Quickstart

Instalação do SDK

npm install @kirvex/sdk

Inicialização

import { Kirvex } from '@kirvex/sdk';

const ap = new Kirvex({
  apiKey: process.env.KIRVEX_KEY!,           // sk_test_... ou sk_live_...
  // URL única: https://api.kirvex.com.br. A chave decide o modo: sk_test_ vai
  // para o sandbox do adquirente e nunca cobra de verdade (veja /docs/v1/charges).
});

Cobrança Pix

const charge = await ap.charges.create(
  {
    amount: { amount: '9990', currency: 'BRL' },
    method: 'pix',
    description: 'Pedido #1234',
    customer: {
      email: 'ada@lovelace.com',
      name: 'Ada Lovelace',
      document: '12345678909',
    },
    pix: { expiresInSeconds: 3600 },
  },
  'pedido-1234-tentativa-1',  // Idempotency-Key (qualquer string única por intenção)
);

console.log(charge.pix?.qrCode);

Webhook

Receba o evento charge.succeeded quando o pagamento for confirmado:

const ep = await ap.webhookEndpoints.create({
  url: 'https://seuapp.com/webhooks/kirvex',
  event_types: ['charge.succeeded', 'charge.failed', 'charge.refunded'],
});
console.log(ep.secret); // guarde — só mostra 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

const refund = await ap.charges.refund(
  charge.id,
  { amount: { amount: '5000', currency: 'BRL' }, reason: 'cliente desistiu' },
  'refund-pedido-1234-tentativa-1',
);

Próximos passos

• Erros — todos os códigos retornados
• POST /v1/charges — referência da rota principal
• /openapi.json — spec completa