PortuguêsConceitosIdempotência

Idempotência

POST /v1/pix aceita um externalRef no corpo. Esse campo é usado como chave de idempotência para que reenvios da mesma cobrança (por timeout de rede, retry da sua aplicação, etc.) não criem duplicatas.

Como usar

Inclua externalRef no corpo da criação de cobrança:

{
  "amountCents": 1000,
  "externalRef": "pedido-123",
  "customer": { /* ... */ }
}

Use um identificador único por operação lógica (ex.: ID do pedido no seu sistema).

Comportamento

  • Mesma externalRef repetida: a INFI retorna a cobrança original com HTTP 200 e o campo extra "idempotent": true.
  • externalRef ausente: cada chamada cria uma nova cobrança independente.

A janela de retenção da chave de idempotência é de 7 dias após criação. Após isso, a mesma externalRef pode produzir nova cobrança.

Escopo

A chave de idempotência é resolvida dentro do escopo da sua conta. Não há colisão entre externalRef de lojistas diferentes.

Saques

POST /v1/withdraw aceita externalRef (opcional, mas fortemente recomendado) no corpo. O comportamento é o mesmo de POST /v1/pix:

  • Mesma externalRef repetida: retorna a transação original com HTTP 200 e "idempotent": true. Saldo não é debitado novamente.
  • externalRef ausente: cada chamada cria um saque independente — risco real de duplicação em retry.
{
  "amountCents": 5000,
  "pixKey": "12345678901",
  "pixKeyType": "cpf",
  "externalRef": "withdraw-2026-05-08-001"
}
Use sempre externalRef em saques

Saques são operações financeiras críticas. Em retry sem externalRef, a INFI não tem como saber que é o mesmo saque e cria um novo, duplicando a saída de dinheiro. Sempre envie um identificador único e estável (ID interno do seu sistema, UUID, etc.).

Se você não usou externalRef e a chamada falhou com timeout, não reenvie cegamente. Em vez disso:

  1. Aguarde alguns segundos (o webhook pode chegar).
  2. Consulte GET /v1/transactions?type=withdrawal&limit=10 para ver se foi criado.
  3. Use o transactionId da resposta para acompanhar.

Veja também os limites anti-burst em POST /v1/withdraw — máximo 1 saque/segundo e 2 saques/minuto por conta.

Webhooks recebidos

Webhooks emitidos pela INFI para o seu endpoint não têm cabeçalho de delivery único. Use transactionId + event como chave de deduplicação no seu lado. Veja Webhook · Retentativa.

TaxasCriar cobrança PIX