Implementar este caso com um assistente de IA
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.4
Receba a confirmação por webhook
Quando o cliente paga, a Finvia envia Antes do
charge.paid ao endpoint cadastrado e ao postbackUrl. O sistema confirma o status na API, marca o pedido como pago e avisa a cozinha.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
- Validade. Em cobrança por mensagem, use
expirationInDays(mínimo1).expirationInSecondsaceita a partir de900(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, envienameeemailouphone. 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
E se o cliente quiser pagar no cartão?
E se o cliente quiser pagar no cartão?
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.E se a venda for de serviço, sem entrega?
E se a venda for de serviço, sem entrega?
Para serviços (aula particular, consultoria, conserto já feito), use itens
digital, sem shippingAddress. O restante do fluxo é igual.E se a venda for por telefone, com o cliente esperando na linha?
E se a venda for por telefone, com o cliente esperando na linha?
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.E se o mesmo cliente comprar toda semana?
E se o mesmo cliente comprar toda semana?
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
postbackUrlem outra URL em cada cobrança - Cobrança Pix criada pelo servidor, nunca pelo navegador ou pelo celular da atendente com a chave secreta
-
amountem reais e igual à soma dos itens - Validade definida com
expirationInDaysouexpirationInSeconds - Mensagem com o
copyPasteseparado, e QR Code opcional a partir deqrCodeBase64 -
idda cobrança salvo junto do pedido - Pedido marcado como pago só com
statuspaidconfirmado na API - Idempotência persistente pelo
iddo 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 echarge.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.

