Idempotência

Retentativas de rede podem fazer com que um mesmo request seja enviado mais de uma vez. Para evitar cobranças duplicadas, a API Xfin suporta idempotência via header Idempotency-Key.

Como funciona

Ao criar um payout com o header Idempotency-Key, o servidor:

1. Verifica se já existe um payout criado com essa chave para o seu parceiro.
2. Se não existe: processa normalmente e associa a chave ao payout criado.
3. Se já existe e está concluído: retorna o payout original com 200 OK — o corpo do request é ignorado, nenhuma nova cobrança é gerada.
4. Se existe e ainda está em processamento (em voo): retorna 409 Conflict.

Fazendo um request idempotente

Inclua o header Idempotency-Key com um valor único para cada operação. Use o ID interno da sua ordem ou transação — algo que você possa reproduzir deterministicamente em caso de retry:

curl -s -X POST "https://xfin-payouts-ys3int7llq-rj.a.run.app/v1/payouts" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: pedido-2026-abc-123" \
  -d '{
    "amount_brl": 100.00,
    "receiver_wallet": "0xEnderecoCarteira",
    "pix_key": "pagador@email.com",
    "pix_key_type": "EMAIL"
  }'

Se a requisição cair, falhar com timeout, ou o cliente não receber resposta, basta repetir o mesmo request com o mesmo Idempotency-Key. O servidor retornará o payout original — sem criar uma segunda cobrança.

Tip

Use um identificador da sua própria lógica de negócio como chave — por exemplo, o ID do pedido no seu sistema (order-12345). Isso torna a idempotência rastreável e eliminará duplicatas mesmo após reinicializações do seu servidor.

Resposta em caso de replay

Quando a chave já existe e o payout foi processado, o servidor retorna o payout original com 200 OK:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "amount_brl": 100.00,
  "min_amount_usdt": 18.37,
  "pix_copy_paste": "00020101021226930014br.gov.bcb.pix...",
  "..."
}

O corpo enviado na retentativa é completamente ignorado — mesmo que os campos sejam diferentes, o servidor retorna o payout original sem modificações.

Conflito em voo — 409 Conflict

Se você enviar um segundo request com a mesma Idempotency-Key enquanto o primeiro ainda está sendo processado (em voo), o servidor retorna:

HTTP/1.1 409 Conflict
Content-Type: application/json

{ "error": "request with this idempotency key is already in flight" }

Aguarde a conclusão do request original antes de retentar.

Propriedades da chave de idempotência

Propriedade	Valor
Header	Idempotency-Key
Escopo	Por parceiro (X-Api-Key) — a mesma string usada por dois parceiros distintos não gera conflito
TTL	24 horas a partir da criação
Endpoints	Apenas POST /v1/payouts

Note

A idempotência é escopada por parceiro: dois parceiros diferentes podem usar o mesmo valor de Idempotency-Key sem interferência mútua.

Quando omitir o header

O header é opcional. Requests sem Idempotency-Key são processados normalmente — a chave apenas garante proteção em caso de retentativa. Se a sua integração não realiza retries automáticos, você pode omiti-la, mas é recomendado usá-la em produção.

Resumo do comportamento

Cenário	Resposta
Primeira requisição com a chave	201 Created — payout criado
Retentativa após conclusão	200 OK — payout original retornado
Retentativa enquanto em processamento	409 Conflict
Chave diferente, mesmos dados	Novo payout criado (201)
Sem header	Novo payout criado sempre (201)