Cenários práticos
Nesta página
Cartão sem resposta da adquirenteNova tentativa depois de uma recusaAdesão no Pix que expiraEstorno de uma fatura pagaLink com limite de pagamentosCartão sem resposta da adquirente
A adquirente não respondeu a tempo à cobrança no cartão feita na criação de uma fatura. Você não sabe se o cliente foi cobrado.
| O que muda | Valor |
|---|---|
Resposta de POST /v1/invoices | 201, com a fatura pending e a tentativa processing em payments[0] |
A mesma chamada com a mesma Idempotency-Key | O mesmo 201, com Idempotent-Replayed: true, sem cobrar de novo |
| Nova tentativa na mesma fatura | 409 até o desfecho |
| Conciliação | A PayZu procura a cobrança na adquirente a partir de 5 minutos da criação |
| Cobrança encontrada | A tentativa passa a paid ou a failed, com invoice.paid ou invoice.payment_failed |
| Cobrança não encontrada em 30 minutos, ou sem resposta em 24 horas | A tentativa passa a failed, com failure.stage: processing, e a fatura volta a aceitar tentativa |
| Cobrança aprovada que aparece depois | A tentativa ainda passa a paid, com invoice.paid |
{
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"amount": 15990,
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"payment": {
"method": "credit_card",
"credit_card": {
"card_token": "UTYi5E0smwqD8P5U8pupcDtT1aIAbpgkc5HLQFGkb3I",
"installments": 1
}
}
}Para acompanhar, consulte GET /v1/invoices/:invoice_id com o id que veio no 201, ou GET /v1/invoices com external_reference=pedido-1234.
Não crie outra fatura para o mesmo pedido enquanto a tentativa estiver processing.
A PayZu nunca repete a cobrança, e a fatura nova seria uma segunda cobrança no cartão do cliente. Um invoice.payment_failed dessa tentativa ainda pode ser seguido de invoice.paid.
Nova tentativa depois de uma recusa
O cartão foi recusado na cobrança de uma fatura. O cliente quer pagar o mesmo pedido com outro cartão.
| O que muda | Valor |
|---|---|
| Primeira resposta | 201, com a fatura pending e a tentativa failed em payments[0] |
| Motivo da recusa | Em failure.code, de PZ220 a PZ298, com a frase para o cliente em failure.message |
| Onde tentar de novo | Na mesma fatura, em POST /v1/invoices/:invoice_id/payments, com o id da primeira resposta |
Idempotency-Key | Uma chave nova |
Chave da criação em POST /v1/invoices/:invoice_id/payments | 409 com Idempotency-Key já usada com outra requisição., porque a chave vale só para a mesma rota e o mesmo corpo |
POST /v1/invoices de novo, com a chave da criação e o token novo | A primeira resposta, com Idempotent-Replayed: true, sem cobrar o cartão novo, porque número, CVV e token do cartão ficam fora da comparação |
credit_card.card_token | O token do novo cartão, gerado de novo no aparelho do comprador |
| Tentativas | Ficam em payments[] da mesma fatura, da mais nova para a mais antiga, até 5 em 24 horas contadas a partir da primeira, somadas às da página de pagamento |
Resposta 422 com Valor fora do limite desta conta. | Não é recusa do cartão: o valor está fora do limite da conta, e outro cartão não resolve |
curl -X POST https://api.sandbox.payzu.dev/v1/invoices/in_9Lq4ZnWcVb7TyXm3KdRh2E/payments \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 0c5e8f1a-2b3d-4c6e-8f9a-1b2c3d4e5f60" \
-H "Content-Type: application/json" \
-d '{
"method": "credit_card",
"credit_card": {
"card_token": "TOKEN_DO_NOVO_CARTAO",
"installments": 1
}
}'A recusa não fecha a fatura: a url segue valendo, e o cliente também pode pagar na página. Veja Pagar uma fatura.
Adesão no Pix que expira
O cliente escolheu assinar um plano no Pix e não pagou o QR Code. O acesso só pode ser liberado depois do pagamento.
| O que muda | Valor |
|---|---|
payment_method em POST /v1/subscriptions | pix, sem credit_card |
Resposta 201 | Assinatura incomplete, com a fatura de adesão em invoice e o copia e cola em invoice.payments[0].pix.qr_code_text |
| Prazo da fatura de adesão | 1 hora depois da criação, em invoice.billing.expires_at; o QR Code vence junto |
| Pix pago | Assinatura active e fatura paid, com invoice.paid e subscription.activated |
Sem pagamento até billing.expires_at | Fatura expired, assinatura canceled com cancellation.reason: initial_payment_failure, e os eventos invoice.expired e subscription.canceled |
Nova criação com o mesmo cliente, plano, payment_method e metadata | Tenta outra vez na fatura de adesão em aberto, sem mudar valores nem datas |
{
"payment_method": "pix",
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"plan_id": "plan_oOsn4Cs4eayZ3LoytwzErn"
}Libere o acesso só quando a assinatura estiver active, pelo evento subscription.activated ou por GET /v1/subscriptions/:subscription_id. A assinatura não aceita installments: o campo responde 400.
Estorno de uma fatura paga
O cliente pagou no cartão a fatura do mês de uma assinatura e pediu o dinheiro de volta. Ele quer continuar assinante.
| O que muda | Valor |
|---|---|
cancel_subscription: false em POST /v1/invoices/:invoice_id/refunds | Mantém a assinatura como está |
cancel_subscription: true | Cancela a assinatura, se estiver active |
| Sem o campo | Vale refund_cancels_subscription da conta, que nasce true e está em Alterar a carência |
| Onde vale | Só em fatura de assinatura; nas outras faturas, o campo não muda nada |
| Valor | Sempre o total da fatura |
| Resposta no cartão | 201 com a fatura refunded, o estorno confirmed em refunds e o evento invoice.refunded |
| Com o cancelamento | Assinatura canceled, com cancellation.reason: invoice_refund, as outras faturas em aberto dela canceled e os eventos invoice.canceled e subscription.canceled |
| Devolução no Pix | A fatura segue paid, com o estorno requested, e a assinatura só é cancelada quando a devolução é confirmada |
{
"cancel_subscription": false
}O estorno também exige Idempotency-Key. Veja Estornar uma fatura.
A contestação de uma fatura de assinatura sempre cancela a assinatura.
Ela não olha cancel_subscription. Uma assinatura cancelada por estorno ou por contestação não pode ser reativada: crie uma nova.
Link com limite de pagamentos
Você vende 50 vagas de um workshop por um link de pagamento criado no painel, com limite de 50 pagamentos, que aceita cartão e Pix. Muitos compradores pagam ao mesmo tempo.
| O que acontece | Efeito na vaga |
|---|---|
| Compra pelo link | Cria uma fatura sem cliente e não ocupa vaga. |
| Tentativa de pagamento na fatura | Ocupa uma vaga até o desfecho. |
| Pix emitido e não pago | Ocupa a vaga até o QR Code vencer, 60 minutos depois. |
| Cartão sem resposta da adquirente | Ocupa a vaga por até 24 horas. |
| Recusa, falha ou Pix vencido | Devolve a vaga. |
| Cobrança aprovada que aparece depois de devolver a vaga | Ocupa uma vaga livre. Sem vaga ou com o link fechado, a fatura fica paga e não conta no limite. |
| Vagas restantes todas em andamento | A compra e a tentativa respondem 422 com Há pagamentos aguardando confirmação neste link. Tente novamente em alguns minutos. |
| 50º pagamento confirmado | O link passa a paid, e uma nova compra responde 422 com Este link já foi pago. |
Cada venda chega com invoice.paid, com o link em payment_link. As faturas do link saem em GET /v1/invoices com payment_link_id, como em Consultar faturas.
Com o link pago, o limite não muda mais.
Aumente o limite no painel enquanto o link está ativo.