SDK TypeScript / Node.js

SDK oficial do Hubpay para TypeScript e Node.js. Funciona em Node.js 18+, Edge Runtime e Deno.

Instalação

bash

pnpm add @hubpay/sdk
# ou
npm install @hubpay/sdk
# ou
yarn add @hubpay/sdk

Configuração

typescript

import { Hubpay } from '@hubpay/sdk';

const hubpay = new Hubpay({
  apiKey: process.env.HUBPAY_API_KEY!, // hpx_test_... ou hpx_live_...
  baseUrl: 'https://api.hubpay.dev',   // opcional — default já configurado
});

Criar cobrança

typescript

const charge = await hubpay.charges.create({
  amount: 5000,          // R$ 50,00 em centavos
  provider: 'asaas',     // 'asaas' | 'mercadopago'
  description: 'Pedido #1234',
  payer: {
    name: 'João Silva',
    document: '12345678901',
    email: 'joao@exemplo.com',
  },
  metadata: { order_id: '1234' },
});

console.log(charge.id);              // 'chg_...'
console.log(charge.pix.copy_paste);  // '000201265800...'
console.log(charge.status);          // 'pending'

Buscar cobrança

typescript

const charge = await hubpay.charges.get('chg_abc123');
console.log(charge.status); // 'pending' | 'paid' | 'expired' | 'cancelled'

Cancelar cobrança

typescript

const charge = await hubpay.charges.cancel('chg_abc123');
console.log(charge.status); // 'cancelled'

Tratar erros

typescript

import { Hubpay, HubpayApiError } from '@hubpay/sdk';

try {
  const charge = await hubpay.charges.create({ ... });
} catch (err) {
  if (err instanceof HubpayApiError) {
    console.error(err.status);        // 400, 401, 403, etc.
    console.error(err.error.type);    // 'invalid_request', 'unauthorized', etc.
    console.error(err.error.message); // Descrição legível
  }
}

Verificar webhook

typescript

// Next.js App Router
export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get('x-hubpay-signature') ?? '';

  const verifier = hubpay.webhooks(process.env.HUBPAY_WEBHOOK_SECRET!);

  if (!verifier.verify(body, signature)) {
    return new Response('Invalid signature', { status: 401 });
  }

  const event = JSON.parse(body);

  if (event.type === 'charge.paid') {
    const { id, amount, metadata } = event.data;
    await fulfillOrder(metadata.order_id, { chargeId: id, amount });
  }

  return new Response('ok');
}

Idempotência

typescript

const charge = await hubpay.charges.create(
  { amount: 5000, provider: 'asaas' },
  { idempotencyKey: crypto.randomUUID() }, // evita cobranças duplicadas
);

Smart Routing

Distribua cobranças automaticamente entre todos os seus PSPs conectados usando round-robin com fallback automático. Requer pelo menos 2 PSPs ativos no mesmo ambiente.

typescript

// Criar cobrança com distribuição automática
const charge = await hubpay.charges.create({
  amount: 5000,
  provider: 'random',
  description: 'Pedido #1234',
});

// O campo provider mostra o PSP que efetivamente processou
console.log(charge.provider);  // 'asaas' | 'mercadopago' | 'efi' | 'pagarme'

// O campo routing só aparece quando provider: 'random' foi usado
console.log(charge.routing);
// {
//   mode: 'round_robin',
//   selected_provider: 'mercadopago',
//   attempted_providers: ['mercadopago']
// }

O campo attempted_providers mostra quais PSPs foram tentados na ordem. Se tiver mais de um item, houve fallback automático — o primeiro falhou e o Hubpay tentou o próximo.

typescript

import { Hubpay, type ChargeRouting } from '@hubpay/sdk';

// Verificar se houve fallback
const charge = await hubpay.charges.create({ amount: 3000, provider: 'random' });

if (charge.routing && charge.routing.attempted_providers.length > 1) {
  console.log('Houve fallback automático!');
  console.log('Tentou:', charge.routing.attempted_providers.join(' → '));
  console.log('Funcionou em:', charge.routing.selected_provider);
}

// Quando usa provider específico, routing não aparece
const specific = await hubpay.charges.create({ amount: 3000, provider: 'asaas' });
console.log(specific.routing); // undefined