SDK TypeScript - Chargefy

O SDK oficial da Chargefy para TypeScript oferece acesso tipado a toda a API, facilitando a integração em aplicações Node.js, Next.js, e outros frameworks JavaScript.

Instalação

npm install @chargefy/sdk

pnpm add @chargefy/sdk

yarn add @chargefy/sdk

Configuração

import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN, // <supabase_jwt>...
  server: 'production', // ou 'sandbox'
});

Opção	Tipo	Obrigatório	Descrição
`accessToken`	`string`	Sim	Supabase JWT obtido via `supabase.auth.getSession()`
`server`	`'production' \| 'sandbox'`	Não	Ambiente (default: `production`)

Nunca exponha o accessToken no frontend. Use o SDK apenas em código server-side (API routes, server components, scripts).

Produtos

Listar Produtos

const { items, pagination } = await chargefy.products.list({
  page: 1,
  limit: 20,
  is_archived: false,
});

for (const product of items) {
  console.log(`${product.name} - ${product.prices.length} preço(s)`);
}

Criar Produto

const product = await chargefy.products.create({
  name: 'Plano Pro',
  description: 'Acesso completo à plataforma',
  prices: [
    {
      type: 'recurring',
      currency: 'brl',
      unit_amount: 9900, // R$ 99,00 (em centavos)
      interval: 'month',
      interval_count: 1,
    },
  ],
});

console.log(`Produto criado: ${product.id}`);

Obter Produto

const product = await chargefy.products.get('prod_123');

Atualizar Produto

const updated = await chargefy.products.update('prod_123', {
  name: 'Plano Pro Plus',
  description: 'Acesso completo com suporte prioritário',
});

Checkout

Criar Sessão de Checkout

const checkout = await chargefy.checkouts.create({
  product_price_id: 'price_123',
  customer_email: 'cliente@email.com',
  success_url: 'https://meusite.com/sucesso',
  metadata: {
    user_id: 'usr_abc',
  },
});

// Redirecionar o cliente para o checkout
console.log(`URL do checkout: ${checkout.url}`);

Confirmar Checkout — PIX

const result = await chargefy.checkouts.confirm(checkout.id, {
  payment_method: 'pix',
  buyer: {
    name: 'João Silva',
    email: 'joao@email.com',
    tax_id: '12345678901', // CPF
  },
});

// QR Code gerado automaticamente
console.log(`PIX QR Code: ${result.pix_qr_code}`);
console.log(`PIX Copia e Cola: ${result.pix_copy_paste}`);

Confirmar Checkout — Cartão de Crédito

const result = await chargefy.checkouts.confirm(checkout.id, {
  payment_method: 'credit_card',
  card: {
    holder_name: 'JOAO SILVA',
    card_number: '4111111111111111',
    expiry_month: '12',
    expiry_year: '2030',
    cvv: '123',
  },
  installments: 3, // 3x
  buyer: {
    name: 'João Silva',
    email: 'joao@email.com',
    tax_id: '12345678901',
  },
});

console.log(`Status: ${result.status}`); // 'succeeded'

Confirmar Checkout — Boleto

const result = await chargefy.checkouts.confirm(checkout.id, {
  payment_method: 'boleto',
  due_date: '2026-03-20',
  buyer: {
    name: 'João Silva',
    email: 'joao@email.com',
    tax_id: '12345678901',
  },
});

console.log(`Código de barras: ${result.boleto_barcode}`);
console.log(`Linha digitável: ${result.boleto_digitable_line}`);
console.log(`URL do boleto: ${result.boleto_url}`);

Clientes

Listar Clientes

const { items } = await chargefy.customers.list({
  page: 1,
  limit: 50,
});

Criar Cliente

const customer = await chargefy.customers.create({
  email: 'maria@email.com',
  name: 'Maria Santos',
  metadata: {
    source: 'signup',
  },
});

Buscar por Email

const { items } = await chargefy.customers.list({
  email: 'maria@email.com',
});

const customer = items[0]; // undefined se não encontrado

Assinaturas

Listar Assinaturas

const { items } = await chargefy.subscriptions.list({
  customer_id: 'cust_123',
  active: true,
});

Cancelar Assinatura

await chargefy.subscriptions.update('sub_123', {
  cancel_at_period_end: true,
});

Suspender Assinatura

await chargefy.subscriptions.update('sub_123', {
  status: 'suspended',
});

Reativar Assinatura

await chargefy.subscriptions.update('sub_123', {
  status: 'active',
});

Descontos

Criar Desconto

const discount = await chargefy.discounts.create({
  name: 'LANCAMENTO20',
  type: 'percentage',
  amount: 20, // 20% de desconto
  max_redemptions: 100,
  starts_at: '2026-03-01T00:00:00Z',
  ends_at: '2026-04-01T00:00:00Z',
});

Webhooks

Criar Endpoint de Webhook

const webhook = await chargefy.webhooks.create({
  url: 'https://meusite.com/api/webhooks/chargefy',
  events: [
    'checkout.updated',
    'subscription.active',
    'subscription.created',
    'subscription.canceled',
  ],
});

