API da Velon

Proposta de API para cobranças, vendas, reembolsos e eventos. Os exemplos abaixo são ilustrativos: não há sandbox executável nem endpoints de produção confirmados. Autenticação, assinaturas, limites e reenvios descrevem o comportamento planejado.

Autenticação

Envie sua chave secreta no cabeçalho Authorization. Nunca exponha a chave no navegador.

# base https://api.velon.com.br/v1 Authorization: Bearer vl_test_xxxxxxxxxxxxxxxx

POST/charges

Cria uma cobrança Pix, cartão ou boleto.

curl https://api.velon.com.br/v1/charges \ -H "Authorization: Bearer vl_test_xxx" \ -H "Content-Type: application/json" \ -d '{ "amount": 5990, "method": "pix", "customer": { "name": "Ana Souza", "email": "ana@exemplo.com", "document": "12345678909" }, "metadata": { "order": "1042" } }'

Resposta:

{ "id": "ch_8f3k2", "status": "pending", "amount": 5990, "method": "pix", "pix": { "qr_code": "00020126...", "expires_in": 1800 } }

GET/charges/:id

Consulta o status: pending, paid, failed, refunded.

POST/charges/:id/refund

Reembolsa a venda pelo mesmo meio de pagamento, dentro do prazo de 7 dias.

Webhooks

Enviamos um POST para a sua URL a cada evento. Valide o cabeçalho Velon-Signature (HMAC SHA-256 do corpo com o segredo do webhook) e responda 2xx em até 10 segundos. Falhas são reenviadas por até 24 horas.

{ "event": "charge.paid", "data": { "id": "ch_8f3k2", "amount": 5990, "method": "pix", "paid_at": "2026-10-02T14:03:11Z" } } // Node.js const sig = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex"); if (sig !== req.headers["velon-signature"]) return res.sendStatus(401);

Eventos

Evento	Quando acontece
charge.created	Cobrança criada
charge.paid	Pagamento aprovado
charge.failed	Pagamento recusado ou expirado
charge.refunded	Reembolso concluído
payout.paid	Saque enviado por Pix

Limites e erros

100 requisições por minuto por chave. Erros usam HTTP 4xx com { "error": { "code", "message" } }. Use o cabeçalho Idempotency-Key para repetir chamadas com segurança.

Precisa de ajuda para integrar?

Falar com o suporte