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

# Catálogo de eventos

> Todos os eventos de webhook da Valora, quando cada um chega e o que fazer.

Todos os eventos têm o mesmo envelope. O pagamento completo vem em `data.object`.

```json theme={null}
{
  "id": "evt_...",
  "object": "event",
  "type": "payment.succeeded",
  "livemode": true,
  "created": "2026-11-14T15:02:11.000Z",
  "data": { "object": { "id": "pay_...", "object": "payment", "status": "succeeded" } }
}
```

## Pagamentos

| Evento | Quando chega | Status do pagamento |
| - | - | - |
| `payment.succeeded` | o pagamento foi confirmado (Pix, cartão aprovado ou boleto pago) | `succeeded` |
| `payment.failed` | o cartão foi recusado ou a cobrança não pôde ser criada | `failed` |
| `payment.expired` | o Pix ou o boleto venceu sem pagamento | `expired` |
| `payment.canceled` | a cobrança foi cancelada antes do pagamento | `canceled` |
| `payment.refunded` | parte ou todo o valor foi devolvido ao pagador | `partially_refunded` ou `refunded` |
| `payment.disputed` | o comprador contestou a compra no cartão | `disputed` |
| `payment.dispute_won` | a contestação terminou a seu favor | `succeeded` |
| `payment.dispute_lost` | a contestação terminou a favor do comprador | `refunded` |

Use `"*"` em `events` para receber todos, inclusive os que forem criados no futuro.

## Exemplos

> [accordion] payment.succeeded (Pix)
>
> ```json theme={null}
> {
>   "id": "evt_Mn45Bv67Cx89Za01",
>   "object": "event",
>   "type": "payment.succeeded",
>   "livemode": true,
>   "created": "2026-11-14T15:02:11.000Z",
>   "data": {
>     "object": {
>       "id": "pay_Xk2v9QeR7tLmN3bA",
>       "object": "payment",
>       "livemode": true,
>       "method": "pix",
>       "status": "succeeded",
>       "amount": { "value": 14990, "currency": "BRL" },
>       "customer_id": null,
>       "external_reference": "pedido-1001",
>       "description": "Pedido 1001",
>       "metadata": { "order_id": "1001" },
>       "fee": { "bps": 99, "fixed": 0, "amount": 148 },
>       "refunded_amount": 0,
>       "dispute": null,
>       "items": [],
>       "splits": [],
>       "expires_at": "2026-11-14T15:30:00.000Z",
>       "succeeded_at": "2026-11-14T15:02:10.000Z",
>       "created_at": "2026-11-14T15:00:00.000Z",
>       "pix": {
>         "txid": "...",
>         "e2e_id": "E1234567820261114150210...",
>         "brcode": "00020101021226...",
>         "qr_image": "data:image/png;base64,...",
>         "payer": { "name": "ANA SOUZA", "document_masked": "***.456.789-**" }
>       }
>     }
>   }
> }
> ```

> [accordion] payment.failed (cartão recusado)
>
> ```json theme={null}
> {
>   "id": "evt_Pl12Ok34Ij56Uh78",
>   "object": "event",
>   "type": "payment.failed",
>   "livemode": true,
>   "created": "2026-11-14T16:10:00.000Z",
>   "data": {
>     "object": {
>       "id": "pay_Cd34Ef56Gh78Ij90",
>       "object": "payment",
>       "method": "card",
>       "status": "failed",
>       "amount": { "value": 29900, "currency": "BRL" },
>       "card": { "brand": "mastercard", "last4": "1234", "installments": 3, "decline_reason": "Transação não autorizada pelo emissor" }
>     }
>   }
> }
> ```

> [accordion] payment.refunded (devolução parcial)
>
> ```json theme={null}
> {
>   "id": "evt_Qa12Ws34Ed56Rf78",
>   "object": "event",
>   "type": "payment.refunded",
>   "livemode": true,
>   "created": "2026-11-15T10:00:00.000Z",
>   "data": {
>     "object": {
>       "id": "pay_Xk2v9QeR7tLmN3bA",
>       "object": "payment",
>       "method": "pix",
>       "status": "partially_refunded",
>       "amount": { "value": 14990, "currency": "BRL" },
>       "refunded_amount": 2000
>     }
>   }
> }
> ```

> [!NOTE]
>
> Os exemplos de falha e devolução mostram só os campos principais. Na entrega real, `data.object` sempre traz o pagamento completo.


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