Idempotency-Key

Toda chamada que cria efeito financeiro na API da Vellus Payments exige o cabeçalho Idempotency-Key. Ele garante que, se a sua chamada falhar por rede antes de você ver a resposta, retentar com a mesma chave devolve o resultado original em vez de cobrar duas vezes.

Em implantação

Esta página descreve o contrato de idempotência que a Vellus Payments publica para integradores. Siga este contrato somente quando o changelog anunciar a disponibilidade do endpoint correspondente no sandbox.

Onde é obrigatório

O cabeçalho Idempotency-Key é obrigatório nestas operações:

Operação	Rota
Criar pagamento	POST /v2/payment
Estornar pagamento	PUT /v2/payment/reverse
Criar recarga	POST /v2/payment/recharge
Cancelar recarga	POST /v2/payment/recharge/{rechargeId}/cancel

Chamadas de leitura, como GET /v2/payment/transactions, não usam este cabeçalho.

Formato

A chave tem de 8 a 128 caracteres, entre letras, números, _, : e - (^[A-Za-z0-9_:-]{8,128}$). Gere uma chave nova por pedido de negócio, nunca uma fixa para todos os pedidos. Um UUID v4 funciona bem.

POST /v2/payment HTTP/1.1
Authorization: Bearer <seu access token>
Idempotency-Key: <uuid-v4-gerado-pelo-cliente>
Content-Type: application/json

{ "amount": 1590, "sellerId": "...", "buyerId": "..." }

Os quatro desfechos

A API guarda, por chave, o corpo da chamada original (um fingerprint, nunca os dados em claro) e o resultado:

1. Chave nova. A operação é processada normalmente, e o resultado fica associado à chave.
2. Replay — mesma chave, mesmo corpo. Você recebe exatamente o status e o corpo da chamada original, com o cabeçalho Idempotent-Replayed: true. Nenhum efeito novo é despachado. É seguro retentar com a mesma chave sempre que a resposta anterior não chegou até você, por exemplo depois de um timeout de rede.
3. Em andamento — mesma chave, mesmo corpo, requisição original ainda não terminou. Você recebe 409 Conflict, com o cabeçalho Retry-After em segundos. Espere esse tempo e tente de novo com a mesma chave.
4. Chave reutilizada — mesma chave, corpo diferente. Você recebe 422 Unprocessable Content. Isso quase sempre indica um defeito de geração de chave no seu lado: a mesma chave está sendo usada para pedidos de negócio diferentes. Gere uma chave nova por pedido.

Os desfechos 3 e 4 saem em application/problem+json. Veja os códigos no catálogo de erros:

• IDEMPOTENCY_KEY_REQUIRED — cabeçalho ausente.
• IDEMPOTENCY_KEY_INVALID_FORMAT — fora do formato aceito.
• IDEMPOTENCY_OPERATION_IN_PROGRESS — desfecho 3.
• IDEMPOTENCY_KEY_REUSED — desfecho 4.

Boa prática de retentativa

• Gere a chave uma vez, antes da primeira tentativa, e guarde-a junto do pedido no seu sistema. Reenvie exatamente a mesma chave em toda retentativa daquele pedido.
• Nunca gere uma chave nova só porque a primeira tentativa não teve resposta. Esse é exatamente o caso que o replay cobre.
• Se receber 500 com Idempotent-Replayed: true ou sem ele numa chamada que você sabe ter retentado, o resultado da operação original não pôde ser confirmado. Não gere uma chave nova para tentar de novo: consulte o suporte antes de repetir, porque o efeito financeiro pode já ter ocorrido no adquirente.