Boleto

Boleto bancário registrado — necessário para clientes sem cartão/PIX. ~70% aprovação, liquidação D+1.

Boleto é necessário no Brasil para clientes que não têm/usam cartão ou PIX. Aprovação ~70%, liquidação em D+1.

Criar cobrança

O Customer precisa estar criado antes com document (CPF/CNPJ) e endereço — sem isso, a CIP recusa o registro do boleto.

// 1. cliente já cadastrado com document + endereço completos
const intent = await zhex.paymentIntents.create({
  amount: 4990,
  currency: 'brl',
  customer: 'cus_…',
  payment_method_types: ['boleto'],
  description: 'Pedido #4821',
});

Quando você confirma (ou o cliente entra no checkout hosted), o boleto é registrado na CIP e o intent volta em requires_action com next_action:

{
  "id": "pi_…",
  "status": "requires_action",
  "next_action": {
    "type": "boleto_display_details",
    "boleto_display_details": {
      "line_code": "34191790010104351004791020150008291260000020000",
      "pdf_url": "https://…/boleto.pdf",
      "barcode_url": "https://…/barcode.png",
      "expires_at": 1714060800
    }
  }
}

line_code — linha digitável (47 dígitos IPTE) que o cliente copia e cola no app do banco.
pdf_url — boleto em PDF (quando o adquirente fornece). Pode ser null se o adquirente expõe só código.
barcode_url — PNG do código de barras (44 dígitos), quando disponível.
expires_at — Unix timestamp do vencimento.

O endpoint de segunda via (regerar boleto após vencimento) ainda é roadmap; até lá, o cliente precisa de um intent novo se o boleto expirar.

Boleto registrado

Boleto registrado é obrigatório desde 2018. A Zhex sempre registra na CIP — você não configura nada. O documento (CPF/CNPJ) e endereço completo do Customer são mandatórios.

Lifecycle

Status	Significado
`requires_payment_method`	Recurso criado
`requires_action`	Boleto emitido, aguardando pagamento
`processing`	Cliente pagou, aguardando confirmação CIP (até 1h em horário bancário)
`succeeded`	Liquidação confirmada (D+1 do pagamento)
`canceled`	Vencimento atingido sem pagamento (expira sozinho)

Refund

await zhex.refunds.create({
  payment_intent: 'pi_3MtwBwLkdI',
  // omita amount para refund total
});

Janela: 60 dias após o pagamento.
Liquidação: D+5 via TED reverso na conta de origem.
Requer dados bancários do cliente — coletados via fluxo de suporte ou pelo painel se não estiverem no boleto original.

Hoje cada PaymentIntent aceita um único refund (total ou parcial em valor único). Múltiplos refunds parciais sequenciais são roadmap.

Boas práticas

Não combine boleto com cartão no mesmo payment_method_types quando ticket > R$ 500. Boleto sempre vence o cartão na escolha do cliente, o que reduz aprovação total.
Webhook obrigatório — boleto é assíncrono por natureza. Sem payment_intent.succeeded, você não tem como saber que liquidou.
Customer com document + endereço completos antes de criar o intent. Caso contrário, a confirmação falha no momento do registro CIP.
Email transacional com link do boleto na confirmação — clientes BR copiam linha digitável e pagam pelo app do banco; oferecer o PDF no email reduz suporte.

Esta página foi útil?

Criar cobrança

Lifecycle

Refund

Boas práticas

Nesta página