HibouPay Docs API
API docs by Redocly

HibouPay Checkout — API Pública (1.0.0-draft)

Download OpenAPI specification:

API pública de Checkout consignado da HibouPay.

Crie uma sessão, redirecione o comprador para a checkoutUrl e receba notificações (webhook) quando o pagamento for aprovado, negado, cancelado ou expirado.

Como integrar: qualquer linguagem via HTTP contra este contrato OpenAPI; o SDK TypeScript (@hiboupay/api-client) é conveniência sobre o mesmo contrato.

Autenticação por X-Api-Key. Credenciais e segredo de webhook: painel HibouPay ou onboarding comercial.

Sessions

Criação e ciclo de vida da sessão de checkout.

Cria uma sessão de checkout

Cria a sessão e devolve a checkoutUrl (link de uso único) para redirecionar o comprador. Idempotente por (merchantId, platformPaymentId) via Idempotency-Key.

Authorizations:
ApiKeyAuth
header Parameters
Idempotency-Key
required
string non-empty

Idempotência de mutações. Chave lógica do create = (merchantId, platformPaymentId).

X-Signature
string

Assinatura HMAC do corpo da requisição (opcional; uso interno/reservado).

X-Timestamp
string

Timestamp para anti-replay do HMAC (par de X-Signature).

Request Body schema: application/json
required
merchantId
required
string <uuid>
platform
required
string
Enum: "vtex" "magento" "nuvemshop" "woocommerce" "api" "shopify"

Plataforma de origem. Lojas de integração direta (sem plataforma de e-commerce) usam api. shopify é usado pela app de pagamento offsite (ver Buyer.document para a regra do CPF).

platformPaymentId
required
string non-empty

Idempotência lógica com merchantId.

platformCallbackUrl
required
string <uri>

Onde a HibouPay notifica a loja (webhook de saída).

returnUrl
required
string <uri>

Para onde devolver o comprador ao fim do checkout.

required
object (Order)

Responses

Request samples

Content type
application/json
{
  • "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
  • "platform": "vtex",
  • "platformPaymentId": "string",
  • "platformCallbackUrl": "http://example.com",
  • "returnUrl": "http://example.com",
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "checkoutUrl": "http://example.com",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Status resumido da sessão

Consulta de status para a loja (status da sessão + outcome agregado; sem dados pessoais).

Authorizations:
ApiKeyAuth
path Parameters
sessionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "state": "string",
  • "outcome": "PENDING"
}

Cancela a sessão

Cancela a sessão se ela ainda não estiver terminal; nunca desfaz um pagamento que já foi liquidado. Idempotente: sessão já terminal retorna o status atual.

Authorizations:
ApiKeyAuth
path Parameters
sessionId
required
string <uuid>
header Parameters
Idempotency-Key
required
string non-empty

Idempotência de mutações. Chave lógica do create = (merchantId, platformPaymentId).

Request Body schema: application/json
optional
reason
string <= 280 characters

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "state": "string",
  • "outcome": "PENDING"
}

Health

Liveness.

Liveness

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Notificação HibouPay → loja (webhook de saída) Webhook

A HibouPay entrega ao callbackUrl configurado por merchant. At-least-once (retry + dedupe por X-HibouPay-Delivery-Id); a loja deve ser idempotente. Assinatura HMAC-SHA256 (X-HibouPay-Signature, payload {t}.{rawBody}) para verificação de autenticidade. payment.approved dispara somente depois que o pagamento foi liquidado.

Authorizations:
ApiKeyAuth
header Parameters
X-HibouPay-Delivery-Id
required
string

Id único da entrega (dedupe idempotente na loja).

X-HibouPay-Signature
required
string

Assinatura HMAC-SHA256 do corpo (t=<unix>,v1=<hex> sobre {t}.{rawBody}).

X-HibouPay-Timestamp
required
string

Timestamp para anti-replay.

Request Body schema: application/json
required
event
required
string
Enum: "payment.approved" "payment.denied" "session.cancelled" "session.expired"
sessionId
required
string <uuid>
platformPaymentId
required
string non-empty
outcome
required
string
Enum: "APPROVED" "DENIED" "CANCELLED" "EXPIRED"
authorizationId
string

Ref do desembolso, presente quando payment.approved.

reason
string
occurredAt
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "event": "payment.approved",
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "platformPaymentId": "string",
  • "outcome": "APPROVED",
  • "authorizationId": "string",
  • "reason": "string",
  • "occurredAt": "2019-08-24T14:15:22Z"
}