Para o negócio: este é o mesmo caminho que o seu checkout vai percorrer em produção. Os cenários feitos aqui servem de base para os cenários CHG-01 a CHG-09 do roteiro de homologação, a etapa recomendada antes de ir para produção.
O que você vai precisar
- A chave secreta de teste (
sk_test_), gerada por um usuário Owner ou Manager. Como gerar: Credenciais e ambientes. - Pix habilitado na conta (taxa de Pix em reais configurada). Sem isso, a criação do Pix responde
422comFees not configured, também no Modo Teste. - Terminal com
curl, ou Node.js 18 ou superior. - Uma URL pública com HTTPS que aponte para a sua máquina, para receber os webhooks. No desenvolvimento, ferramentas como o ngrok fazem isso (
ngrok http 3000).
Visão geral do fluxo
O desenho abaixo mostra a sequência completa do tutorial com Pix no sandbox, da conexão à consulta final.1
Autenticar e testar a conexão
Monte o cabeçalho Basic e chame
GET /v1/payment-methods.2
Subir o receptor de webhooks
Um servidor mínimo que recebe os avisos da Finvia e responde com status
2xx.3
Criar a cobrança Pix
POST /v1/charges com postbackUrl apontando para o seu receptor.4
Mostrar o QR Code
Use
qrCodeBase64 e copyPaste da resposta.5
Receber os eventos
Veja
charge.created e charge.pending chegarem e, cerca de 5 segundos depois, o charge.paid: no Modo Teste, o Pix é confirmado sozinho.6
Simular outros status
Use a rota de simulação de webhook do sandbox para testar o tratamento de estorno, recusa e falha.
7
Consultar a cobrança
GET /v1/charges/{id} para confirmar o estado.8
Repetir com cartão de crédito
O resultado do cartão vem na própria resposta.
1. Autentique e teste a conexão
A API usa HTTP Basic: a chave vai como usuário, a senha fica vazia. Você convertesua_chave: (com os dois pontos no final) para Base64 e envia no cabeçalho Authorization.
Configure as variáveis de ambiente:
200 significa que a chave e o cabeçalho estão corretos.
id, name, countries, currencies e description.
Recebeu
200 e uma lista em JSON? A autenticação está pronta. Se recebeu 401 com {"message": "Unauthorized", "statusCode": 401}, decodifique o Base64 e confira se ele termina em :.2. Suba o receptor de webhooks
O webhook é a notificação que a Finvia envia ao seu servidor quando algo muda na cobrança. No Pix, ele é a única forma de saber que o cliente pagou sem ficar consultando a API. Este servidor mínimo em Express recebe as notificações e responde200 antes de processar. Ele descarta repetições com a receita de deduplicação e, além disso, só libera um pedido que ainda não foi liberado. Essa segunda proteção cobre o caso de o mesmo aviso chegar com outro id.
server.mjs
https://abc123.ngrok.io. O endereço do seu receptor será https://abc123.ngrok.io/webhooks/finvia.
3. Crie a cobrança Pix
Esta é a cobrança do exemplo de início rápido: R$ 100,00 em Pix, com validade de 1 dia, para um produto digital. ApostbackUrl aponta para o seu receptor.
201:
"amount": 100 significa R$ 100,00.
Pontos de atenção nesta chamada:
Como escolher a validade do QR Code: veja o guia de Pix.
4. Mostre o QR Code
A resposta já traz tudo o que o cliente precisa para pagar:qrCodeBase64: a imagem PNG do QR Code em formato data URI, pronta para usar comosrcde uma imagem.copyPaste: o código Pix copia e cola, para quem paga pelo celular.
copyPaste e o qrCodeBase64 são fictícios. Não tente pagar esse código em um aplicativo de banco: a confirmação acontece sozinha, como mostra o passo seguinte.
5. Receba os webhooks
O que chega ao receptor
Assim que a cobrança é gravada, sai ocharge.created. Logo depois, com o QR Code gerado, sai o charge.pending. Os dois chegam à postbackUrl e aos endpoints cadastrados no painel (Configurações > Webhooks). Os eventos de cada canal estão na tabela de eventos por canal.
data completo está em Webhooks de cobrança.
O Pix de teste é pago sozinho
No Modo Teste não há nada para pagar nem botão de simulação. Cerca de 5 segundos depois da criação, a cobrança passa sozinha parapaid: paidAt é preenchido e paymentDetails.endToEndId recebe um valor de teste. Nesse momento chega o charge.paid, com o mesmo id de cobrança devolvido na criação. É nesse evento que você libera o pedido.
O
charge.paid com o mesmo id retornado na criação é a evidência do cenário CHG-05 da homologação. Se, em casos raros, a cobrança não virar paid em alguns segundos, crie outra.No sandbox, todo Pix é aprovado. Não dá para simular expiração ou falha de um Pix. Para testar o tratamento desses casos, use a simulação de webhook abaixo.
Separe eventos de teste e de produção
Os endpoints de webhook não têm modo: a sua conta tem uma única lista, que recebe tanto os eventos de teste quanto os de produção. O painel não tem uma lista separada para o Modo Teste. Por isso, a integração precisa separar os eventos pelo payload:
A
postbackUrl é definida em cada cobrança. Se quiser URLs diferentes por ambiente, informe uma postbackUrl de teste nas cobranças criadas com a chave de teste.
Simule outros status
Para testar como o seu receptor reage a estorno, recusa ou falha, use a rota de simulação de webhook, disponível só para cobranças de teste. Ela não reenvia o evento original e não altera a cobrança: gera um evento novocharge.{status}, com id novo, para a postbackUrl e para os endpoints da sua conta.
201:
Um roteiro útil de simulação:
{"status": "paid"}: confira se o receptor responde2xxe se o pedido, já liberado pelocharge.paidreal, não é liberado de novo. O evento simulado temidnovo, então quem segura a duplicidade aqui é a checagem do pedido.{"status": "refunded"}: confira se o pedido é marcado como estornado.{"status": "refused"}e{"status": "failed"}: confira se o pedido é marcado como não pago.
O payload simulado não é idêntico ao real: traz campos a mais e não traz
anticipation_fee_estimated. Use a simulação para testar conectividade e o tratamento de cada evento, e não como referência de formato. O formato real está em Webhooks de cobrança.6. Consulte a cobrança
Os webhooks não têm assinatura HMAC (Webhooks), então confirme o estado da cobrança na API antes de uma ação crítica. A consulta também é o caminho quando o seu receptor ficou fora do ar.200 traz o objeto completo da cobrança em camelCase: id, status, amount, currency, spread, net, customer, paymentMethod, merchantId, paymentDetails, metadata, paidAt, createdAt e updatedAt. Nas respostas de consulta, as chaves de metadata voltam em camelCase. Veja Metadata.
7. Repita com cartão de crédito
No cartão, a aprovação ou a recusa vem na própria resposta da criação. Os webhooks chegam em seguida, como complemento:charge.paid na aprovação, charge.refused (status refused) ou charge.failed (status failed) na recusa.
O desenho abaixo mostra os dois caminhos da cobrança de cartão no tutorial, aprovada e recusada.
No Modo Teste, o resultado depende só do número do cartão:
A tabela completa e as regras estão em Cartões de teste. Use uma conta sem 3D Secure obrigatório para testar a recusa: com 3DS ou antifraude ligados, a recusa pode vir dessas etapas, com outro
reason.
201 aprovada:
201 recusada, com o cartão 4444333322221112:
charge.refused ou charge.failed sai no máximo uma vez por cobrança, para os endpoints e para a postbackUrl. O envelope padrão não traz o motivo: ele está no reason da resposta e na consulta da cobrança.
Erros comuns
Mais detalhes em Erros e como tratar.
Perguntas frequentes
Preciso cadastrar o cliente antes de criar a cobrança?
Preciso cadastrar o cliente antes de criar a cobrança?
Não. Ao enviar
name e email (ou phone) dentro de customer, a API cria ou localiza o cliente na mesma chamada. O cadastro prévio com POST /v1/customers é útil quando o cliente volta a comprar, guarda cartão ou assina um plano: aí basta enviar o customer.id.Posso usar só a postbackUrl, sem cadastrar webhook no painel?
Posso usar só a postbackUrl, sem cadastrar webhook no painel?
Pode, para eventos de cobrança. Os eventos que cada canal recebe estão na tabela de eventos por canal. Os eventos de assinatura chegam só aos endpoints cadastrados no painel.
Se eu já tenho o status na resposta do cartão, preciso do webhook?
Se eu já tenho o status na resposta do cartão, preciso do webhook?
Sim. A resposta resolve o checkout, e os eventos posteriores, como estorno, alerta de contestação e bloqueio, só chegam por notificação.
Como sei que a cobrança veio do sandbox?
Como sei que a cobrança veio do sandbox?
No webhook,
livemode vem false e data.is_test vem true. No charge.updated legado, o indicador é data.isTest. Os mesmos endpoints recebem eventos de teste e de produção, então descarte ou separe os eventos com livemode: false no ambiente de produção.A requisição deu timeout. Posso criar a cobrança de novo?
A requisição deu timeout. Posso criar a cobrança de novo?
Não reenvie às cegas: a API não aceita
Idempotency-Key. Veja a estratégia segura em Paginação, ordenação e idempotência.Checklist do que você terá ao final
- Chave de teste guardada em variável de ambiente, nunca no código.
-
GET /v1/payment-methodsrespondendo200. - Receptor de webhooks em HTTPS respondendo
2xxrapidamente. - Cobrança Pix criada, com
idguardado junto ao pedido. - QR Code exibido a partir de
qrCodeBase64, comcopyPastecomo alternativa. -
charge.createdecharge.pendingrecebidos napostbackUrl. -
charge.paidrecebido cerca de 5 segundos depois, com o mesmoidda criação. - Eventos de teste reconhecidos por
livemode: false. - Outros status simulados com
POST /v1/charges/{id}/resend-webhook, sem liberar o pedido duas vezes. - Estado confirmado com
GET /v1/charges/{id}antes de liberar o pedido. - Cobranças de cartão aprovada (
4444333322221111) e recusada (4444333322221112), com tratamento depaid,refusedefailedna resposta.
Como testar
Este tutorial cobre a base dos cenários CHG-01 (cartão aprovado), CHG-02 (cartão parcelado), CHG-03 (cartão recusado, com o cartão4444333322221112), CHG-04 (Pix gerado), CHG-05 (Pix pago no sandbox), CHG-06 (consulta), CHG-08 (recebimento de webhook) e CHG-09 (simulação de webhook) do roteiro de homologação. Guarde, para cada um, a requisição, a resposta, o id e o log do webhook com o status HTTP que o seu receptor devolveu.
Veja também
Pix
Regras de validade, QR Code e boas práticas do Pix.
Cartão de crédito
Parcelamento, recusas e 3D Secure.
Webhooks de cobrança
Todos os campos e eventos de cobrança.
Criar uma cobrança
Referência completa de
POST /v1/charges.
