EspañolConceptosIdempotencia

Idempotencia

POST /v1/pix acepta un externalRef en el cuerpo. Ese campo se usa como clave de idempotencia para que los reenvíos del mismo cobro (timeout de red, retry de tu aplicación, etc.) no creen duplicados.

Cómo usarla

Incluye externalRef en el cuerpo de creación del cobro:

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

Usa un identificador único por operación lógica (p.ej. el ID del pedido en tu sistema).

Comportamiento

  • Mismo externalRef repetido: INFI devuelve el cobro original con HTTP 200 y el campo extra "idempotent": true.
  • externalRef ausente: cada llamada crea un nuevo cobro independiente.

La ventana de retención de la clave de idempotencia es de 7 días tras la creación. Después de eso, el mismo externalRef puede generar un nuevo cobro.

Alcance

La clave de idempotencia se resuelve dentro del alcance de tu cuenta. No hay colisión entre externalRef de comerciantes distintos.

Retiros

POST /v1/withdraw acepta externalRef (opcional, pero muy recomendado) en el cuerpo. El comportamiento es el mismo que en POST /v1/pix:

  • Mismo externalRef repetido: devuelve la transacción original con HTTP 200 y "idempotent": true. El saldo no se debita de nuevo.
  • externalRef ausente: cada llamada crea un retiro independiente — riesgo real de duplicación en reintentos.
{
  "amountCents": 5000,
  "pixKey": "12345678901",
  "pixKeyType": "cpf",
  "externalRef": "withdraw-2026-05-08-001"
}
Usa siempre externalRef en retiros

Los retiros son operaciones financieras críticas. En reintento sin externalRef, INFI no tiene cómo saber que es el mismo retiro y crea uno nuevo, duplicando la salida. Envía siempre un identificador único y estable (ID interno de tu sistema, UUID, etc.).

Si no usaste externalRef y la llamada falló con timeout, no reenvíes a ciegas. En su lugar:

  1. Espera unos segundos (el webhook puede llegar).
  2. Consulta GET /v1/transactions?type=withdrawal&limit=10 para ver si fue creado.
  3. Usa el transactionId de la respuesta para hacer seguimiento.

Ver también los límites anti-burst en POST /v1/withdraw — máximo 1 retiro/segundo y 2 retiros/minuto por cuenta.

Webhooks recibidos

Los webhooks emitidos por INFI a tu endpoint no traen un encabezado único de entrega. Usa transactionId + event como clave de deduplicación de tu lado. Ver Webhook · Reintento.

TarifasCrear cobro PIX