Quickstart
Faça sua primeira cobrança em menos de 5 minutos.
A API é HTTP + JSON, em https://api.kirvex.com.br. Os exemplos usam curl e
o fetch do Node 18+; qualquer linguagem com cliente HTTP serve. Chave,
Idempotency-Key e a assinatura opcional dos pedidos estão em
Autenticação.
Cobrança Pix
curl -X POST https://api.kirvex.com.br/v1/charges \
-u "$KIRVEX_SECRET_KEY:" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1234-tentativa-1" \
-d '{
"amount": { "amount": "9990", "currency": "BRL" },
"method": "pix",
"description": "Pedido #1234",
"customer": {
"email": "ada@lovelace.com",
"name": "Ada Lovelace",
"document": "12345678909",
"phone": "+5511987654321",
"address": {
"zipcode": "01310100",
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP"
}
},
"pix": { "expiresInSeconds": 3600 }
}'
const res = await fetch('https://api.kirvex.com.br/v1/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.KIRVEX_SECRET_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'pedido-1234-tentativa-1', // única por intenção
},
body: JSON.stringify({
amount: { amount: '9990', currency: 'BRL' },
method: 'pix',
description: 'Pedido #1234',
customer: {
email: 'ada@lovelace.com',
name: 'Ada Lovelace',
document: '12345678909',
phone: '+5511987654321', // a Pagar.me exige telefone e endereço
address: {
zipcode: '01310100',
street: 'Avenida Paulista',
number: '1000',
neighborhood: 'Bela Vista',
city: 'São Paulo',
state: 'SP',
},
},
pix: { expiresInSeconds: 3600 },
}),
});
const charge = await res.json();
console.log(charge.id, charge.status); // ch_..., pending
console.log(charge.pix?.qrCode); // Pix copia e cola para o comprador
A cobrança nasce pending. Quando o comprador paga, ela passa a succeeded e
você recebe o evento charge.succeeded.
phone e address são exigidos pela Pagar.me em todo pedido. Sem eles, a
cobrança vai para outra adquirente ou volta 503 (formatos em
Telefone e endereço do comprador).
Webhook
Cadastre o endpoint que vai receber os eventos:
curl -X POST https://api.kirvex.com.br/v1/webhook_endpoints \
-u "$KIRVEX_SECRET_KEY:" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-endpoint-1" \
-d '{
"url": "https://seuapp.com/webhooks/kirvex",
"event_types": ["charge.succeeded", "charge.failed", "charge.refunded"]
}'
A resposta traz o secret do endpoint. Guarde: ele só aparece uma vez.
No seu endpoint, valide a assinatura. O cabeçalho X-Kirvex-Signature vem no
formato t=<unix>,v1=<hex>, e v1 é o HMAC SHA-256 de <t>.<corpo cru> com o
secret do endpoint (detalhes em Webhooks):
import { createHmac, timingSafeEqual } from 'node:crypto';
const header = req.headers['x-kirvex-signature']!;
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
const expected = createHmac('sha256', SECRET).update(`${parts.t}.${rawBody}`).digest('hex');
if (
!parts.v1 ||
parts.v1.length !== expected.length ||
!timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'))
) {
return res.status(401).end();
}
Refund
curl -X POST https://api.kirvex.com.br/v1/charges/ch_.../refund \
-u "$KIRVEX_SECRET_KEY:" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund-pedido-1234-tentativa-1" \
-d '{ "amount": { "amount": "5000", "currency": "BRL" }, "reason": "cliente desistiu" }'
Sem amount, o estorno é do valor inteiro.
Próximos passos
- Autenticação — chave, Idempotency-Key e assinatura dos pedidos
- Erros — todos os códigos retornados
- POST /v1/charges — referência da rota principal
/openapi.json— spec completa