Skip to main content
Boleto é um método assíncrono — o comprador recebe um documento bancário, paga em banco/app/internet banking, e o resultado da compensação chega 1 dia útil depois (no mínimo). A integração reflete isso: o payment_intent fica em pending com o documento renderizado em next_action, e o payment.intent.succeeded chega via webhook quando o banco confirma.

​
Pré-requisitos

Boleto exige endereço completo do comprador por regulamentação FEBRABAN. Ao confirmar uma checkout session com payment_method: "boleto", os seguintes campos são obrigatórios: Falhar qualquer um retorna um erro 422 por parâmetros inválidos.
POST /v1/payment-intents aceita cartão e Pix no fluxo direto. Um payment intent de boleto nasce por checkout hospedado ou invoice; não envie payment_method_types: ["boleto"] no create direto.

​
Lifecycle

​
Lendo next_action.boleto_display_details

Trate hosted_voucher_url e pdf como campos independentes, mesmo quando as duas URLs apontarem para o mesmo documento.

​
Auto-expiração

A Chargefy agenda automaticamente um job para encerrar a tentativa no momento de expires_at se o pagamento não tiver sido confirmado. O vencimento encerra o boleto, não o Payment Intent. Quando isso ocorre:
  • O intent volta a requires_payment_method e payment.intent.updated é emitido; a expiração não cancela o intent.
  • charge.failed é emitido com payment_error.message: "Boleto expired without payment".
  • O documento atual é invalidado quando possível e next_action volta a null.
Não é preciso fazer polling para detectar expiração — escute o webhook.

​
Reemitir um boleto vencido (regenerate)

Depois que um boleto vence, use POST /v1/payment-intents/{id}/regenerate_boleto para emitir outro dentro do mesmo Payment Intent. Um boleto pending ou processing ainda pode ser pago e não é reemitido. Mantém:
  • Mesmo ID de payment_intent e mesmo client_secret.
  • Mesmo vínculo com a checkout session (se aplicável).
  • Novo latest_charge, novo next_action, novo expires_at.
Limitado a 1 chamada por hora por Payment Intent (429 caso contrário). Sem limite total de reemissões.