PayZu GatewaySegurança

Idempotência


Nesta páginaComo funciona em cada operaçãoA resposta guardadaO cartão fica fora da comparaçãoComo repetir uma chamadaErros de idempotência

Repita com segurança uma chamada que ficou sem resposta, sem cobrar, assinar ou estornar duas vezes.

Como funciona em cada operação

Idempotency-KeyRotas
ObrigatórioCriar uma fatura, Pagar uma fatura, Estornar uma fatura e Criar uma assinatura.
OpcionalDemais rotas POST, PATCH e DELETE com a chave de API.
IgnoradoSalvar um cartão, Cadastrar um webhook, Trocar o segredo de um webhook e Defender uma contestação.
Não usadoGeração de token de cartão e rotas do Checkout.

A resposta guardada

O valor do cabeçalho tem até 255 caracteres e é único na conta inteira, qualquer que seja a chave de API usada. Acima disso, a chamada responde 400 de validação, com Idempotency-Key em fields. A primeira resposta fica guardada por 24 horas, com qualquer status, inclusive erro.

Repetição com a mesma chaveResposta
Mesmo método, caminho e corpoA resposta da primeira chamada, com o mesmo status, o cabeçalho Idempotent-Replayed: true e sem X-Request-Id.
Outro corpo ou outra rota409, chave já usada com outra requisição.
Enquanto a primeira chamada ainda executa409, requisição ainda em processamento.

Três respostas não ficam guardadas, porque acontecem antes de a chave ser registrada:

  • os erros de autenticação;
  • o 404 da Recorrência não ativada;
  • os 400 de validação dos dados.

Nas rotas que cobram, assinam ou estornam, também não fica guardado o erro que acontece antes de a cobrança seguir para a adquirente: a chave é liberada e pode ser usada de novo. Depois desse envio, a resposta fica guardada, inclusive a do cartão recusado e a de 5xx.

O cartão fica fora da comparação

Na comparação do corpo, não entram o número e o CVV de card nem o card_token: em credit_card no pagamento da fatura e na assinatura, e em payment.credit_card na criação da fatura.

Repetição com a mesma chaveResposta
Um token novoA primeira resposta.
Cartão digitado com outro número e outro CVV, mas com a mesma validade e o mesmo titularA primeira resposta.
Outro card_id, outra validade, outro titular, ou o token trocado pelo cartão digitado e o contrário409, chave já usada com outra requisição.

Em nenhum desses casos algo é cobrado de novo. Como cada token serve para uma operação só, a repetição com card_token pode levar um token novo.

Como repetir uma chamada

Gere a Idempotency-Key antes da primeira tentativa, como um UUID, guarde junto do pedido e reenvie a mesma chave com o mesmo corpo quando não souber o resultado. Para outra operação, ou para tentar outro cartão depois de uma recusa, use uma chave nova.

bash
curl -X POST https://api.sandbox.payzu.dev/v1/invoices/in_7Kd2QmXvB9LtYc4WnRz8Hs/refunds \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c"

Se a resposta for o 409 de requisição em processamento, espere a primeira chamada terminar e repita com a mesma chave. Se o 409 continuar, há duas possibilidades:

Primeira chamadaO que fazer
Ainda executaRepita com a mesma chave mais tarde. Quando ela terminar, a repetição recebe a resposta guardada ou, se ela terminou com um erro que não fica guardado, é feita como uma nova chamada.
Caiu sem respostaA chave continua respondendo 409 até vencer, em 24 horas.

Consulte se a fatura, a assinatura ou o estorno existe antes de repetir com outra chave.

Com outra chave, a operação pode ser feita duas vezes se a primeira chamada ainda terminar.

A resposta 422 de chave liberada também pede uma nova tentativa com a mesma chave.

Erros de idempotência

CódigoHTTPMensagem
PZ010400Envie o cabeçalho Idempotency-Key nesta operação.
PZ011409Idempotency-Key já usada com outra requisição.
PZ012409Requisição com esta Idempotency-Key ainda está em processamento.
-422Requisição com esta Idempotency-Key acabou de ser liberada. Tente novamente.

Todos os códigos do PayZu Gateway estão no Catálogo de erros.