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

# Idempotência

> Evite movimentação financeira duplicada tratando external_ref como identificador estável de escrita.

Use idempotência em todo caminho de escrita que possa ser repetido por usuário, fila, worker ou cliente de rede.

## Regra recomendada

Use `external_ref` como identificador estável de uma operação lógica de criação.

* Reutilize o mesmo valor ao repetir a mesma criação de pagamento ou transferência.
* Nunca reutilize o mesmo valor para uma intenção financeira diferente.
* Persista o seu `external_ref` e o `id` do recurso na Pagou.

## Exemplo de requisição

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

## Exemplo de resposta com sucesso

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

## Erro comum

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."
}
```

Como corrigir: se a repetição se refere à mesma operação de negócio, reconcilie o recurso existente em vez de enviar uma nova criação com outra intenção.

## Onde isso mais importa

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

## Padrão de retentativa

1. Só repita com segurança quando você puder provar que é a mesma operação lógica.
2. Se a resposta de uma escrita se perder, reconcilie com `GET` antes de criar outro recurso.
3. Mantenha `requestId`, ID do recurso e `external_ref` no mesmo registro de auditoria.