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

   export VALORA_API_KEY="sk_vl_..."
   

   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:

   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

   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:

   {
     "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:

   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 como simular o pagamento e acompanhe a entrega do evento em Desenvolvedores → Webhooks no painel.

Próximos passos

Checkout pela API

Deixe o cliente escolher entre Pix, cartão e boleto numa página pronta.

Webhooks

Assinatura, novas tentativas e reenvio de entregas.

Checklist de produção

O que conferir antes de vender de verdade.

Referência da API

Todos os endpoints e campos.