pix na conversa
Botão Pix no WhatsApp por API para o seu SaaS cobrar na conversa
Com o botão Pix no WhatsApp por API, o seu SaaS manda a cobrança onde o cliente já está conversando: chave Pix com cópia em um toque, valor opcional e a confirmação de entrega pelo webhook.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Um endpoint, quatro campos
sessionId, to, content e pixKey bastam. pixAmount, pixMessage e footer completam a cobrança quando você precisa.
Tipo de chave detectado
Na API não-oficial, CPF, CNPJ, e-mail, telefone ou chave aleatória são reconhecidos pelo formato, sem campo extra.
Também na API Oficial
Dentro da janela de 24 horas, a mesma chamada sai como texto com a chave em linha própria, o valor e a mensagem.
Um botão Pix no WhatsApp por API encurta a distância entre “quanto ficou?” e “paguei”. Em software de cobrança, de agendamento com sinal ou de delivery, a cobrança costuma sair do seu sistema por e-mail ou por um link que o cliente precisa abrir em outra tela. Quando a mensagem chega no WhatsApp com a chave pronta para copiar, o cliente final faz o pagamento sem sair da conversa em que já estava falando com a loja, a clínica ou a escola.
Na API de WhatsApp da D-API, essa cobrança é uma chamada só: POST /api/v1/interactive/send/pix. O seu SaaS informa a chave do seu cliente, o valor quando houver e uma mensagem de referência. O resto da integração (autenticação, sessionId, webhooks) é o mesmo que você já usa para texto.
Onde o botão Pix entra no seu produto
Alguns fluxos em que clientes SaaS usam a cobrança na conversa:
- Agendamento com sinal. O paciente escolhe o horário, o sistema da clínica reserva o slot e manda o Pix do sinal na mesma conversa.
- Delivery e pedidos por WhatsApp. O pedido fecha no atendimento e o restaurante envia a chave com o valor total para pagamento antecipado.
- Régua de cobrança. O software de cobrança dispara o lembrete de vencimento já com a chave e o valor da parcela.
- Mensalidade de escola ou academia. A secretaria manda a cobrança do mês para o responsável, com a referência do aluno em
pixMessage.
Em todos eles, o ganho para o seu cliente é o mesmo: menos atrito entre a conversa e o pagamento, sem depender de link externo.
Como enviar o botão Pix pela API
Os campos obrigatórios são sessionId, to, content e pixKey. Os opcionais são pixAmount (número, mínimo 0), pixMessage, footer e mentionAll.
curl -X POST https://api.d-api.cloud/api/v1/interactive/send/pix \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "clinica-4821",
"to": "5511999999999",
"content": "Seu horário de terça às 14:30 está reservado. Para confirmar, pague o sinal pelo Pix.",
"pixKey": "[email protected]",
"pixAmount": 50,
"pixMessage": "Sinal consulta 14:30",
"footer": "Clínica Exemplo"
}'
A resposta de sucesso traz messageId, messageType: "pix", a pixKey e o pixAmount enviados. Guarde o messageId junto da cobrança no seu banco: é ele que liga a mensagem aos eventos de entrega e leitura.
Chave, valor e mensagem: o que cada campo faz
Na API não-oficial, o tipo da chave é deduzido do formato, sem campo dedicado:
| Formato da chave | Tipo reconhecido |
|---|---|
| 11 dígitos | CPF |
| 14 dígitos | CNPJ |
| Texto com arroba e ponto | |
| Começa com +55, ou 10 a 11 dígitos | Telefone |
| UUID (8-4-4-4-12) | Chave aleatória |
Pontos, traços, barras e espaços são ignorados na detecção, então 123.456.789-00 e 12345678900 chegam ao mesmo resultado. Formato fora dessa lista é tratado como chave aleatória, por isso vale validar a chave no cadastro do seu cliente, antes do primeiro envio.
O pixAmount define o comportamento da mensagem. Com valor maior que zero, a cobrança sai com o valor. Sem valor, ou com zero, sai só com a cópia da chave. O valor não pode ser negativo: a validação da rota recusa.
O pixMessage é a referência da cobrança. Use algo que o seu cliente reconheça no extrato e que o seu sistema consiga casar depois, como o número do pedido ou da parcela.
Botão Pix na API Oficial
Se parte da sua base usa a API Oficial, a mesma rota funciona, com duas diferenças que a referência deixa explícitas. A primeira: o envio só vale dentro da janela de 24 horas aberta pela última mensagem do contato. A segunda: como a Meta não oferece botão de copiar em mensagem livre, a D-API converte a cobrança em texto. O content abre a mensagem, a linha seguinte traz “Chave Pix:” com a chave, depois o valor formatado em reais e o pixMessage, e o footer fecha.
Na prática, o seu código chama o mesmo endpoint para todos os clientes, e o que muda é a apresentação no aparelho do cliente final. Fora da janela de 24 horas, a cobrança iniciada pela empresa na API Oficial depende de template aprovado, com as tarifas da Meta cobradas na conta do seu cliente. O artigo sobre cobrança de mensagens de serviço explica essa regra.
Acompanhando entrega e pagamento
O ciclo completo de uma cobrança pelo WhatsApp tem três sinais, e só dois deles vêm da D-API:
- Enviada. A resposta da chamada traz o
messageId. - Entregue e lida. Os eventos
message.deliveredemessage.readchegam no webhook com o mesmomessage_id. Os dois passam por deduplicação de 30 segundos por mensagem, conforme a documentação da D-API. - Paga. Vem do banco ou do provedor de pagamentos do seu cliente. A D-API envia a mensagem e não processa o pagamento.
Com os dois primeiros sinais, a sua régua de cobrança sabe se vale reenviar ou escalar para uma ligação. Com o terceiro, o seu sistema dá baixa e pode mandar a confirmação pela mesma conversa.
Boas práticas para cobrança em escala
- Cobrança idempotente. Gere uma chave de idempotência por parcela no seu lado e não envie o mesmo Pix duas vezes se o job reprocessar.
- Envio fora do request. Régua de cobrança com milhares de parcelas é trabalho de fila no seu backend, com limite de concorrência por conexão e retentativa só depois de conferir se a primeira tentativa falhou de fato.
- Contexto antes da chave. Um
contentque diz o que está sendo cobrado reduz dúvida e resposta do tipo “isso é golpe?”. - Combine com outros formatos. Uma vitrine em carrossel leva à escolha do produto, e o Pix fecha a venda. O artigo sobre mensagens interativas mostra como esses formatos se encaixam.
Na API não-oficial, a cobrança da D-API é por conexão, sem custo por mensagem, então uma régua que manda lembrete e Pix para cada parcela não muda a sua fatura.
Time D-API. Atualizado em .
Perguntas frequentes
A D-API confirma quando o cliente pagou o Pix?
Não. O endpoint envia a mensagem de cobrança com a chave. A baixa do pagamento vem do seu banco ou do seu provedor de pagamentos, e o seu sistema atualiza o pedido.
Posso mandar o botão Pix sem valor definido?
Sim. pixAmount é opcional. Sem valor, a mensagem sai só com a cópia da chave e o cliente digita o valor no app do banco.
Preciso informar se a chave é CPF, e-mail ou aleatória?
Não existe campo para isso. Na API não-oficial, o tipo é deduzido do formato da chave: 11 dígitos como CPF, 14 como CNPJ, texto com arroba como e-mail, formato UUID como chave aleatória.
Funciona para o cliente do meu SaaS que usa a API Oficial?
Funciona dentro da janela de 24 horas. Como a Meta não tem botão de copiar em mensagem livre, a cobrança sai como texto com a chave Pix numa linha própria, o valor formatado em reais e a mensagem.
Como sei que a cobrança chegou ao cliente?
A resposta do envio traz o messageId. Os eventos message.delivered e message.read chegam no webhook com esse mesmo message_id.