Idempotência
Como repetir chamadas com segurança depois de uma falha de rede, sem criar cobranças duplicadas.
Redes falham. Uma chamada pode chegar à Accelerazione, criar a cobrança e a resposta se perder no caminho de volta. Se a sua integração repetir a chamada sem proteção, o comprador é cobrado duas vezes. A chave de idempotência resolve isso: a mesma chave, enviada de novo, devolve o resultado da primeira chamada em vez de criar outra cobrança.
Idempotency-Key: pedido-1001-tentativa-1Como usar
- Gere uma chave por tentativa de compra, por exemplo
pedido-1001-tentativa-1. Ela pode ter de 1 a 200 caracteres; espaços nas pontas são removidos. Vazia ou maior que isso, a resposta é400 invalid_idempotency_key. - Grave a chave antes da primeira chamada, junto com o pedido. Se o seu processo cair no meio, a repetição usa a mesma chave.
- Repita com a mesma chave e o mesmo corpo sempre que não souber o resultado: tempo esgotado, conexão interrompida,
5xx. - Grave o
iddo PaymentIntent assim que receber a resposta, vinculado ao pedido e à chave.
O cabeçalho é opcional na criação de cobrança, mas recomendado para todos os métodos.
Comportamento com a mesma chave
| Situação | Resposta |
|---|---|
| Mesmo corpo, criação concluída | A resposta original de novo, inclusive se ela era Failed ou RequiresAction. |
| Criação ainda em andamento | 409 com type: idempotency_key_in_flight. Espere o tempo do cabeçalho Retry-After e repita. |
| Corpo diferente | 409 com type: idempotency_key_payload_mismatch. Não reutilize uma chave para outra compra. |
| Falha de rede sem resposta | Repita a mesma chamada, com a mesma chave e o mesmo corpo. |
503 com type: idempotency_unavailable | Respeite Retry-After e repita com a mesma chave. |
A resposta fica retida por pelo menos 24 horas. Depois disso, a mesma chave pode criar uma cobrança nova: não reaproveite chaves antigas.
Só respostas 201 ficam retidas. Se a primeira chamada terminou com um erro 4xx ou 5xx antes de a cobrança ser criada, repetir com a mesma chave executa a criação de novo.
A comparação do corpo é semântica: reordenar campos ou mudar espaços não conta como corpo diferente.
A repetição devolve a foto, não o estado atual
Repetir o create devolve a resposta do momento da criação. Uma cobrança criada como Processing e paga depois continua aparecendo como Processing na repetição. Para saber o estado atual, use GET /api/v1/paymentintents/{id}.
Quando usar uma chave nova
| Situação | Chave |
|---|---|
Falha de rede, tempo esgotado, 5xx | A mesma, com o mesmo corpo. |
Erro de validação (400) corrigido no corpo | Nova, mesmo para o mesmo pedido. |
| Recusa confirmada do cartão, comprador vai tentar de novo | Nova. Em crédito, abra também uma nova sessão 3DS. |
| Nova compra | Nova. |
Resultado indeterminado (Processing) | Nenhuma. Acompanhe a cobrança existente por consulta ou webhook. Criar outra pode gerar uma segunda cobrança. |
Outras rotas
Tokenização, estorno e saque têm regras próprias:
| Rota | Onde vai a chave | Regras |
|---|---|---|
POST /api/v1/card-tokens | Cabeçalho Idempotency-Key ou campo idempotencyKey | Obrigatória. 8 a 255 caracteres. Veja Tokenização. |
POST /api/v1/paymentintents/{id}/refund-requests | Campo idempotencyKey do corpo | Opcional. Veja Estornos. |
POST /api/v1/withdrawals | Cabeçalho Idempotency-Key ou campo idempotencyKey | Obrigatória. 10 a 200 caracteres. Veja Saques. |