Skip to main content
O Pix é o pagamento instantâneo do Brasil. Na Finvia, você cria a cobrança e recebe na resposta o código copia e cola e a imagem do QR Code para mostrar ao cliente. Quando o cliente paga no app do banco, a Finvia avisa o seu sistema por webhook e você libera o pedido.
Para o negócio: o Pix é pago à vista, sem parcelamento, e o cliente paga no app do próprio banco. Você define por quanto tempo o QR Code vale: alguns minutos em um checkout com o cliente na tela, ou um ou mais dias em uma cobrança enviada por link ou mensagem.

Quando usar

Como funciona

O desenho abaixo mostra o caminho completo de uma cobrança Pix, do pedido à confirmação, e o que acontece quando o QR Code vence sem pagamento. Os eventos chegam aos endpoints de webhook cadastrados no painel e à postbackUrl da cobrança. O charge.updated vai só para a postbackUrl: sem ela, a única forma de saber que um Pix venceu é consultar a cobrança.
1

Você cria a cobrança Pix

Seu servidor chama POST /v1/charges com paymentMethod.type pix e a validade do QR Code.
2

A resposta traz o QR Code

A resposta 201 vem com status pending e paymentDetails com o código copia e cola (copyPaste), a imagem do QR Code (qrCodeBase64) e o identificador endToEndId.
3

Você mostra o QR Code ao cliente

O checkout exibe a imagem e um botão para copiar o código. Os endpoints de webhook e a postbackUrl recebem charge.created e charge.pending.
4

O cliente paga no app do banco

Ele escaneia o QR Code ou cola o código no app do banco e confirma o pagamento.
5

A Finvia confirma por webhook

A cobrança passa para paid e o seu sistema recebe charge.paid (e, na postbackUrl, também o charge.updated legado). Confirme com GET /v1/charges/{id} e libere o pedido.

Regras de negócio

Nunca libere o pedido com base na resposta da criação. O pending indica só que o QR Code foi gerado. Libere só depois de receber charge.paid e confirmar o status com GET /v1/charges/{id}.

Como escolher a validade

Uma validade curta mantém o pedido e o estoque alinhados com o pagamento. Uma validade longa dá tempo para o cliente pagar quando puder.

O que vem na resposta

Para o desenvolvedor: qrCodeBase64 pode vir null ou ausente quando a imagem não pôde ser gerada (ou em cobranças criadas antes de o campo existir). Nesse caso, gere o QR Code no seu front-end a partir do copyPaste, com qualquer biblioteca de QR Code, ou mostre só o código copia e cola.

Passo a passo

1. Crie a cobrança

Resposta 201:

2. Mostre o QR Code no checkout

O seu back-end devolve ao front-end apenas o copyPaste e o qrCodeBase64. A chave secreta nunca vai para o navegador.
Para o desenvolvedor: para atualizar a tela quando o cliente pagar, faça o front-end consultar o seu back-end a cada poucos segundos (ou use WebSocket). O seu back-end responde com o status que gravou ao receber charge.paid. O navegador nunca chama a API da Finvia com a chave secreta.

3. Receba os webhooks

Os eventos de cobrança chegam aos endpoints do painel e à postbackUrl no envelope padrão (id, event, livemode, data), com as chaves de data em snake_case. Os objetos internos ficam como foram gravados: payment_details do Pix vem em camelCase (endToEndId, copyPaste, qrCodeBase64) e metadata volta exatamente como você enviou. O exemplo abaixo é um charge.paid.
O exemplo mostra parte do objeto data. O payload completo está em Webhooks de cobrança. Na postbackUrl, o pagamento gera também um charge.updated legado, em camelCase e sem id.
Node.js
Para descartar eventos repetidos, siga a receita de deduplicação, que cobre também o charge.updated. Depois de criado, um Pix pode passar pelos status abaixo. Cada seta mostra o que provoca a mudança e o aviso que o seu sistema recebe. O estorno e o MED estão detalhados nas seções seguintes desta página e em Bloqueio, chargeback e MED.

Conciliação

