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
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
Passo a passo
1. Crie a cobrança
201:
2. Mostre o QR Code no checkout
O seu back-end devolve ao front-end apenas ocopyPaste e o qrCodeBase64. A chave secreta nunca vai para o navegador.
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.
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
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 porPOST /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
statuscontinuapaide a cobrança passa a terisBlocked: true,blockedAteblockedReason. - O evento
charge.blockedvai aos endpoints de webhook e àpostbackUrl(que recebe também ocharge.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
refundede você recebecharge.refunded. Se for recusada, o bloqueio é retirado, sem webhook: acompanhe pela consulta.
Erros comuns
Perguntas frequentes
Posso usar expirationInDays e expirationInSeconds juntos?
Posso usar expirationInDays e expirationInSeconds juntos?
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.
Qual a validade mínima de um Pix?
Qual a validade mínima de um Pix?
15 minutos:
expirationInSeconds tem mínimo 900. Em dias, o mínimo é 1.O Pix aceita parcelamento?
O Pix aceita parcelamento?
Não. O Pix é pago à vista. Para parcelar, use cartão de crédito.
Como sei que o cliente pagou?
Como sei que o cliente pagou?
Pelo webhook
charge.paid. Ao receber, confirme o status com GET /v1/charges/{id} antes de liberar o pedido.Como testo um Pix pago sem pagar de verdade?
Como testo um Pix pago sem pagar de verdade?
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 (chavesk_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.- CHG-04 (Pix gerado): cobrança com
pending, resposta com o copia e cola e webhookcharge.pending. - CHG-05 (Pix pago): o webhook
charge.paidchega com o mesmoiddevolvido 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.

