@hubpay/sdk

SDK TypeScript oficial do Hubpay — API unificada para cobranças Pix.

Instalação

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

Quick start

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

const hubpay = new Hubpay({
  apiKey: process.env.HUBPAY_API_KEY!, // hpx_test_... ou hpx_live_...
});

// Criar cobrança
const charge = await hubpay.charges.create({
  amount: 5000, // R$ 50,00 em centavos
  provider: 'asaas',
  description: 'Pedido #1234',
  payer: { name: 'João Silva', document: '12345678901' },
});

console.log(charge.pix.copy_paste); // Pix copia e cola
console.log(charge.status);         // 'pending'

// Buscar cobrança
const updated = await hubpay.charges.get(charge.id);

// Cancelar cobrança
const cancelled = await hubpay.charges.cancel(charge.id);

Smart Routing (provider "random")

Distribua cobranças automaticamente entre todos os seus PSPs conectados usando round-robin com fallback automático.

Como funciona

Em vez de escolher um PSP específico, envie provider: "random" e o Hubpay distribui sequencialmente:

• Requisição 1 → Asaas
• Requisição 2 → Mercado Pago
• Requisição 3 → Efí
• Requisição 4 → Asaas (recomeça)

Se o PSP da vez estiver fora do ar, o Hubpay tenta automaticamente o próximo. Seus clientes nunca veem erro de pagamento.

Exemplo

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

const hubpay = new Hubpay({ apiKey: 'hpx_live_...' });

const charge = await hubpay.charges.create({
  amount: 5000,
  provider: 'random',
  description: 'Pedido #1234',
  payer: {
    name: 'João da Silva',
    document: '12345678900',
    email: '[email protected]',
  },
});

console.log(charge.provider);
// => "mercadopago" (o PSP que efetivamente processou)

console.log(charge.routing);
// => {
//   mode: "round_robin",
//   selected_provider: "mercadopago",
//   attempted_providers: ["mercadopago"]
// }

Verificando fallback

Se houve fallback (PSP principal falhou), attempted_providers terá mais de um item:

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

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

Requisitos

• Pelo menos 2 PSPs ativos conectados no dashboard do Hubpay no mesmo ambiente (test ou live).
• Com apenas 1 PSP, use o nome do provider diretamente ("asaas", "mercadopago", etc.).

Combinando com provider específico

// Cobranças normais: distribui automaticamente
const charge1 = await hubpay.charges.create({
  amount: 5000,
  provider: 'random',
});

// Caso especial: forçar Asaas pra um cliente específico
const charge2 = await hubpay.charges.create({
  amount: 10000,
  provider: 'asaas',
});

Nota sobre o campo provider na resposta

Quando você usa "random", o campo provider na resposta mostra o PSP que efetivamente processou a cobrança (ex: "mercadopago"), não "random". O campo routing contém os detalhes do roteamento.

Quando você usa um provider específico, o campo routing não aparece na resposta.

Verificar webhook

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

  const verifier = hubpay.webhooks(process.env.HUBPAY_WEBHOOK_SECRET!);
  if (!verifier.verify(body, sig)) {
    return new Response('Invalid signature', { status: 401 });
  }

  const event = JSON.parse(body);
  if (event.type === 'charge.paid') {
    // processar pagamento...
  }

  return new Response('ok');
}

Tratamento de erros

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

try {
  await hubpay.charges.create({ amount: 5000, provider: 'asaas' });
} catch (err) {
  if (err instanceof HubpayApiError) {
    console.error(err.status);        // 400, 401, 403, 502...
    console.error(err.error.type);    // 'invalid_request', 'unauthorized'...
    console.error(err.error.message); // descrição legível
  }
}

Documentação completa

hubpay.dev/docs

License

MIT