Saltar al contenido principal
POST
/
api
/
message
/
pix
/
:instance
Enviar PIX
curl --request POST \
  --url https://api.example.com/api/message/pix/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "merchantName": "<string>",
  "pixKey": "<string>",
  "pixKeyType": "<string>",
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'
Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

​
Descripción

Envía un mensaje con una tarjeta visual de PIX en el chat de WhatsApp, mostrando el nombre del beneficiario, el tipo de clave y la clave en sí. El botón funciona como un “copiar clave” con estilo PIX, al tocarlo, el destinatario copia la clave al portapapeles y la pega en su app bancaria para pagar. No abre una pantalla de pago, no crea un cobro, y no hay callback de confirmación, es solo la presentación visual de la clave en un formato amigable y clicable.

​
Ejemplos

​
PIX con clave CPF

Envía el botón PIX usando una clave CPF. Envía solo dígitos (sin puntos ni guiones). 
curl -X POST "https://ryzeapi.cloud/api/message/pix/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":       "5511999999999",
    "merchantName": "RyzeAPI Tecnologia",
    "pixKey":       "12345678901",
    "pixKeyType":   "CPF"
  }'

​
PIX con clave CNPJ

Envía el botón PIX usando una clave CNPJ. Envía solo dígitos (sin puntos, guiones ni barras). 
curl -X POST "https://ryzeapi.cloud/api/message/pix/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":       "5511999999999",
    "merchantName": "RyzeAPI Tecnologia",
    "pixKey":       "12345678000199",
    "pixKeyType":   "CNPJ"
  }'

​
PIX con clave Email

Envía el botón PIX usando una clave EMAIL. 
curl -X POST "https://ryzeapi.cloud/api/message/pix/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":       "5511999999999",
    "merchantName": "RyzeAPI Tecnologia",
    "pixKey":       "contato@ryzeapi.cloud",
    "pixKeyType":   "EMAIL"
  }'

​
Respuesta exitosa

200 OK
{
  "success": true,
  "message": "Message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "outgoing",
    "messageType": "pix",
    "content":     "",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}
El botón solo copia la clave PIX al portapapeles del destinatario, no abre la pantalla de pago del banco ni inicia un cobro. El pago lo hace manualmente el destinatario en su propia app bancaria, y no hay callback de “pagado” vía WhatsApp.

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia (p. ej., $Instance_Name).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
number
string
requerido
Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us).
​
merchantName
string
requerido
Nombre del beneficiario mostrado en la tarjeta visual de PIX (sobre la clave).
​
pixKey
string
requerido
Clave PIX (CPF, CNPJ, email, teléfono o clave aleatoria).
​
pixKeyType
string
requerido
Tipo de clave. Valores aceptados: CPF, CNPJ, EMAIL, PHONE, RANDOM.
​
delay
int
predeterminado:"0"
Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” al destinatario.
​
replyTo
string
ID del mensaje a citar (respuesta). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos.
​
replyPrivate
boolean
predeterminado:"false"
Cuando es true y replyTo apunta a un mensaje originado en un grupo, la respuesta se redirige al chat privado del autor original.
​
source
string
predeterminado:"api"
Identificador de origen para trazabilidad (p. ej., crm, checkout, n8n).

​
Notas

  • El pixKeyType se valida con oneof, si envías un valor fuera de CPF | CNPJ | EMAIL | PHONE | RANDOM, la solicitud se rechaza con 400.
  • Para claves CPF/CNPJ, envía solo dígitos (sin puntos, guiones ni barras): 12345678901 o 12345678000199.
  • Para PHONE, usa el formato internacional sin + (p. ej., 5511999999999).
  • Para RANDOM, usa el UUID generado por el banco (p. ej., aabbccdd-1234-5678-90ab-cdef01234567).
  • Este endpoint no crea un código QR Brcode ni registra un cobro, es solo la representación visual del pedido con una clave PIX clicable.

​
Errores

HTTPStatus internoMensaje
400,Instance name is required
400,Invalid request: <detail>
400,Number is required
400,MerchantName is required
400,PixKey is required
400,PixKeyType is required
400invalid_numberInvalid phone number format: <detail>
400invalid_request(validación oneof u otro motivo)
404,Instance not found
500send_failedFailed to send message: <reason>
503disconnectedInstance is not connected to WhatsApp
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "PixKeyType is required" }
}