Skip to main content
Muita venda acontece sem carrinho de compras: o cliente pergunta pelo WhatsApp, combina pelo direct do Instagram ou fecha por telefone. Nesses casos, o vendedor precisa mandar um jeito de pagar dentro da própria conversa e saber, sem conferir o extrato, quando o pagamento entrou. Esta página mostra como fazer isso com uma cobrança Pix criada pela API.
A API da Finvia não tem um recurso de “link de pagamento” hospedado. Não existe uma rota que devolva uma página pronta para o cliente pagar. Quem monta a mensagem é o seu sistema, com o código copia e cola (copyPaste) e a imagem do QR Code (qrCodeBase64) que a API devolve na criação da cobrança Pix. Para receber em cartão, você precisa de uma página de checkout própria que colete os dados do cartão e chame a API pelo seu servidor.
Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em Integrar com IA.

Implementar este caso com um assistente de IA

Open in Cursor

O cenário

A Doce Encontro Confeitaria faz bolos e doces sob encomenda em Salvador. Todas as encomendas chegam pelo WhatsApp e pelo Instagram: cerca de 350 pedidos por mês, com ticket médio de R$ 180. A confeitaria usa um pequeno sistema interno onde a atendente registra o pedido. Hoje, a atendente manda a chave Pix da empresa, o cliente paga, envia o comprovante por foto e alguém confere o extrato antes de liberar a produção. A Doce Encontro quer:
  • gerar uma cobrança Pix com o valor exato do pedido, direto do sistema interno;
  • enviar o copia e cola e o QR Code na conversa;
  • dar 2 dias para o cliente pagar;
  • saber automaticamente quando o pagamento entrou, sem pedir comprovante.

O que a Finvia resolve

Para o negócio: cada pedido vira uma cobrança Pix com valor, cliente e validade definidos. A API devolve o código copia e cola e a imagem do QR Code, que o sistema da confeitaria envia ao cliente. Quando o cliente paga, a Finvia envia um webhook (charge.paid) ao sistema, que marca o pedido como pago. Não é preciso conferir comprovante, porque a confirmação vem da Finvia.

Arquitetura da solução

O desenho abaixo mostra o caminho de uma encomenda da Doce Encontro, da conversa ao pedido pago. A mesma cobrança em ordem, com os dois desfechos possíveis: pago dentro do prazo ou vencido. Os endpoints do painel não recebem aviso de expiração. Por isso o sistema também controla o prazo e consulta a cobrança no fim da validade.

Passo a passo

1

Cadastre o endpoint de webhook

