Idempotência
Nesta página
Como cada produto deduplicaRepita com a mesma chaveCasos que fogem do padrãoErros de idempotênciaCom o identificador que cada produto confere, você repete uma chamada que ficou sem resposta e a operação não é criada duas vezes.
Como cada produto deduplica
A chave é o clientReference, de até 64 caracteres, no corpo. Ele é único na conta entre cobranças, saques e transferências internas.
| Operação | Repetiu com os mesmos dados | Repetiu com dados diferentes |
|---|---|---|
Cobrança, em POST /pix | Retorna a cobrança existente | Retorna a operação que já tem essa referência, sem comparar valor nem outro campo |
Saque e transferência interna, em POST /withdraw, POST /withdraw/qrcode e POST /internal-transfer | Retorna a operação existente | 409 PZC210 |
Devolução, em POST /refund/{transactionId}, com a chave por transação | Retorna a devolução existente se ela está PENDING ou COMPLETED; em outro status, 409 PZC210 | 409 PZC210 |
| Operação | Chave | Repetiu com os mesmos dados | Repetiu com dados diferentes |
|---|---|---|---|
Cobrança, em POST /transactions/payment | externalRef, no corpo | 200 com a cobrança existente, em vez de 201 | PAYMENT_EXTERNAL_REF_MISMATCH |
| Saque, pagamento de copia e cola, transferência e devolução | Header Idempotency-Key, de 1 a 255 caracteres ASCII visíveis, sem espaço | Retorna a operação original, no estado atual | WITHDRAW_IDEMPOTENCY_KEY_REUSED, TRANSFER_IDEMPOTENCY_KEY_REUSED ou REFUND_IDEMPOTENCY_KEY_REUSED |
O Idempotency-Key vale por conta, não expira e é aceito nestas rotas:
POST /transactions/withdrawPOST /transactions/pix/qr-paymentsPOST /transactions/internal-transferPOST /transactions/payment/{paymentId}/refundPOST /transactions/deposit/{depositId}/refund
A chave é o header Idempotency-Key, de até 255 caracteres, obrigatório nas quatro rotas da tabela.
| Operação | Repetiu com os mesmos dados | Repetiu com dados diferentes |
|---|---|---|
Criar, pagar e estornar fatura e criar assinatura, em POST /v1/invoices, POST /v1/invoices/:invoice_id/payments, POST /v1/invoices/:invoice_id/refunds e POST /v1/subscriptions | Retorna a resposta da primeira chamada, com Idempotent-Replayed: true | 409 PZ011 |
O número, o CVV e o token do cartão ficam fora da comparação: repetir com outro card_token retorna a primeira resposta, e trocar o token pelo cartão digitado, ou o contrário, conta como dados diferentes.
O checkout e a geração de token de cartão não usam chave de idempotência. Antes de repetir uma adesão ou o pagamento de uma fatura pelo checkout, consulte a assinatura ou a fatura pelas rotas GET correspondentes.
Detalhes em Idempotência do PayZu Gateway.
A chave é o header Idempotency-Key, de 1 a 255 caracteres.
| Operação | Repetiu com os mesmos dados | Repetiu com dados diferentes |
|---|---|---|
Compra, cadastro de carteira e saque, em POST /v1/buys, POST /v1/wallets e POST /v1/withdrawals | Retorna a resposta da primeira chamada | 422 idempotency_key_reused |
Detalhes em Idempotência do PayZu Câmbio.
A chave é o clientCode, único por conta, no corpo.
| Operação | Repetiu com os mesmos dados | Repetiu com dados diferentes |
|---|---|---|
Proposta, em POST /v1/proposals | 200 com a proposta existente | client_code_conflict |
As ações que mudam o estado da proposta recebem expectedVersion, a version que você leu por último. Se a proposta mudou desde a leitura, a resposta é version_conflict: releia e tente de novo.
O PayZu Payments e a recorrência no cartão não têm chave de idempotência.
Repetir POST /charges cria outra cobrança.
O externalId é obrigatório, mas não deduplica. Depois de um timeout, procure o seu externalId em Listar as cobranças, filtrando pelo período, antes de criar outra cobrança.
Repita com a mesma chave
Gere a chave antes da primeira tentativa, guarde-a junto do pedido e reenvie exatamente a mesma chave quando não souber o resultado.
Casos que fogem do padrão
No PayZu Conta Hub, três operações pedem cuidado na retentativa.
| Operação | Na retentativa | Rota |
|---|---|---|
| Devolução | Depois de um 502, envie a mesma Idempotency-Key e o mesmo amount. A resposta traz a devolução já pedida, sem enviar outro Pix. | Solicitar a devolução de uma cobrança |
| Pagamento de copia e cola | Envie o mesmo código com a mesma chave, que também confere o código pago. | Pagar um Pix copia e cola |
| Transferência interna | Depois de um 502, a transferência pode ter ficado REQUESTED. Repita com a mesma chave para recebê-la de volta. | Transferir para outra conta PayZu |
Devolução repetida sem a chave envia outro Pix.
Isso acontece quando a primeira devolução já concluiu.
Erros de idempotência
| Código | HTTP | Mensagem |
|---|---|---|
REFUND_INVALID_IDEMPOTENCY_KEY | 400 | Idempotency-Key inválido: use até 255 caracteres ASCII visíveis, sem espaço. |
TRANSFER_INVALID_IDEMPOTENCY_KEY | 400 | O cabeçalho Idempotency-Key deve ter de 1 a 255 caracteres visíveis. |
WITHDRAW_INVALID_IDEMPOTENCY_KEY | 400 | O cabeçalho Idempotency-Key deve ter de 1 a 255 caracteres visíveis. |
PAYMENT_EXTERNAL_REF_MISMATCH | 409 | Já existe uma cobrança com esta referência, e os dados enviados não conferem com os dela. |
REFUND_IDEMPOTENCY_KEY_REUSED | 409 | Este Idempotency-Key já foi usado por um estorno com outros dados. |
TRANSFER_IDEMPOTENCY_KEY_REUSED | 409 | Esta chave de idempotência já foi usada para outra transferência. |
WITHDRAW_IDEMPOTENCY_KEY_REUSED | 409 | Este Idempotency-Key já foi usado por um saque com outros dados. |
PAYMENT_CREATION_IN_FLIGHT | 412 | Uma cobrança com esta referência está sendo criada agora. Repita em instantes. |
| Código | HTTP | Mensagem |
|---|---|---|
PZ001 | 400 | A solicitação possui erros de validação. |
PZ010 | 400 | Envie o cabeçalho Idempotency-Key nesta operação. |
PZ011 | 409 | Idempotency-Key já usada com outra requisição. |
PZ012 | 409 | Requisição com esta Idempotency-Key ainda está em processamento. |
| - | 422 | Requisição com esta Idempotency-Key acabou de ser liberada. Tente novamente. |
| Código | HTTP | Mensagem |
|---|---|---|
client_code_conflict | 409 | O clientCode já foi usado com outro conteúdo. |
version_conflict | 409 | O registro mudou desde a leitura. Releia e tente de novo. |
Os códigos do PayZu Câmbio estão em Idempotência do produto, e a lista inteira, no Catálogo de erros.