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

# Idempotência

> Evite cobranças e devoluções duplicadas quando houver timeout ou repetição.

`POST /v1/payment-intents` exige `Idempotency-Key` com 16 a 128 caracteres formados por letras, números, ponto, sublinhado ou hífen.

```http theme={"system"}
Idempotency-Key: pedido-1024-cobranca-001
```

A mesma chave, rota e corpo reproduzem a resposta anterior e incluem `idempotent-replayed: true`. Reutilizar a chave com outro corpo ou outra operação retorna `409 idempotency_conflict`.

## Como gerar a chave

Use uma referência estável para a mesma tentativa, por exemplo `pedido-{id}-cobranca-{tentativa}`. Uma nova tentativa lógica deve receber outra chave.

## Em caso de timeout

**1. Não crie outra chave**

Repita a requisição com a mesma chave e exatamente o mesmo corpo.

**2. Leia a resposta reproduzida**

Se a primeira tentativa terminou, a API devolve o resultado persistido.

**3. Reconcilie pelo UUID**

Quando tiver o `id`, consulte a cobrança antes de tomar outra ação.

Devoluções também exigem `Idempotency-Key`, com 8 a 100 caracteres. A deduplicação de webhooks é separada: persista o `id` de cada evento processado.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.