No painel (https://app.finvia.com.br), em Configurações > Webhooks, cadastre a URL do sistema interno, em HTTPS, por exemplo https://pedidos.doceencontro.exemplo.com.br/webhooks/finvia. Em cada cobrança, envie também um postbackUrl em outra URL, por exemplo https://pedidos.doceencontro.exemplo.com.br/webhooks/finvia/postback. Ele recebe os mesmos eventos e também o charge.updated legado, que avisa quando o Pix é cancelado ou expira. Se a mesma URL estiver nos dois lugares, ela recebe cada evento duas vezes.
2

Gere a cobrança Pix do pedido

A atendente registra a encomenda: bolo de chocolate de 2 kg e um cento de brigadeiros, R$ 210,00 no total. O sistema cria a cobrança com validade de 2 dias:
Repare em customer: sem id, a API aceita name mais email ou phone. Como a conversa é pelo WhatsApp, o telefone basta.
Os itens são physical porque a confeitaria vende produto físico. Com algum item physical, shippingAddress é obrigatório, mesmo quando o cliente retira na loja: nesse caso, a confeitaria usa o endereço de retirada ou o endereço do cliente, conforme a sua política. Sem o endereço, a API responde 400 com Shipping info must be provided for merchants selling physical items.. São obrigatórios postalCode, addressLine1, city, state e country (BRA); addressLine2 e neighborhood são opcionais. O endereço desta página é fictício.
3

Monte a mensagem com o copia e cola

A resposta traz tudo o que a mensagem precisa:
O sistema da confeitaria monta o texto e envia pelo canal da conversa:
O copyPaste vai em uma mensagem separada, sozinho, para o cliente copiar com um toque. Se quiser mandar também a imagem do QR Code, converta o qrCodeBase64 (uma imagem PNG em data URI) em arquivo e envie como foto. Se qrCodeBase64 vier null, envie só o copia e cola.
Para o desenvolvedor: o envio pelo WhatsApp ou Instagram é feito pelo seu sistema, pela ferramenta de atendimento que você já usa. A Finvia não envia mensagens ao cliente. Guarde o id da cobrança junto do pedido DE-3127.
4

Receba a confirmação por webhook

Quando o cliente paga, a Finvia envia charge.paid ao endpoint cadastrado e ao postbackUrl. O sistema confirma o status na API, marca o pedido como pago e avisa a cozinha.
Antes do charge.paid, chegam charge.created e charge.pending. Eles confirmam que a cobrança foi criada, e o sistema pode só registrá-los.
5

Trate o pedido não pago

Se o cliente não pagar em 2 dias, o código expira. Os endpoints do painel não recebem aviso de expiração. O postbackUrl recebe o charge.updated legado (em camelCase, sem id de evento), e o status final pode vir como failed. Mesmo assim, o sistema controla o prazo: ao fim da validade, ele consulta a cobrança com GET /v1/charges/{id}. Se ela não estiver paid, cancela a encomenda ou gera uma cobrança nova, se o cliente ainda quiser o pedido.
6

Devolva o dinheiro quando necessário

Se a confeitaria não puder atender uma encomenda já paga, ela faz o estorno total. No Pix, a devolução é enviada na hora para a conta de origem do cliente. Peça o estorno em até 90 dias do pagamento, que é o prazo das regras do Pix.
A resposta vem com status refunded, e o evento charge.refunded é enviado. Cada cobrança aceita um estorno: um segundo pedido recebe 422 “Já existe um reembolso para esta cobrança”.

Regras e cuidados

Não confie em comprovante enviado pelo cliente. A confirmação válida é o status paid da cobrança na API. Uma foto de comprovante pode ser de outro pagamento, de outro valor ou editada.
Valor em reais. "amount": 210 é R$ 210,00. Enviar 21000 gera uma cobrança de R$ 21.000,00, e o cliente vai ver esse valor no app do banco.
  • Validade. Em cobrança por mensagem, use expirationInDays (mínimo 1). expirationInSeconds aceita a partir de 900 (15 minutos), útil quando o cliente paga durante a conversa.
  • Uma cobrança por pedido. O código copia e cola é ligado a uma cobrança com valor fixo. Se o pedido mudar de valor, gere uma cobrança nova e avise o cliente para usar só o código novo.
  • Cliente identificado. Sem customer.id, envie name e email ou phone. O documento é opcional no Pix.
  • Produto físico. Com algum item physical, shippingAddress é obrigatório. Sem ele, a cobrança não é criada (400).
  • Sem link hospedado. Não existe rota de link de pagamento. Não tente montar uma URL de pagamento a partir do copyPaste.

Variações do caso

Como a API não hospeda uma página de pagamento, a confeitaria precisa de uma página de checkout própria, em HTTPS, que colete os dados do cartão e envie ao servidor dela, que chama POST /v1/charges com credit_card. A mensagem do WhatsApp leva o endereço dessa página, com o código do pedido. A chave secreta nunca vai para o navegador. Se a página for usar 3D Secure, veja 3D Secure.
Para serviços (aula particular, consultoria, conserto já feito), use itens digital, sem shippingAddress. O restante do fluxo é igual.
Use expirationInSeconds com 15 a 30 minutos (900 a 1800) e envie o copia e cola por SMS ou WhatsApp enquanto a ligação continua. O atendente vê a confirmação no sistema assim que o charge.paid chega.
Cadastre o cliente com POST /v1/customers e use o customer.id nas próximas cobranças, para não repetir os dados. Cada pedido continua sendo uma cobrança Pix nova.

Checklist de implementação

  • Endpoint de webhook cadastrado no painel, em HTTPS, e postbackUrl em outra URL em cada cobrança
  • Cobrança Pix criada pelo servidor, nunca pelo navegador ou pelo celular da atendente com a chave secreta
  • amount em reais e igual à soma dos itens
  • Validade definida com expirationInDays ou expirationInSeconds
  • Mensagem com o copyPaste separado, e QR Code opcional a partir de qrCodeBase64
  • id da cobrança salvo junto do pedido
  • Pedido marcado como pago só com status paid confirmado na API
  • Idempotência persistente pelo id do evento
  • Rotina de expiração que consulta a cobrança antes de cancelar o pedido
  • Estorno implementado para pedidos cancelados depois do pagamento

Como homologar

Os cenários aplicáveis são CHG-04 (Pix gerado, com o copia e cola na resposta), CHG-05 (Pix pago e charge.paid recebido), CHG-06 (consulta), CHG-07 (estorno), CHG-08 (recebimento de webhook) e CHG-09 (reenvio de webhook de teste). Se vender produto físico, inclua CHG-10. Com a chave de teste, o Pix é confirmado sozinho: a cobrança nasce pending, com um QR Code fictício que não deve ser pago, e passa para paid cerca de 5 segundos depois, com charge.paid chegando com livemode: false. Não dá para simular a expiração no Modo Teste; para testar o tratamento de outros status, use o reenvio de webhook de teste, que dispara um evento novo e não altera a cobrança. Detalhes no roteiro de homologação.

Veja também

Pix

Validade, QR Code e copia e cola.

Sua primeira cobrança

Uma cobrança Pix completa.

Webhooks de cobrança

Eventos e formato do payload.

Clientes

Cadastro e reaproveitamento de clientes.