> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Prevent duplicate money movement by treating external_ref as your stable write identifier.

Use idempotency on every write path that can be retried by a user, queue, worker, or network client.

## Recommended rule

Use `external_ref` as the stable identifier for a logical create operation.

* Reuse the same value when retrying the same payment or transfer create.
* Never reuse the same value for a different monetary intent.
* Persist both your `external_ref` and the Pagou resource `id`.

## Example request

```json theme={null}
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix"
}
```

## Example success response

```json theme={null}
{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "status": "pending"
  }
}
```

## Common error

Status `409`

```json theme={null}
{
  "type": "https://api.pagou.ai/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A transaction with external_ref order_1001 already exists."
}
```

Fix: if the retry refers to the same business operation, reconcile the existing resource instead of sending a new create with different intent.

## Where it matters most

* `POST /v2/transactions`
* `PUT /v2/transactions/{id}/refund`
* `POST /v2/transfers`
* `POST /v2/transfers/{id}/cancel`

## Retry pattern

1. Retry safely only when you can prove it is the same logical operation.
2. If a write response is lost, reconcile with `GET` before creating another resource.
3. Keep `requestId`, resource ID, and `external_ref` in the same audit record.