HibouPay Docs API
← Documentação da API

Quickstart

Primeiro sucesso em ~5 minutos: criar sessão → consultar status → (opcional) cancelar. Contrato completo (schemas e status codes): referência Redoc.

Antes de começar

1. Criar sessão — POST /v1/sessions

(a) Com o SDK @hiboupay/api-client

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

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

try {
  const session = await client.createSession({
    merchantId: process.env.HIBOUPAY_MERCHANT_ID!, // UUID fornecido pela HibouPay
    platform: 'api',
    platformPaymentId: 'order-42', // idempotência lógica junto com merchantId
    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',
      },
    },
  });

  // Redirecione o comprador para checkoutUrl (link de uso único, expira em ~10 min)
  console.log(session.sessionId, session.checkoutUrl, session.expiresAt);
} catch (err) {
  if (err instanceof HibouPayApiError) {
    console.error(`HibouPay API error ${err.status}: ${err.error}`);
  }
  throw err;
}

O SDK gera um Idempotency-Key (UUID v4) automaticamente se você não passar um em { idempotencyKey }. Para retries seguros da mesma operação lógica, prefira fornecer a sua própria chave estável.

Guia completo do cliente: SDK.

(b) curl puro

curl -X POST https://sandbox.api.hiboupay.com.br/v1/sessions \
  -H "X-Api-Key: $HIBOUPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "'"$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": 10000,
      "currency": "BRL",
      "items": [
        { "sku": "SKU-1", "description": "Produto 1", "quantity": 1, "unitAmountCents": 10000 }
      ],
      "buyer": {
        "document": "12345678901",
        "name": "Fulano de Tal",
        "email": "fulano@example.com",
        "phone": "11999998888"
      }
    }
  }'

Resposta (201):

{
  "sessionId": "22222222-2222-4222-8222-222222222222",
  "checkoutUrl": "https://checkout.hiboupay.com.br/s/<token-uso-unico>",
  "expiresAt": "2026-07-14T17:10:00.000Z"
}

buyer exige document, name, email e phone na criação (exceto integrações Shopify, em que o CPF pode ser opcional na tipagem — ver SDK). Demais campos (address, civilStatus, birthDate, nationality) são opcionais nesse ponto e podem ser completados depois no checkout. order.items exige ao menos 1 item; amountCents e unitAmountCents são inteiros em centavos (nunca float de reais).

Erros possíveis: 400, 401, 409, 422, 429. Ver Erros e limites.

2. Consultar status — GET /v1/sessions/{sessionId}

(a) SDK

const status = await client.getSessionStatus(session.sessionId);
console.log(status.state, status.outcome); // outcome: PENDING | APPROVED | DENIED | CANCELLED | EXPIRED

(b) curl

curl https://sandbox.api.hiboupay.com.br/v1/sessions/22222222-2222-4222-8222-222222222222 \
  -H "X-Api-Key: $HIBOUPAY_API_KEY"

Resposta (200):

{
  "sessionId": "22222222-2222-4222-8222-222222222222",
  "state": "AWAITING_APPROVAL",
  "outcome": "PENDING"
}

state é o status da sessão; outcome é o resumo agregado sem dados pessoais (PENDING | APPROVED | DENIED | CANCELLED | EXPIRED). Erros: 401, 404.

3. Cancelar — POST /v1/sessions/{sessionId}/cancel

Só se aplica se a sessão ainda não estiver terminal; nunca desfaz um pagamento que já foi liquidado. Idempotente: se a sessão já estiver terminal, devolve o estado atual em vez de erro.

(a) SDK

const cancelled = await client.cancelSession(session.sessionId, { reason: 'comprador desistiu' });
console.log(cancelled.outcome); // CANCELLED (ou o outcome terminal que já existia)

(b) curl

curl -X POST https://sandbox.api.hiboupay.com.br/v1/sessions/22222222-2222-4222-8222-222222222222/cancel \
  -H "X-Api-Key: $HIBOUPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "comprador desistiu" }'

O corpo é opcional (reason, string, até 280 caracteres). Erros: 401, 404, 409 (status atual não permite cancelamento).

Próximos passos