DOCS

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

On this page