Enviar Pix

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>"
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    number: '<string>',
    merchantName: '<string>',
    pixKey: '<string>',
    pixKeyType: '<string>',
    delay: 123,
    replyTo: '<string>',
    replyPrivate: true,
    source: '<string>'
  })
};

fetch('https://api.example.com/api/message/pix/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/message/pix/:instance"

payload = {
    "number": "<string>",
    "merchantName": "<string>",
    "pixKey": "<string>",
    "pixKeyType": "<string>",
    "delay": 123,
    "replyTo": "<string>",
    "replyPrivate": True,
    "source": "<string>"
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/pix/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:       "5511999999999",
    merchantName: "RyzeAPI Tecnologia",
    pixKey:       "12345678901",
    pixKeyType:   "CPF"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/pix/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":       "5511999999999",
        "merchantName": "RyzeAPI Tecnologia",
        "pixKey":       "12345678901",
        "pixKeyType":   "CPF"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":       "5511999999999",
        "merchantName": "RyzeAPI Tecnologia",
        "pixKey":       "12345678901",
        "pixKeyType":   "CPF"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/pix/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/pix/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:       "5511999999999",
    merchantName: "RyzeAPI Tecnologia",
    pixKey:       "12345678000199",
    pixKeyType:   "CNPJ"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/pix/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":       "5511999999999",
        "merchantName": "RyzeAPI Tecnologia",
        "pixKey":       "12345678000199",
        "pixKeyType":   "CNPJ"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":       "5511999999999",
        "merchantName": "RyzeAPI Tecnologia",
        "pixKey":       "12345678000199",
        "pixKeyType":   "CNPJ"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/pix/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/pix/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:       "5511999999999",
    merchantName: "RyzeAPI Tecnologia",
    pixKey:       "contato@ryzeapi.cloud",
    pixKeyType:   "EMAIL"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/pix/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":       "5511999999999",
        "merchantName": "RyzeAPI Tecnologia",
        "pixKey":       "contato@ryzeapi.cloud",
        "pixKeyType":   "EMAIL"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":       "5511999999999",
        "merchantName": "RyzeAPI Tecnologia",
        "pixKey":       "contato@ryzeapi.cloud",
        "pixKeyType":   "EMAIL"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/pix/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us).

string

obrigatório

Nome do beneficiário exibido no cartão visual do PIX (acima da chave).

string

obrigatório

Chave PIX (CPF, CNPJ, e-mail, telefone ou chave aleatória).

string

obrigatório

Tipo da chave. Valores aceitos: CPF, CNPJ, EMAIL, PHONE, RANDOM.

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.

string

ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.

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.

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

HTTP	Status interno	Mensagem
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`
400	`invalid_number`	`Invalid phone number format: <detalhe>`
400	`invalid_request`	(validação `oneof` ou outro motivo)
404	,	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envelope de erro:

{
  "success": false,
  "error": { "message": "PixKeyType is required" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

PIX com Chave de CPF

PIX com Chave de CNPJ

PIX com Chave de Email

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

​Descrição

​Exemplos

​PIX com Chave de CPF

​PIX com Chave de CNPJ

​PIX com Chave de Email

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

PIX com Chave de CPF

PIX com Chave de CNPJ

PIX com Chave de Email

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros