Pular para o conteúdo 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 ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

​
Descrição

Envia uma mensagem com cartão visual de PIX no chat do WhatsApp, exibindo o nome do beneficiário, o tipo da chave e a própria chave. O botão funciona como um “copiar chave” com design de PIX, ao tocar, o destinatário copia a chave para a área de transferência e cola no app do banco para pagar. Não abre tela de pagamento, não cria cobrança e não há callback de confirmação, é apenas a apresentação visual da chave em formato amigável e clicável.

​
Exemplos

​
PIX com Chave de CPF

Envia o botão PIX usando uma chave do tipo CPF. Envie apenas dígitos (sem pontos ou traços). 
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 com Chave de CNPJ

Envia o botão PIX usando uma chave do tipo CNPJ. Envie apenas dígitos (sem pontos, traços ou 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 com Chave de Email

Envia o botão PIX usando uma chave do tipo 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"
  }'

​
Resposta de sucesso

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"
    }
  }
}
O botão apenas copia a chave PIX para a área de transferência do destinatário, não abre a tela de pagamento do banco nem inicia uma cobrança. O pagamento é feito manualmente pelo destinatário no app do próprio banco, e não há callback de “pago” via WhatsApp.

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: $Instance_Name).

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
number
string
obrigatório
Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us).
​
merchantName
string
obrigatório
Nome do beneficiário exibido no cartão visual do PIX (acima da chave).
​
pixKey
string
obrigatório
Chave PIX (CPF, CNPJ, e-mail, telefone ou chave aleatória).
​
pixKeyType
string
obrigatório
Tipo da chave. Valores aceitos: CPF, CNPJ, EMAIL, PHONE, RANDOM.
​
delay
int
padrão:"0"
Tempo em segundos para aguardar antes de enviar. Durante o intervalo, o servidor envia o indicador de “digitando…” ao destinatário.
​
replyTo
string
ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.
​
replyPrivate
boolean
padrão:"false"
Quando true e replyTo aponta para uma mensagem originária de um grupo, a resposta é redirecionada para o privado do autor original.
​
source
string
padrão:"api"
Identificador de origem para rastreabilidade (ex.: crm, checkout, n8n).

​
Notas

  • O pixKeyType é validado por oneof, se enviar um valor fora de CPF | CNPJ | EMAIL | PHONE | RANDOM, a request é rejeitada com 400.
  • Para chaves CPF/CNPJ envie apenas dígitos (sem pontos, traços ou barras): 12345678901 ou 12345678000199.
  • Para PHONE, use o formato internacional sem + (ex.: 5511999999999).
  • Para RANDOM, use a UUID que o banco gerou (ex.: aabbccdd-1234-5678-90ab-cdef01234567).
  • Esse endpoint não cria QR Code Brcode nem registra cobrança, é apenas a representação visual do pedido com chave PIX clicável.

​
Erros

HTTPStatus internoMensagem
400,Instance name is required
400,Invalid request: <detalhe>
400,Number is required
400,MerchantName is required
400,PixKey is required
400,PixKeyType is required
400invalid_numberInvalid phone number format: <detalhe>
400invalid_request(validação oneof ou outro motivo)
404,Instance not found
500send_failedFailed to send message: <reason>
503disconnectedInstance is not connected to WhatsApp
Envelope de erro: 
{
  "success": false,
  "error": { "message": "PixKeyType is required" }
}