HTTP / OpenAPI

Integre a HibouPay Checkout em qualquer linguagem com HTTP puro. O contrato OpenAPI é a referência completa; este guia resume os endpoints do dia a dia com exemplos curl.

Referência navegável: Redoc.

Base URLs e autenticação

Header obrigatório (exceto /v1/health):

X-Api-Key: hp_...sua_chave...

Detalhes: Autenticação.

Endpoints

Criar sessão — POST /v1/sessions

Headers: X-Api-Key, Idempotency-Key (obrigatório), Content-Type: application/json.

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"
}

Idempotência lógica: (merchantId, platformPaymentId). Mesmo payload → mesmo resultado; payload divergente com a mesma combinação → 409.

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

curl https://sandbox.api.hiboupay.com.br/v1/sessions/$SESSION_ID \
  -H "X-Api-Key: $HIBOUPAY_API_KEY"

Resposta 200: { "sessionId", "state", "outcome" } — outcome é um de PENDING | APPROVED | DENIED | CANCELLED | EXPIRED.

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

Não desfaz pagamento já liquidado. Sessão já terminal devolve o estado atual (idempotente).

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

reason é opcional (até 280 caracteres).

Health — GET /v1/health

Público, sem API key:

curl https://sandbox.api.hiboupay.com.br/v1/health
# → { "status": "ok" }

Webhooks (entrada na sua loja)

A HibouPay faz POST no seu platformCallbackUrl com o envelope WebhookEvent, headers de assinatura HMAC e X-HibouPay-Delivery-Id para dedupe. Verificação passo a passo: Webhooks.

Status codes comuns

Detalhes: Erros e limites.

Prefer SDK TypeScript?

Se o seu backend é Node.js, o pacote @hiboupay/api-client evita boilerplate de headers, erros e HMAC — ver SDK.