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

# Pix

> Cobranças Pix com QR Code e copia e cola, confirmadas em segundos.

O Pix é a forma de pagamento mais rápida: o cliente paga pelo app do banco e a confirmação chega em segundos. Você pode cobrar Pix de duas formas:

* **No checkout** (link fixo ou `POST /v1/checkouts`): a Valora mostra o QR Code ao cliente.
* **Direto pela API** (`POST /v1/payments`): você recebe o QR Code e o copia e cola e mostra na sua própria tela.

## Criar uma cobrança Pix pela API

> [tab] cURL
>
> ```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": "149.90",
>     "description": "Pedido 1001",
>     "external_reference": "pedido-1001",
>     "expires_in": 1800
>   }'
> ```

> [tab] Node.js
>
> ```js theme={null}
> const res = await fetch("https://api.valorapayments.com.br/v1/payments", {
>   method: "POST",
>   headers: {
>     Authorization: `Bearer ${process.env.VALORA_API_KEY}`,
>     "Content-Type": "application/json",
>     "Idempotency-Key": "pedido-1001",
>   },
>   body: JSON.stringify({
>     method: "pix",
>     amount: "149.90",
>     description: "Pedido 1001",
>     external_reference: "pedido-1001",
>     expires_in: 1800,
>   }),
> });
> const payment = await res.json();
> // payment.pix.brcode  -> copia e cola
> // payment.pix.qr_image -> QR Code (PNG em data URL)
> ```

> [tab] Python
>
> ```python theme={null}
> import os, requests
>
> res = requests.post(
>     "https://api.valorapayments.com.br/v1/payments",
>     headers={
>         "Authorization": f"Bearer {os.environ['VALORA_API_KEY']}",
>         "Idempotency-Key": "pedido-1001",
>     },
>     json={
>         "method": "pix",
>         "amount": "149.90",
>         "description": "Pedido 1001",
>         "external_reference": "pedido-1001",
>         "expires_in": 1800,
>     },
> )
> payment = res.json()
> ```

### Valor: em reais ou pelo produto

Envie **um** dos dois:

* `amount`: valor em reais, como texto ou número, com até 2 casas (`"149.90"`, `149.9`).
* `product_id` + `quantity`: a Valora calcula o valor pelo preço do produto. O cliente não consegue mudar o preço.

> [!WARNING]
>
> Na entrada, o valor vai em **reais**. Nas respostas, todo valor vem em **centavos inteiros**: `"149.90"` volta como `14990`.

### Validade

`expires_in` define quanto tempo o Pix vale, em segundos: de 60 (1 min) a 86400 (24 h). O padrão é 3600 (1 h). Depois disso, o pagamento muda para `expired` e você recebe `payment.expired`.

### Exibir para o cliente

| Campo | Uso |
| - | - |
| `pix.qr_image` | QR Code em PNG, pronto para `<img src="...">` |
| `pix.brcode` | código copia e cola |
| `expires_at` | prazo para mostrar um cronômetro |

## Ciclo de vida

```mermaid theme={null}
flowchart LR
  A[requires_payment] -->|cliente paga| B[succeeded]
  A -->|prazo acaba| C[expired]
  A -->|você cancela| D[canceled]
  B -->|devolução parcial| E[partially_refunded]
  B -->|devolução total| F[refunded]
  E --> F
```

| Status | Significado | Evento |
| - | - | - |
| `requires_payment` | Pix criado, aguardando pagamento | — |
| `succeeded` | pago e confirmado | `payment.succeeded` |
| `expired` | o prazo acabou sem pagamento | `payment.expired` |
| `canceled` | cancelado por você antes do pagamento | `payment.canceled` |
| `partially_refunded` / `refunded` | parte ou todo o valor foi devolvido ao pagador | `payment.refunded` |

> [!NOTE]
>
> Um Pix pago com valor diferente do cobrado, ou pago depois de cancelado, não vira crédito automaticamente. Ele fica marcado para análise da Valora e não libera o pedido.

## Quem pagou

Depois da confirmação, `pix.payer` traz o nome e o documento **mascarado** de quem pagou, e `pix.e2e_id` traz o identificador da transação no Banco Central. Use para conciliar e para atender o cliente.

## Cancelar um Pix

Enquanto o Pix está em `requires_payment`, você pode cancelar com `POST /v1/payments/{payment_id}/cancel`. O QR Code deixa de valer.

## Saldo

O valor de um Pix confirmado entra no saldo **disponível** na hora, já descontada a taxa.

## Próximos passos

> [card] [Devoluções](https://dev.valorapayments.com.br/recursos/devolucoes-e-contestacoes.md)
>
> Devolva todo ou parte de um Pix ao pagador.

> [card] [Idempotência](https://dev.valorapayments.com.br/integrar/idempotencia.md)
>
> Evite cobrar duas vezes o mesmo pedido.


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