console.log(`Webhook secret: ${webhook.secret}`);

Listar Webhooks

const { items } = await chargefy.webhooks.list();

Tratamento de Erros

O SDK lança exceções tipadas para erros da API:

import { Chargefy, ChargefyError } from '@chargefy/sdk';

try {
  const product = await chargefy.products.get('prod_inexistente');
} catch (error) {
  if (error instanceof ChargefyError) {
    console.error(`Erro ${error.statusCode}: ${error.message}`);

    switch (error.statusCode) {
      case 401:
        console.error('Token inválido ou expirado');
        break;
      case 403:
        console.error('Escopo insuficiente');
        break;
      case 404:
        console.error('Recurso não encontrado');
        break;
      case 422:
        console.error('Erro de validação:', error.detail);
        break;
      case 429:
        console.error(`Rate limit. Retry após ${error.retryAfter}s`);
        break;
    }
  }
}

TypeScript Types

O SDK exporta todos os tipos para uso em sua aplicação:

import type {
  Product,
  ProductCreate,
  ProductUpdate,
  Price,
  Checkout,
  CheckoutCreate,
  CheckoutConfirm,
  Customer,
  Subscription,
  Discount,
  Webhook,
  WebhookEvent,
  PaginatedResponse,
} from '@chargefy/sdk';

// Use em seus tipos
interface MySubscriptionHandler {
  processSubscription: (subscription: Subscription) => Promise<void>;
  listProducts: () => Promise<PaginatedResponse<Product>>;
}

Exemplos Completos

Checkout End-to-End (Next.js API Route)

api/checkout/route.ts

import { Chargefy } from '@chargefy/sdk';
import { NextRequest, NextResponse } from 'next/server';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN!,
});

export async function POST(req: NextRequest) {
  const { productPriceId, email } = await req.json();

  // 1. Criar checkout
  const checkout = await chargefy.checkouts.create({
    product_price_id: productPriceId,
    customer_email: email,
    success_url: `${process.env.NEXT_PUBLIC_URL}/checkout/sucesso`,
  });

  return NextResponse.json({
    checkoutId: checkout.id,
    clientSecret: checkout.client_secret,
    url: checkout.url,
  });
}

Webhook Handler (Next.js API Route)

api/webhooks/chargefy/route.ts

import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.CHARGEFY_WEBHOOK_SECRET!;

function verifySignature(payload: string, signature: string): boolean {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get('webhook-signature') || '';

  if (!verifySignature(body, signature)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const event = JSON.parse(body);

  switch (event.type) {
    case 'checkout.updated':
      if (event.data.status === 'succeeded') {
        // Pagamento confirmado — ativar acesso
        console.log(`Checkout ${event.data.id} pago!`);
      }
      break;

    case 'subscription.canceled':
      // Assinatura cancelada — revogar acesso
      console.log(`Assinatura ${event.data.id} cancelada`);
      break;

    case 'subscription.active':
      // Assinatura ativa — liberar acesso
      console.log(`Assinatura ${event.data.id} ativa`);
      break;
  }

  return NextResponse.json({ received: true });
}

Próximos Passos

Framework Adapters

Adapters para Next.js, Express e mais

API Reference

Referência completa de todos os endpoints

Webhooks

Configurar notificações em tempo real

Sandbox

Testar no ambiente de desenvolvimento

​Instalação

​Configuração

​Produtos

​Listar Produtos

​Criar Produto

​Obter Produto

​Atualizar Produto

​Checkout

​Criar Sessão de Checkout

​Confirmar Checkout — PIX

​Confirmar Checkout — Cartão de Crédito

​Confirmar Checkout — Boleto

​Clientes

​Listar Clientes

​Criar Cliente

​Buscar por Email

​Assinaturas

​Listar Assinaturas

​Cancelar Assinatura

​Suspender Assinatura

​Reativar Assinatura

​Descontos

​Criar Desconto

​Webhooks

​Criar Endpoint de Webhook

​Listar Webhooks

​Tratamento de Erros

​TypeScript Types

​Exemplos Completos

​Checkout End-to-End (Next.js API Route)

​Webhook Handler (Next.js API Route)

​Próximos Passos

Framework Adapters

API Reference

Webhooks

Sandbox

Instalação

Configuração

Produtos

Listar Produtos

Criar Produto

Obter Produto

Atualizar Produto

Checkout

Criar Sessão de Checkout

Confirmar Checkout — PIX

Confirmar Checkout — Cartão de Crédito

Confirmar Checkout — Boleto

Clientes

Listar Clientes

Criar Cliente

Buscar por Email

Assinaturas

Listar Assinaturas

Cancelar Assinatura

Suspender Assinatura

Reativar Assinatura

Descontos

Criar Desconto

Webhooks

Criar Endpoint de Webhook

Listar Webhooks

Tratamento de Erros

TypeScript Types

Exemplos Completos

Checkout End-to-End (Next.js API Route)

Webhook Handler (Next.js API Route)

Próximos Passos