SDK TypeScript (@hiboupay/api-client)

Cliente TypeScript de conveniência para lojas que integram a HibouPay Checkout direto por API: métodos tipados (createSession / getSessionStatus / cancelSession) e verificação de assinatura de webhook (HMAC-SHA256).

Somente no backend. Este pacote assume execução em um servidor confiável (Node.js). A X-Api-Key e o segredo de webhook nunca devem ser expostos no browser.

O contrato HTTP (OpenAPI) é a referência agnóstica de linguagem; este SDK é conveniência sobre o mesmo contrato. Integração sem SDK: HTTP / OpenAPI.

Instalação

Publicado no GitHub Packages da organização hiboupay. Configure o registry no .npmrc do seu projeto:

@hiboupay:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

npm install @hiboupay/api-client

GITHUB_TOKEN precisa de permissão de leitura de pacotes no org hiboupay (token pessoal ou credencial de CI).

Cliente HTTP

import { HibouPayClient, HibouPayApiError } from '@hiboupay/api-client';

const client = new HibouPayClient({
  baseUrl: 'https://sandbox.api.hiboupay.com.br', // produção: https://api.hiboupay.com.br
  apiKey: process.env.HIBOUPAY_API_KEY!,
});

try {
  const session = await client.createSession({
    merchantId: process.env.HIBOUPAY_MERCHANT_ID!,
    platform: 'api',
    platformPaymentId: 'order-42',
    platformCallbackUrl: 'https://minha-loja.com/webhooks/hiboupay',
    returnUrl: 'https://minha-loja.com/checkout/retorno',
    order: {
      orderId: 'order-42',
      amountCents: 10_000,
      currency: 'BRL',
      items: [{ sku: 'SKU-1', description: 'Produto 1', quantity: 1, unitAmountCents: 10_000 }],
      buyer: {
        document: '12345678901',
        name: 'Fulano de Tal',
        email: 'fulano@example.com',
        phone: '11999998888',
      },
    },
  });

  console.log(session.checkoutUrl);
} catch (err) {
  if (err instanceof HibouPayApiError) {
    // err.status, err.error (código curto), err.message
    console.error(`HibouPay API error ${err.status}: ${err.error}`);
  }
  throw err;
}

const status = await client.getSessionStatus(session.sessionId);
console.log(status.state, status.outcome);

await client.cancelSession(session.sessionId, { reason: 'comprador desistiu' });

Uma Idempotency-Key é exigida pela API em mutações. Se você não passar { idempotencyKey }, o cliente gera um UUID v4 automaticamente. Para retries seguros da mesma operação lógica, prefira fornecer a sua própria chave estável.

Erros tipados

Qualquer resposta não-2xx lança HibouPayApiError:

class HibouPayApiError extends Error {
  status: number; // status HTTP
  error: string; // código curto (ex.: "idempotency_conflict")
  message: string; // descrição legível (fallback = error)
}

Verificação de webhook

A HibouPay assina os webhooks com HMAC-SHA256 sobre "{t}.{rawBody}" (bytes exatos do corpo). Use constructEvent com o corpo cru:

import express from 'express';
import { constructEvent, WebhookSignatureError } from '@hiboupay/api-client';

const app = express();

app.post(
  '/webhooks/hiboupay',
  express.raw({ type: 'application/json' }), // NÃO use express.json() nesta rota
  (req, res) => {
    try {
      const event = constructEvent(
        req.body,
        req.headers,
        process.env.HIBOUPAY_WEBHOOK_SECRET!,
      );

      // dedupe por X-HibouPay-Delivery-Id antes de agir

      switch (event.event) {
        case 'payment.approved':
          // somente depois que o pagamento foi liquidado
          break;
        case 'payment.denied':
        case 'session.cancelled':
        case 'session.expired':
          break;
      }

      res.status(200).end();
    } catch (err) {
      if (err instanceof WebhookSignatureError) {
        res.status(400).send('invalid signature');
        return;
      }
      throw err;
    }
  },
);

Alternativa: verifyWebhookSignature(rawBody, signatureHeader, secret, opts?) retorna boolean. Guia completo: Webhooks.

Exports principais

Tipos re-exportados incluem CreateSessionRequest, CreateSessionResponse, SessionStatusResponse, CancelSessionRequest, WebhookEvent, ApiError, Order, OrderItem, Buyer, Address.

CPF (Buyer.document) e plataforma

Buyer.document (CPF) é opcional na tipagem quando platform: 'shopify' (a Shopify pode entregar o CPF depois, no fluxo do checkout). Para qualquer outra plataforma — incluindo platform: 'api' — o CPF continua obrigatório na criação da sessão (validado no servidor).

Próximos passos

• Quickstart — fluxo mínimo ponta a ponta
• Erros e limites
• Referência Redoc