Comece aquiSegurança da API

Idempotência


Nesta páginaComo cada produto deduplicaRepita com a mesma chaveCasos que fogem do padrãoErros de idempotência

Com 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çãoRepetiu com os mesmos dadosRepetiu com dados diferentes
Cobrança, em POST /pixRetorna a cobrança existenteRetorna 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-transferRetorna a operação existente409 PZC210
Devolução, em POST /refund/{transactionId}, com a chave por transaçãoRetorna a devolução existente se ela está PENDING ou COMPLETED; em outro status, 409 PZC210409 PZC210

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çãoNa retentativaRota
DevoluçãoDepois 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 colaEnvie o mesmo código com a mesma chave, que também confere o código pago.Pagar um Pix copia e cola
Transferência internaDepois 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ódigoHTTPMensagem
PZC210409Já existe uma operação com este identificador. Verifique o clientReference informado.
PZC221409Esta transação já foi reembolsada.

Os códigos do PayZu Câmbio estão em Idempotência do produto, e a lista inteira, no Catálogo de erros.