Idempotencia

Una clave de idempotencia identifica un intento lógico de escritura. Permite repetir un request cuando se corta la conexión o vence el timeout sin crear otra operación.

Operaciones

Usá una clave distinta para cada operación lógica:

POST /v1/payments
Idempotency-Key: order-9821-payment-1

POST /v1/payments/{payment_id}/cancel
Idempotency-Key: order-9821-cancel-1

POST /v1/payments/{payment_id}/refunds
Idempotency-Key: order-9821-refund-1

Cómo elegir la clave

Una clave debe ser:

• única para el intento lógico, no para cada envío HTTP;
• estable durante todos los retries de ese intento;
• suficientemente difícil de colisionar;
• ajena a secretos o datos personales.

Una combinación como {order_id}-{operation}-{attempt} o un UUID generado y persistido antes del request suele ser adecuada. No uses timestamps generados en cada retry.

Alcance

La unicidad se evalúa por:

api_key_id + operación + idempotency_key

Por eso una clave de creación no sustituye la clave de cancelación o reembolso. Aun así, usar nombres explícitos facilita la operación y el soporte.

Repetición válida

Si repetís la misma operación, clave y body, PagoFast devuelve el status y body previamente guardados. El replay evita duplicar la operación lógica; no significa que el estado externo no pueda evolucionar después mediante consulta o webhook.

POST #1 → la red se corta después de enviar
POST #2 con misma key y mismo body → respuesta almacenada

Reutilización inválida

La misma clave con un body distinto devuelve:

409 Conflict

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "La clave de idempotencia ya fue utilizada con una solicitud diferente.",
    "category": "conflict",
    "retryable": false,
    "request_id": "req_019f704f89d77e83",
    "details": {}
  }
}

No resuelvas este error generando automáticamente otra clave: podrías duplicar un cobro. Investigá qué body corresponde al intento original.

Concurrencia

Si dos requests idénticos con la misma clave llegan al mismo tiempo, ambos representan una sola operación. El segundo puede esperar o recibir la respuesta almacenada según el estado de procesamiento. Si recibís un error transitorio, respetá retryable y repetí con la misma clave y body.

Relación con external_reference

Idempotency-Key deduplica envíos de una operación. external_reference identifica el pago en tu dominio y es único por API key. Son controles complementarios:

• retry del mismo intento: misma key y mismo external_reference;
• nuevo intento autorizado para la misma orden: nueva key y una referencia externa distinta o estrategia acordada;
• misma referencia ya usada: 409 external_reference_conflict, incluso si el pago anterior falló.

Algoritmo de retry recomendado

1. Persistir key, body e intención antes de enviar.
2. Enviar el request.
3. Si hay respuesta, guardar payment.id, status y X-Request-Id.
4. Ante desconexión o timeout, no crear otra intención.
5. Repetir exactamente el mismo request con la misma key.
6. Si el resultado sigue incierto y conocés payment.id, consultarlo.
7. Procesar los webhooks posteriores de manera idempotente.

Si falta el header, la API devuelve 400 idempotency_key_required.