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

> ## Agent Instructions
> Valora Payments API (Brazil: Pix, card, boleto). Base URL https://api.valorapayments.com.br, Authorization: Bearer sk_vl_... used only on the server. Request amounts are reais as strings ("149.90"); response amounts are integer cents (14990). Use POST /v1/checkouts for card and boleto; POST /v1/payments only creates Pix and should send an Idempotency-Key. Confirm payments only through the payment.succeeded webhook after verifying X-Valora-Signature (hex HMAC-SHA256 of "<t>.<raw body>"), dedupe by event.id and check livemode. Never invent endpoints or fields: check /llms.txt and /openapi.json.

# Idempotência

> Repita a criação de um pagamento com segurança, sem cobrar o cliente duas vezes.

Uma requisição pode falhar no meio do caminho: a rede cai, o servidor reinicia, o tempo esgota. Nesses casos você não sabe se a cobrança foi criada. O header `Idempotency-Key` resolve isso: repetir a mesma requisição com a mesma chave devolve a cobrança já criada em vez de criar outra.

## Como usar

Envie o header em `POST /v1/payments`, com um valor único por operação (até 200 caracteres):

```bash theme={null}
curl https://api.valorapayments.com.br/v1/payments \
  -H "Authorization: Bearer $VALORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1001" \
  -d '{ "method": "pix", "amount": "49.90" }'
```

## O que acontece em cada caso

| Situação | Resposta |
| - | - |
| Primeira requisição | `201 Created`, cobrança nova |
| Mesma chave, **mesmo corpo** | `200 OK` com a cobrança já criada e o header `Idempotent-Replayed: true` |
| Mesma chave, **corpo diferente** | `409 idempotency_conflict`, nada é criado |

## Boas práticas

* Use um identificador da sua operação, como o id do pedido: `pedido-1001`. Assim, uma nova tentativa sempre reaproveita a mesma chave.
* Gere uma chave nova para uma cobrança **nova** do mesmo pedido (por exemplo, depois que o Pix anterior expirou): `pedido-1001-2`.
* Em erros `5xx` e de rede, repita com a **mesma** chave. Em erros `4xx`, corrija o corpo antes de tentar de novo.

> [!NOTE]
>
> Hoje a idempotência vale para a criação de pagamentos (`POST /v1/payments`). Para as outras criações, guarde o `id` retornado e consulte antes de repetir.


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