EnglishConceptsIdempotency

Idempotency

POST /v1/pix accepts an externalRef in the body. This field is used as an idempotency key so that resending the same charge (network timeout, retry from your application, etc.) does not create duplicates.

How to use it

Include externalRef in the charge creation body:

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

Use a unique identifier per logical operation (e.g., your system’s order ID).

Behavior

  • Same externalRef repeated: INFI returns the original charge with HTTP 200 and an extra field "idempotent": true.
  • Missing externalRef: each call creates a new independent charge.

The idempotency key retention window is 7 days after creation. After that, the same externalRef may produce a new charge.

Scope

The idempotency key is resolved within the scope of your account. There is no collision between externalRefs of different merchants.

Withdrawals

POST /v1/withdraw accepts externalRef (optional, but strongly recommended) in the body. The behavior is the same as POST /v1/pix:

  • Same externalRef repeated: returns the original transaction with HTTP 200 and "idempotent": true. Balance is not debited again.
  • Missing externalRef: each call creates an independent withdrawal — real risk of duplication on retries.
{
  "amountCents": 5000,
  "pixKey": "12345678901",
  "pixKeyType": "cpf",
  "externalRef": "withdraw-2026-05-08-001"
}
Always use externalRef in withdrawals

Withdrawals are critical financial operations. On retry without externalRef, INFI has no way to know it is the same withdrawal and creates a new one, duplicating the outflow. Always send a unique and stable identifier (internal ID in your system, UUID, etc.).

If you did not use externalRef and the call failed with timeout, do not blindly resend. Instead:

  1. Wait a few seconds (the webhook may arrive).
  2. Query GET /v1/transactions?type=withdrawal&limit=10 to see whether it was created.
  3. Use the transactionId from the response to track it.

See also the anti-burst limits in POST /v1/withdraw — max 1 withdrawal/second and 2 withdrawals/minute per account.

Webhooks received

Webhooks sent by INFI to your endpoint do not carry a unique delivery header. Use transactionId + event as a dedup key on your side. See Webhook · Retry.

FeesCreate a PIX charge