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

# Início rápido

> Crie uma chave de teste, gere sua primeira cobrança Pix e receba a confirmação por webhook.

Neste guia, você sai de uma conta nova até uma cobrança Pix criada pela API e confirmada no seu servidor. Tudo acontece no ambiente de teste, sem dinheiro real.

## Pré-requisitos

* Uma conta no [painel da Valora](https://console.valorapayments.com.br).
* Um servidor que faça requisições HTTPS (os exemplos usam `curl` e Node.js 18+).
* Para receber webhooks, uma URL pública com HTTPS. Em desenvolvimento, use um túnel como o ngrok ou o Cloudflare Tunnel.

## Faça sua primeira cobrança

**1. Crie uma chave de teste**

No painel, abra **Desenvolvedores → Chaves de API** e crie uma chave no ambiente **Sandbox**. Copie a chave (`sk_vl_...`) e guarde numa variável de ambiente do servidor.

```bash theme={null}
export VALORA_API_KEY="sk_vl_..."
```

> [!WARNING]
>
> A chave dá acesso aos dados do seu negócio. Use só no servidor. Nunca coloque no navegador, no app ou no repositório.

**2. Cadastre um webhook**

O webhook avisa o seu servidor quando o pagamento é confirmado. Cadastre a URL que vai receber os eventos:

```bash theme={null}
curl https://api.valorapayments.com.br/v1/webhooks \
  -H "Authorization: Bearer $VALORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://seu-dominio.com/webhooks/valora", "events": ["payment.succeeded"] }'
```

A resposta traz o campo `secret` (`whsec_...`). Ele aparece **só agora**. Guarde junto com a chave: é ele que valida a assinatura de cada evento.

**3. Crie uma cobrança Pix**

```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", "external_reference": "pedido-1001" }'
```

A resposta (`201`) traz o pagamento com `status: "requires_payment"` e os dados do Pix:

```json theme={null}
{
  "id": "pay_Xk2v9QeR7tLmN3bA",
  "object": "payment",
  "livemode": false,
  "method": "pix",
  "status": "requires_payment",
  "amount": { "value": 4990, "currency": "BRL" },
  "external_reference": "pedido-1001",
  "pix": {
    "txid": "...",
    "brcode": "00020101021226...",
    "qr_image": "data:image/png;base64,..."
  },
  "expires_at": "2026-11-14T19:00:00.000Z"
}
```

Mostre ao cliente o `pix.qr_image` (QR Code) ou o `pix.brcode` (código copia e cola).

**4. Confirme o pagamento no webhook**

Quando o Pix é pago, a Valora envia `payment.succeeded` para a sua URL. Valide a assinatura antes de liberar o pedido:

```js theme={null}
import crypto from "node:crypto";
import express from "express";

const app = express();

// Use o corpo CRU: a assinatura é calculada sobre os bytes exatos que chegaram.
app.post("/webhooks/valora", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Valora-Signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const raw = req.body.toString("utf8");
  const expected = crypto
    .createHmac("sha256", process.env.VALORA_WEBHOOK_SECRET)
    .update(`${parts.t}.${raw}`)
    .digest("hex");

  const valid =
    typeof parts.v1 === "string" &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  const recent = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  if (!valid || !recent) return res.sendStatus(400);

  const event = JSON.parse(raw);
  if (event.type === "payment.succeeded") {
    const payment = event.data.object;
    // Libere o pedido payment.external_reference (uma vez só, mesmo que o evento chegue de novo).
  }
  res.sendStatus(200);
});

app.listen(3000);
```

**5. Pague o Pix de teste**

No ambiente de teste, nenhum dinheiro real se move. Veja em [Testes](https://dev.valorapayments.com.br/integrar/testes.md) como simular o pagamento e acompanhe a entrega do evento em **Desenvolvedores → Webhooks** no painel.

## Próximos passos

> [card] [Checkout pela API](https://dev.valorapayments.com.br/recursos/checkouts.md)
>
> Deixe o cliente escolher entre Pix, cartão e boleto numa página pronta.

> [card] [Webhooks](https://dev.valorapayments.com.br/integrar/webhooks.md)
>
> Assinatura, novas tentativas e reenvio de entregas.

> [card] [Checklist de produção](https://dev.valorapayments.com.br/integrar/producao.md)
>
> O que conferir antes de vender de verdade.

> [card] [Referência da API](https://dev.valorapayments.com.br/api-reference/introducao.md)
>
> Todos os endpoints e campos.


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