Pular para o conteúdo
D-APITestar grátis

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 E-mail
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:

  1. Enviada. A resposta da chamada traz o messageId.
  2. Entregue e lida. Os eventos message.delivered e message.read chegam no webhook com o mesmo message_id. Os dois passam por deduplicação de 30 segundos por mensagem, conforme a documentação da D-API.
  3. 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 content que 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.