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

# Referência da API

> URL, autenticação, formato das respostas, limites e convenções da API REST da Valora.

A API da Valora é REST, recebe e devolve JSON e usa os status HTTP padrão. Todas as rotas ficam em `/v1`.

> [card] [Início rápido](https://dev.valorapayments.com.br/quickstart.md)
>
> A primeira cobrança em poucos minutos.

> [card] [Webhooks](https://dev.valorapayments.com.br/integrar/webhooks.md)
>
> Confirmação dos pagamentos no seu servidor.

## URL base

```text theme={null}
https://api.valorapayments.com.br
```

A mesma URL atende teste e produção. O ambiente vem da chave usada. Veja [Teste e produção](https://dev.valorapayments.com.br/conceitos/ambientes.md).

## Autenticação

Envie a chave no header `Authorization`, no formato Bearer:

```bash theme={null}
curl https://api.valorapayments.com.br/v1/payments \
  -H "Authorization: Bearer sk_vl_..."
```

| Situação | Resposta |
| - | - |
| Sem header ou com formato inválido | `401 invalid_api_key` |
| Chave revogada ou inexistente | `401 invalid_api_key` |
| Chave sem o escopo da rota | `403 missing_scope` |
| Chave de produção com a empresa ainda em análise | `403 business_not_active` |

> [!WARNING]
>
> Use a chave só no servidor. Veja [Chaves de API](https://dev.valorapayments.com.br/conceitos/chaves-de-api.md) para escopos e revogação.

## Convenções

### Dinheiro

| Onde | Formato | Exemplo |
| - | - | - |
| Entrada (corpo da requisição) | reais, texto ou número, até 2 casas, ponto decimal | `"149.90"` |
| Saída (respostas e webhooks) | centavos, inteiro | `14990` |

A moeda é sempre `BRL`. O valor mínimo é `0.01`.

### Ids

Todo objeto tem um id com prefixo:

| Prefixo | Objeto |
| - | - |
| `pay_` | pagamento |
| `cs_` | compra (sessão de checkout) |
| `cus_` | cliente |
| `prod_` | produto |
| `ref_` | devolução |
| `we_` | endpoint de webhook |
| `whd_` | entrega de webhook |
| `evt_` | evento |

### Datas

Datas vêm em ISO 8601, em UTC: `2026-11-14T15:02:11.000Z`.

### Campos opcionais

Campos sem valor vêm como `null`, nunca omitidos. Nas rotas `PATCH`, enviar `null` limpa o campo.

### `external_reference` e `metadata`

* `external_reference`: o seu identificador (id do pedido, SKU), até 100 caracteres. Use para conciliar e para buscar.
* `metadata`: até 20 pares de chave e valor em texto (chave até 40, valor até 500 caracteres). Volta igual em todas as respostas e webhooks.

> [!NOTE]
>
> Não coloque dados sensíveis (senhas, números de cartão, documentos completos) em `metadata`.

## Respostas

Sucesso: o objeto, ou uma lista.

```json theme={null}
{ "id": "pay_Xk2v9QeR7tLmN3bA", "object": "payment", "status": "succeeded" }
```

Erro: sempre no mesmo formato. Veja [Erros](https://dev.valorapayments.com.br/api-reference/erros.md).

```json theme={null}
{ "error": { "type": "not_found", "message": "Pagamento não encontrado." } }
```

## Limites

| Limite | Valor |
| - | - |
| Requisições por chave | 300 por minuto |
| Requisições sem chave válida | 60 por minuto por IP |
| Tamanho do corpo | 256 KB |

Passou do limite? A resposta é `429 rate_limited` com o header `Retry-After` (em segundos).

## Recursos

> [card] [Pagamentos](https://dev.valorapayments.com.br/recursos/pix.md)
>
> Cobranças Pix, cancelamento e devolução.

> [card] [Checkouts](https://dev.valorapayments.com.br/recursos/checkouts.md)
>
> Compras com página de pagamento pronta.

> [card] [Clientes](https://dev.valorapayments.com.br/recursos/clientes.md)
>
> Dados de quem compra.

> [card] [Produtos](https://dev.valorapayments.com.br/recursos/produtos.md)
>
> Catálogo e preços.

> [card] [Saldo](https://dev.valorapayments.com.br/recursos/saldo-e-saques.md)
>
> Disponível e a liberar.

> [card] [Webhooks](https://dev.valorapayments.com.br/integrar/webhooks.md)
>
> Endpoints, entregas e segredos.


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