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

# Chaves de API

> Crie chaves por ambiente, limite o que cada uma pode fazer com escopos e revogue quando precisar.

Toda requisição à API leva uma chave no header `Authorization`. A chave identifica o seu negócio, define o ambiente (teste ou produção) e limita o que pode ser feito.

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

## Criar uma chave

**1. Abra o painel**

Entre no [painel](https://console.valorapayments.com.br), vá em **Desenvolvedores → Chaves de API** e clique em **Criar chave de API**. Dê um nome que diga onde a chave é usada (ex.: "Servidor de produção").

**2. Escolha o ambiente**

**Sandbox** para testes ou **Production** para cobranças reais. O ambiente não muda depois.

**3. Escolha os escopos**

Em **Permissões da chave**, marque só o que a integração usa. Uma chave sem permissões marcadas pode usar todas as rotas.

**4. Copie e guarde**

A chave aparece uma única vez. Guarde num cofre de segredos ou numa variável de ambiente do servidor.

## Formato

As chaves começam com `sk_vl_` seguido de 48 caracteres hexadecimais. Uma chave com formato errado é recusada com `401 invalid_api_key` antes de qualquer consulta.

## Escopos

| Escopo | Permite |
| - | - |
| `payments:read` | listar e consultar pagamentos |
| `payments:write` | criar, cancelar e devolver pagamentos |
| `checkouts:read` | consultar compras criadas pela API |
| `checkouts:write` | criar compras (`POST /v1/checkouts`) |
| `customers:read` | listar e consultar clientes |
| `customers:write` | criar e atualizar clientes |
| `products:read` | listar e consultar produtos |
| `products:write` | criar e atualizar produtos |
| `webhooks:read` | listar webhooks e entregas |
| `webhooks:write` | criar, remover, rotacionar o segredo e reenviar entregas |
| `balance:read` | consultar o saldo |

Uma chamada sem o escopo necessário responde `403 missing_scope`.

> [!TIP]
>
> Separe chaves por uso. Por exemplo: uma chave só com `checkouts:write` e `payments:read` para a loja, e outra com `webhooks:write` usada só na configuração.

## Revogar uma chave

Se uma chave vazou ou não é mais usada, revogue no painel em **Desenvolvedores → Chaves de API** e crie outra. A revogação vale em até 15 segundos.

> [!WARNING]
>
> Nunca envie a chave para o navegador, o app do cliente, logs ou repositórios. Quem tem a chave age em nome do seu negócio.

## Isolamento por negócio

Cada chave só enxerga os dados do próprio negócio. Pedir um pagamento, cliente ou produto de outro negócio responde `404 not_found`, como se ele não existisse.


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