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

# Idempotência

> Processe pagamentos com segurança em redes instáveis.

Os endpoints de criação de pagamento (`POST /payments` e `POST /payments/pix`) suportam o header `Idempotency-Key`. Com ele, reenviar a mesma requisição em caso de timeout ou falha de rede nunca resultará em cobranças duplicadas.

## Como funciona

1. Gere uma chave única para cada intenção de pagamento — tipicamente o ID do pedido no seu sistema.
2. Inclua o header em todas as tentativas:

```http theme={null}
Idempotency-Key: ORD-2026-12345
```

3. Se a transação já existe para aquela chave e empresa, o backend devolve o resultado original **sem reprocessar**:

```http theme={null}
HTTP/1.1 200 OK
Idempotent-Replayed: true
```

```json theme={null}
{
  "status": "approved",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  ...
}
```

<Info>
  Quando `Idempotent-Replayed: true` estiver presente no header de resposta, o pagamento **não foi processado novamente** — você está recebendo o resultado cacheado da primeira tentativa bem-sucedida.
</Info>

## Escopo

As chaves de idempotência são escopadas por empresa (`company_id`). A mesma chave pode ser reutilizada por empresas diferentes sem colisão.

## Recomendações

| Situação                              | Recomendação                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Timeout na requisição                 | Reenvie com a **mesma** `Idempotency-Key`                                                               |
| Nova tentativa de pagamento (cliente) | Gere uma **nova** `Idempotency-Key`                                                                     |
| Formato da chave                      | Use o ID do pedido do seu sistema (ex: `ORD-2026-12345`) ou uma chave única                             |
| Ausência do header                    | O pagamento é processado normalmente, gerado um Idempotency-Key automaticamente e retornado na response |