---
title: "Idempotencia"
description: "Evitar pagos duplicados al reintentar escrituras con Idempotency-Key."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.pagofast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotencia

# 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:

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

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

```http
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:

```text
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.

```text
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:

```http
409 Conflict
```

```json
{
  "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`.

Source: https://docs.pagofast.com/idempotency/index.mdx