Skip to main content
Este tutorial leva você da chave de teste até uma cobrança acompanhada por webhook, sem dinheiro real. Ao final, você terá o fluxo básico que toda integração com a Finvia usa: criar a cobrança, mostrar o meio de pagamento ao cliente, receber a notificação e confirmar o estado.
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 422 com Fees 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).
Use somente a chave sk_test_ neste tutorial. Com a chave de produção (sk_), as cobranças são reais.

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ê converte sua_chave: (com os dois pontos no final) para Base64 e envia no cabeçalho Authorization. Configure as variáveis de ambiente:
Chame a listagem de meios de pagamento. Resposta 200 significa que a chave e o cabeçalho estão corretos.
A resposta é uma lista com os meios habilitados para a sua conta. Cada item traz 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 responde 200 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
Anote a URL HTTPS gerada pelo ngrok, por exemplo https://abc123.ngrok.io. O endereço do seu receptor será https://abc123.ngrok.io/webhooks/finvia.
Para o desenvolvedor: os eventos charge.created, charge.pending, charge.paid e charge.refunded usam campos em snake_case dentro de data (paid_at, payment_details, is_test). A resposta da API usa camelCase (paidAt, paymentDetails). Não reaproveite o mesmo parser para os dois sem mapear os nomes. Os objetos aninhados (payment_details, payment_method de cartão) ficam em camelCase, e metadata volta exatamente como foi enviada. O charge.updated legado vem todo em camelCase, inclusive as chaves de metadata. Por isso os exemplos usam orderId, que chega igual em todos os canais (veja Metadata).

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. A postbackUrl aponta para o seu receptor.
Resposta 201:
O valor vai em reais: "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 como src de uma imagem.
  • copyPaste: o código Pix copia e cola, para quem paga pelo celular.
No Modo Teste, o 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.
Para o desenvolvedor: qrCodeBase64 pode vir null ou ausente quando a imagem não pôde ser gerada. Nesse caso, gere o QR Code no seu front-end a partir do copyPaste. Sempre exiba o copyPaste também: muitos clientes pagam pelo celular e não conseguem ler a própria tela.

5. Receba os webhooks

O que chega ao receptor

Assim que a cobrança é gravada, sai o charge.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.
O exemplo acima mostra os campos principais. O objeto 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 para paid: 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 novo charge.{status}, com id novo, para a postbackUrl e para os endpoints da sua conta.
Resposta 201:
Um roteiro útil de simulação:
  1. {"status": "paid"}: confira se o receptor responde 2xx e se o pedido, já liberado pelo charge.paid real, não é liberado de novo. O evento simulado tem id novo, então quem segura a duplicidade aqui é a checagem do pedido.
  2. {"status": "refunded"}: confira se o pedido é marcado como estornado.
  3. {"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.
A resposta 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.
Para um id que não existe, a API responde hoje 200 com corpo vazio, sem 404. Trate corpo vazio como “cobrança não encontrada”.

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.
Exemplo de resposta 201 aprovada:
Exemplo de resposta 201 recusada, com o cartão 4444333322221112:
Na recusa síncrona, o 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.
Para o desenvolvedor: para não guardar dados de cartão no seu servidor, o caminho é o cofre de cartões.

Erros comuns

Mais detalhes em Erros e como tratar.

Perguntas frequentes

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.
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.
Sim. A resposta resolve o checkout, e os eventos posteriores, como estorno, alerta de contestação e bloqueio, só chegam por notificação.
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.
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-methods respondendo 200.
  • Receptor de webhooks em HTTPS respondendo 2xx rapidamente.
  • Cobrança Pix criada, com id guardado junto ao pedido.
  • QR Code exibido a partir de qrCodeBase64, com copyPaste como alternativa.
  • charge.created e charge.pending recebidos na postbackUrl.
  • charge.paid recebido cerca de 5 segundos depois, com o mesmo id da 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 de paid, refused e failed na 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ão 4444333322221112), 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.