PayZu GatewayApoio

Cenários práticos


Nesta páginaCartão sem resposta da adquirenteNova tentativa depois de uma recusaAdesão no Pix que expiraEstorno de uma fatura pagaLink com limite de pagamentos

Cartã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 mudaValor
Resposta de POST /v1/invoices201, com a fatura pending e a tentativa processing em payments[0]
A mesma chamada com a mesma Idempotency-KeyO mesmo 201, com Idempotent-Replayed: true, sem cobrar de novo
Nova tentativa na mesma fatura409 até o desfecho
ConciliaçãoA PayZu procura a cobrança na adquirente a partir de 5 minutos da criação
Cobrança encontradaA 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 horasA tentativa passa a failed, com failure.stage: processing, e a fatura volta a aceitar tentativa
Cobrança aprovada que aparece depoisA tentativa ainda passa a paid, com invoice.paid
POST /v1/invoices
{
  "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 mudaValor
Primeira resposta201, com a fatura pending e a tentativa failed em payments[0]
Motivo da recusaEm failure.code, de PZ220 a PZ298, com a frase para o cliente em failure.message
Onde tentar de novoNa mesma fatura, em POST /v1/invoices/:invoice_id/payments, com o id da primeira resposta
Idempotency-KeyUma chave nova
Chave da criação em POST /v1/invoices/:invoice_id/payments409 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 novoA 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_tokenO token do novo cartão, gerado de novo no aparelho do comprador
TentativasFicam 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
bash
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 mudaValor
payment_method em POST /v1/subscriptionspix, sem credit_card
Resposta 201Assinatura 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ão1 hora depois da criação, em invoice.billing.expires_at; o QR Code vence junto
Pix pagoAssinatura active e fatura paid, com invoice.paid e subscription.activated
Sem pagamento até billing.expires_atFatura 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 metadataTenta outra vez na fatura de adesão em aberto, sem mudar valores nem datas
POST /v1/subscriptions
{
  "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 mudaValor
cancel_subscription: false em POST /v1/invoices/:invoice_id/refundsMantém a assinatura como está
cancel_subscription: trueCancela a assinatura, se estiver active
Sem o campoVale refund_cancels_subscription da conta, que nasce true e está em Alterar a carência
Onde valeSó em fatura de assinatura; nas outras faturas, o campo não muda nada
ValorSempre o total da fatura
Resposta no cartão201 com a fatura refunded, o estorno confirmed em refunds e o evento invoice.refunded
Com o cancelamentoAssinatura canceled, com cancellation.reason: invoice_refund, as outras faturas em aberto dela canceled e os eventos invoice.canceled e subscription.canceled
Devolução no PixA fatura segue paid, com o estorno requested, e a assinatura só é cancelada quando a devolução é confirmada
POST /v1/invoices/in_2WcN6xQmLb9TzYv4KdRh8E/refunds
{
  "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.

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 aconteceEfeito na vaga
Compra pelo linkCria uma fatura sem cliente e não ocupa vaga.
Tentativa de pagamento na faturaOcupa uma vaga até o desfecho.
Pix emitido e não pagoOcupa a vaga até o QR Code vencer, 60 minutos depois.
Cartão sem resposta da adquirenteOcupa a vaga por até 24 horas.
Recusa, falha ou Pix vencidoDevolve a vaga.
Cobrança aprovada que aparece depois de devolver a vagaOcupa uma vaga livre. Sem vaga ou com o link fechado, a fatura fica paga e não conta no limite.
Vagas restantes todas em andamentoA compra e a tentativa respondem 422 com Há pagamentos aguardando confirmação neste link. Tente novamente em alguns minutos.
50º pagamento confirmadoO 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.