SDKs

SDKs Oficiais

Linguagem	Pacote	Versão mínima	Instalação
TypeScript / Node.js	@kirvex/sdk	Node 20+	npm install @kirvex/sdk
PHP	kirvex/sdk	PHP 8.2+	composer require kirvex/sdk
Python	kirvex	Python 3.11+	pip install kirvex

TypeScript

npm install @kirvex/sdk

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

const ap = new Kirvex({
  apiKey: 'sk_test_...',
  // 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).
});

const charge = await ap.charges.create(
  {
    amount: { amount: '9990', currency: 'BRL' },
    method: 'pix',
    customer: { email: 'ada@lovelace.com' },
  },
  'idempotency-key-unico'
);

PHP

composer require kirvex/sdk

use Kirvex\Sdk\Kirvex;

$ap = new Kirvex('sk_test_...');

$charge = $ap->charges->create([
    'amount' => ['amount' => '9990', 'currency' => 'BRL'],
    'method' => 'pix',
    'customer' => ['email' => 'ada@lovelace.com'],
], 'idempotency-key-unico');

Python

pip install kirvex

Síncrono

from kirvex import Kirvex

ap = Kirvex("sk_test_...")

charge = ap.charges.create({
    "amount": {"amount": "9990", "currency": "BRL"},
    "method": "pix",
    "customer": {"email": "ada@lovelace.com"},
}, "idempotency-key-unico")

Assíncrono

from kirvex import AsyncKirvex

async with AsyncKirvex("sk_test_...") as ap:
    charge = await ap.charges.create({
        "amount": {"amount": "9990", "currency": "BRL"},
        "method": "pix",
    }, "idempotency-key-unico")

Recursos disponíveis em todas as SDKs

Todos os recursos da API são acessíveis via as SDKs:

• charges — criar, listar, capturar, estornar, reembolsar
• customers — CRUD de clientes
• payouts — saques via Pix
• refunds — listar reembolsos
• events — replay de eventos
• balance — saldo da conta
• webhookEndpoints — gerenciar endpoints de webhook

Tratamento de erros

Todas as SDKs levantam exceções tipadas com campos padronizados:

Campo	Tipo	Descrição
httpStatus	int	Status HTTP da resposta
errorCode	string	Código do erro (insufficient_funds, card_declined, etc.)
errorType	string	Tipo de erro (api_error, invalid_request_error)
requestId	string	ID da requisição (envie ao suporte)
retryable	boolean	Se a requisição pode ser reenviada

Contribuição

Os SDKs são open-source. Contribuições são bem-vindas!

• TypeScript SDK (GitHub)
• PHP SDK (GitHub)
• Python SDK (GitHub)