Solicitar pagamento
POST /send/request-payment
Envia uma solicitação de pagamento com o botão nativo "Revisar e pagar" do WhatsApp. O fluxo suporta PIX (estático, dinâmico ou desabilitado), boleto, link de pagamento e cartão, combinando tudo em uma única mensagem interativa.
Como funciona
- Define o valor em
amount(BRL por padrão) e opcionalmente personaliza título, texto e nota adicional. - Por padrão exige
pixKey. - O arquivo apontado por
fileUrlé anexado como documento (boleto ou fatura em PDF, por exemplo). paymentLinkhabilita o botão externo.- Para cobrar um pedido recebido pelo WhatsApp, informe
orderMessageIdcom o ID da mensagemOrderMessagedesse mesmo contato. A API obtém itens, moeda e total do pedido;amountnão é necessário nesse caso. Ainda é preciso informar um método de pagamento.
Campos comuns
Este endpoint também suporta os campos padrão: delay, readchat, readmessages, replyid,
mentions, track_source, track_id e async.
Autenticação
[
{
"token": []
}
]
{
"token": {
"name": "token",
"type": "apiKey",
"in": "header"
}
}
Corpo da requisição
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`).",
"example": "5511999999999"
},
"orderMessageId": {
"type": "string",
"description": "ID de uma `OrderMessage` recebida do mesmo contato. Vincula a cobrança ao pedido real."
},
"title": {
"type": "string",
"description": "Título que aparece no cabeçalho do fluxo",
"example": "Detalhes do pedido"
},
"text": {
"type": "string",
"description": "Mensagem exibida no corpo do fluxo",
"example": "Pedido #123 pronto para pagamento"
},
"footer": {
"type": "string",
"description": "Texto do rodapé da mensagem",
"example": "Loja Exemplo"
},
"itemName": {
"type": "string",
"description": "Nome do item principal listado no fluxo",
"example": "Assinatura Plano Ouro"
},
"invoiceNumber": {
"type": "string",
"description": "Identificador ou número da fatura",
"example": "PED-123"
},
"amount": {
"type": "number",
"format": "float",
"description": "Valor da cobrança (em BRL por padrão)",
"example": 199.9
},
"pixKey": {
"type": "string",
"description": "Chave PIX estático (CPF/CNPJ/telefone/email/EVP)",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"pixType": {
"type": "string",
"description": "Tipo da chave PIX (`CPF`, `CNPJ`, `PHONE`, `EMAIL`, `EVP`). Padrão `EVP`",
"example": "EVP"
},
"pixName": {
"type": "string",
"description": "Nome do recebedor exibido no fluxo (padrão usa o nome do perfil da instância)",
"example": "Loja Exemplo"
},
"paymentLink": {
"type": "string",
"description": "URL externa para checkout (somente dominios homologados; veja lista acima)",
"example": "https://pagamentos.exemplo.com/checkout/abc"
},
"fileUrl": {
"type": "string",
"description": "URL ou caminho (base64) do documento a ser anexado (ex.: boleto PDF)",
"example": "https://cdn.exemplo.com/boleto-123.pdf"
},
"fileName": {
"type": "string",
"description": "Nome do arquivo exibido no WhatsApp ao anexar `fileUrl`",
"example": "boleto-123.pdf"
},
"boletoCode": {
"type": "string",
"description": "Linha digitável do boleto (habilita o método boleto automaticamente)",
"example": "34191.79001 01043.510047 91020.150008 5 91070026000"
},
"replyid": {
"type": "string",
"description": "ID da mensagem que será respondida"
},
"mentions": {
"type": "string",
"description": "Números mencionados separados por vírgula"
},
"delay": {
"type": "integer",
"description": "Atraso em milissegundos antes do envio (exibe \"digitando...\" no WhatsApp)"
},
"readchat": {
"type": "boolean",
"description": "Marca o chat como lido após enviar a mensagem"
},
"readmessages": {
"type": "boolean",
"description": "Marca mensagens recentes como lidas após o envio"
},
"async": {
"type": "boolean",
"description": "Enfileira o envio para processamento assíncrono"
},
"track_source": {
"type": "string",
"description": "Origem de rastreamento (ex.: chatwoot, crm-interno)"
},
"track_id": {
"type": "string",
"description": "Identificador de rastreamento (aceita valores duplicados)"
}
},
"required": [
"number"
],
"anyOf": [
{
"required": [
"amount"
]
},
{
"required": [
"orderMessageId"
]
}
]
},
"examples": {
"pedidoRecebido": {
"summary": "Cobrar um pedido enviado pelo cliente",
"value": {
"number": "5511999999999",
"orderMessageId": "3EB0ID_DO_PEDIDO",
"pixKey": "123e4567-e89b-12d3-a456-426614174000",
"text": "Confira os dados para pagamento"
}
},
"pixSimples": {
"summary": "PIX simples",
"value": {
"number": "5511999999999",
"amount": 199.9,
"text": "Pedido #123 pronto para pagamento",
"pixKey": "123e4567-e89b-12d3-a456-426614174000",
"pixType": "EVP"
}
},
"pixEBoleto": {
"summary": "PIX + boleto",
"value": {
"number": "5511999999999",
"amount": 349.5,
"text": "Pedido #457 com boleto",
"pixKey": "12345678000190",
"pixType": "CNPJ",
"pixName": "Loja Exemplo LTDA",
"boletoCode": "34191.79001 01043.510047 91020.150008 5 91070026000",
"additionalNote": "Pague via PIX ou utilize o boleto em anexo"
}
},
"completo": {
"summary": "PIX + boleto + link",
"value": {
"number": "5511888888888",
"title": "Assinatura Premium",
"text": "Plano anual disponível para pagamento",
"footer": "footer",
"invoiceNumber": "INV-789",
"itemName": "Bolo XYZ",
"amount": 599,
"pixKey": "123e4567-e89b-12d3-a456-426614174000",
"pixType": "EVP",
"pixName": "Empresa Exemplo",
"boletoCode": "23793.38128 60000.000123 45670.000012 3 45670000012345",
"fileUrl": "https://cdn.exemplo.com/boleto-inv-789.pdf",
"fileName": "Clique para abrir o PDF.pdf",
"paymentLink": "https://payment-link.pagar.me/checkout/inv-789"
}
}
}
}
}
}
Respostas
{
"200": {
"description": "Solicitação de pagamento enviada com sucesso",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Message"
},
{
"type": "object",
"properties": {
"response": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Payment request sent successfully"
}
}
}
}
}
]
}
}
}
},
"400": {
"description": "Requisição inválida",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Missing pixKey or pixCode"
}
}
}
}
}
},
"401": {
"description": "Não autorizado",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Invalid token"
}
}
}
}
}
},
"500": {
"description": "Erro interno do servidor",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Failed to send payment request"
}
}
}
}
}
}
}
#/components/schemas/Message
{
"type": "object",
"description": "Representa uma mensagem trocada no sistema",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "ID único interno da mensagem (formato r + 7 caracteres hex aleatórios)"
},
"messageid": {
"type": "string",
"description": "ID original da mensagem no provedor"
},
"chatid": {
"type": "string",
"description": "ID da conversa relacionada"
},
"sender": {
"type": "string",
"description": "ID do remetente da mensagem"
},
"senderName": {
"type": "string",
"description": "Nome exibido do remetente"
},
"isGroup": {
"type": "boolean",
"description": "Indica se é uma mensagem de grupo",
"default": false
},
"fromMe": {
"type": "boolean",
"description": "Indica se a mensagem foi enviada pelo usuário",
"default": false
},
"messageType": {
"type": "string",
"description": "Tipo de conteúdo da mensagem"
},
"source": {
"type": "string",
"description": "Plataforma de origem da mensagem"
},
"messageTimestamp": {
"type": "integer",
"description": "Timestamp original da mensagem em milissegundos",
"default": 0
},
"status": {
"type": "string",
"description": "Status do ciclo de vida da mensagem.\nExemplos comuns: `Queued`, `Canceled`, `Failed`, `Sent`, `Delivered`, `Read`.\n"
},
"text": {
"type": "string",
"description": "Texto original da mensagem",
"default": ""
},
"quoted": {
"type": "string",
"description": "ID da mensagem citada/respondida",
"default": ""
},
"edited": {
"type": "string",
"description": "Histórico de edições da mensagem",
"default": ""
},
"reaction": {
"type": "string",
"description": "ID da mensagem reagida",
"default": ""
},
"vote": {
"type": "string",
"description": "Dados de votação de enquete e listas",
"default": ""
},
"convertOptions": {
"type": "string",
"description": "Conversão de opções da mensagem, lista, enquete e botões",
"default": ""
},
"buttonOrListid": {
"type": "string",
"description": "ID do botão ou item de lista selecionado",
"default": ""
},
"owner": {
"type": "string",
"description": "Dono da mensagem",
"default": ""
},
"error": {
"type": "string",
"description": "Mensagem de erro caso o envio tenha falhado",
"default": ""
},
"content": {
"description": "Conteúdo bruto da mensagem (JSON serializado ou texto)",
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string",
"description": "Texto bruto quando não for JSON"
}
]
},
"wasSentByApi": {
"type": "boolean",
"description": "Indica se a mensagem foi enviada via API"
},
"sendFunction": {
"type": "string",
"description": "Função usada para enviar a mensagem (quando enviada via API)"
},
"sendPayload": {
"description": "Payload usado no envio quando disponível. Dados de mídia em base64 são omitidos.",
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string",
"description": "Texto bruto quando não for JSON"
}
]
},
"fileURL": {
"type": "string",
"description": "URL ou referência de arquivo da mensagem"
},
"callPeer": {
"type": "object",
"description": "Contato conhecido associado a uma ligação, quando disponível em `messageType: call`.",
"properties": {
"jid": {
"type": "string"
},
"name": {
"type": "string"
},
"imagePreviewUrl": {
"type": "string"
}
}
},
"send_folder_id": {
"type": "string",
"description": "Pasta associada ao envio (quando aplicável)"
},
"track_source": {
"type": "string",
"description": "Origem de rastreamento"
},
"track_id": {
"type": "string",
"description": "ID de rastreamento (pode repetir)"
},
"ai_metadata": {
"type": "object",
"description": "Metadados do processamento por IA",
"properties": {
"agent_id": {
"type": "string",
"description": "ID do agente de IA responsável"
},
"request": {
"type": "object",
"description": "Dados da requisição à API de IA",
"properties": {
"messages": {
"type": "array",
"description": "Histórico de mensagens enviadas para a API"
},
"tools": {
"type": "array",
"description": "Ferramentas disponíveis para o agente"
},
"options": {
"type": "object",
"description": "Opções de configuração da API",
"properties": {
"model": {
"type": "string"
},
"temperature": {
"type": "number"
},
"maxTokens": {
"type": "integer"
},
"topP": {
"type": "number"
},
"frequencyPenalty": {
"type": "number"
},
"presencePenalty": {
"type": "number"
}
}
}
}
},
"response": {
"type": "object",
"description": "Resposta da API de IA",
"properties": {
"choices": {
"type": "array",
"description": "Resultados retornados pela API"
},
"toolResults": {
"type": "array",
"description": "Resultados da execução de ferramentas"
},
"error": {
"type": "string",
"description": "Mensagem de erro, se houver"
}
}
}
}
},
"sender_pn": {
"description": "JID PN resolvido do remetente (quando disponível)",
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sender_lid": {
"description": "LID original do remetente (quando disponível)",
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sender_image_preview_url": {
"type": "string",
"format": "uri",
"description": "URL temporária de preview do remetente, quando conhecida. A hidratação desta versão preenche mensagens recebidas em grupos; o campo pode ser omitido. Não provoca consulta de foto ao WhatsApp na listagem."
}
}
}