Conciliar é conferir que cada pedido pago no seu sistema corresponde a um Pix recebido, com o valor certo. Para conferir em lote, use GET /v1/charges com status=paid, createdAtStart e createdAtEnd no dia desejado, paginando por page e size. Para achar um Pix pelo endToEndId, use searchFor.

Estorno de Pix

Uma cobrança Pix paga pode ser estornada por POST /v1/refunds. O estorno é uma devolução Pix do pagamento original, sempre do valor total, enviada na hora. Quando aceita, o dinheiro costuma chegar em segundos na conta de origem. Pelas regras do Pix, a devolução precisa ser pedida em até 90 dias do pagamento: depois disso, o banco pode recusar. A cobrança vai para refunded e o seu sistema recebe charge.refunded. Detalhes em Estorno.

MED

O MED (Mecanismo Especial de Devolução) é o mecanismo do Pix que permite à instituição do pagador pedir a devolução de um Pix em caso de suspeita de fraude ou falha operacional. Quando a Finvia é notificada de um MED sobre um Pix pago, a equipe Finvia bloqueia a cobrança enquanto o caso é analisado:
  • O status continua paid e a cobrança passa a ter isBlocked: true, blockedAt e blockedReason.
  • O evento charge.blocked vai aos endpoints de webhook e à postbackUrl (que recebe também o charge.updated).
  • O valor já liquidado da venda sai do saldo disponível e vai para o saldo bloqueado.
  • Se a devolução for aceita, a cobrança fica refunded e você recebe charge.refunded. Se for recusada, o bloqueio é retirado, sem webhook: acompanhe pela consulta.
O fluxo completo, o envio da defesa e os desfechos estão em Bloqueio, chargeback e MED.

Erros comuns

Perguntas frequentes

Um dos dois é obrigatório. Envie só o que corresponde à sua regra: segundos para checkout com o cliente na tela, dias para cobranças por link.
15 minutos: expirationInSeconds tem mínimo 900. Em dias, o mínimo é 1.
Não. O Pix é pago à vista. Para parcelar, use cartão de crédito.
Pelo webhook charge.paid. Ao receber, confirme o status com GET /v1/charges/{id} antes de liberar o pedido.
Crie a cobrança com a chave sk_test_. Cerca de 5 segundos depois, ela passa sozinha para paid e você recebe charge.paid. Não tente pagar o código de teste em um app de banco.

Como testar

No Modo Teste (chave sk_test_), o Pix é confirmado automaticamente. Não há nada para pagar nem botão de simulação.
1

Crie a cobrança com a chave de teste

Use paymentMethod: { "type": "pix", "expirationInSeconds": 900 } (ou expirationInDays).
2

Confira a resposta

Vem status: "pending" com copyPaste e qrCodeBase64 fictícios. Não tente pagar esse código.
3

Aguarde cerca de 5 segundos

A cobrança passa sozinha para paid: paidAt é preenchido e paymentDetails.endToEndId recebe um valor de teste.
4

Confira os eventos

Os endpoints recebem charge.created e charge.pending na criação e charge.paid na confirmação, com livemode: false. A postbackUrl, se informada, também é notificada. Confirme com GET /v1/charges/{id} usando a mesma chave de teste.
No sandbox todo Pix é aprovado: não dá para simular expiração ou falha. Para testar o tratamento de outros status, use POST /v1/charges/{id}/resend-webhook, que dispara um evento simulado sem alterar a cobrança. Se, em casos raros, a cobrança não virar paid em alguns segundos, gere outra.
Cenários do roteiro de homologação:
  • CHG-04 (Pix gerado): cobrança com pending, resposta com o copia e cola e webhook charge.pending.
  • CHG-05 (Pix pago): o webhook charge.paid chega com o mesmo id devolvido na criação.
  • CHG-07 (estorno): estorno total da cobrança paga, com charge.refunded.
  • CHG-08 e CHG-09: recebimento e simulação de webhook.

Veja também

Webhooks de cobrança

Formato completo dos eventos.

Estorno

Como devolver um Pix pago.

Bloqueio, chargeback e MED

Contestações e bloqueio preventivo.

Criar uma cobrança

Todos os campos da rota.