Visão geral

A API HibouPay Checkout permite que a sua loja ofereça pagamento consignado ao comprador: você cria uma sessão, redireciona o cliente para a HibouPay e recebe uma notificação quando o pagamento for concluído.

Fluxo da sessão

1. Sua loja cria uma sessão          POST /v1/sessions
2. Você redireciona o comprador      → checkoutUrl
3. O comprador conclui o checkout    (na HibouPay)
4. A HibouPay notifica a loja        webhook (ou você consulta o status)

1. Criar a sessão

Com a API key e o merchantId da sua loja, chame POST /v1/sessions. A resposta traz:

sessionId — identificador da sessão
checkoutUrl — URL para redirecionar o comprador (link de uso único, expira em ~10 minutos)
expiresAt — quando a sessão deixa de ser válida

Use platform: 'api' se a sua loja integra direto (sem plataforma de e-commerce). Informe platformCallbackUrl (para onde enviar webhooks) e returnUrl (para onde devolver o comprador ao fim do fluxo).

2. Redirecionar o comprador

Envie o comprador para checkoutUrl. Ele completa o fluxo de crédito/consignado na HibouPay.

3. Saber o resultado

Há duas formas de acompanhar o desfecho:

Abordagem	Quando usar
Webhook (recomendado)	A HibouPay envia um evento para o seu `platformCallbackUrl` quando a sessão é aprovada, negada, cancelada ou expirada.
Consulta de status	`GET /v1/sessions/{sessionId}` — útil como fallback ou para exibir status na sua interface.

Polling frequente não substitui o webhook: use a consulta pontualmente; configure o webhook para reagir em tempo quase real sem sobrecarregar a API.

4. Cancelar (opcional)

Enquanto a sessão ainda não terminou, você pode cancelá-la com POST /v1/sessions/{sessionId}/cancel. O cancelamento não desfaz um pagamento que já foi liquidado.

Outcomes

A consulta de status e os webhooks usam um outcome resumido:

`outcome`	Significado
`PENDING`	Sessão em andamento
`APPROVED`	Pagamento aprovado (somente depois que o pagamento foi liquidado)
`DENIED`	Pagamento negado
`CANCELLED`	Sessão cancelada
`EXPIRED`	Sessão expirou

O campo state traz o status da sessão com mais detalhe; outcome é o resumo agregado (sem dados pessoais).

Próximos passos

Autenticação — obter API key e escolher a URL base
Quickstart — primeiro sucesso em poucos minutos
Webhooks — receber e verificar notificações