Pular para o conteúdo principal
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 requires_action 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: Endereços fora do Brasil são aceitos, mantendo a exigência de CPF ou CNPJ: bastam país, rua e cidade. O boleto impresso mostra rua, número, bairro e cidade do pagador; o estado aparece só para endereços nos Estados Unidos, e o código postal de fora do Brasil não aparece. Campos ausentes ou inválidos impedem a emissão.
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.

Emitir o primeiro boleto de uma fatura pela API

Use POST /v1/invoices/{id}/issue_boleto. A chamada emite o boleto de uma fatura aberta, avulsa ou de assinatura, e retorna PDF e linha digitável em next_action.boleto_display_details do Payment Intent. Não é necessário abrir a página hospedada. Complete antes os dados do customer.

Emitir boletos em volume

Para emitir os boletos de muitas faturas, como as 1.800 mensalidades que um ERP gera numa tarde, faça uma chamada por fatura e mande várias ao mesmo tempo, em vez de esperar uma terminar para começar a próxima. A emissão leva cerca de 5 segundos: uma por vez, 1.800 boletos levam mais de 3 horas. Cada boleto de fatura avulsa gasta duas criações, a fatura (POST /v1/invoices) e a emissão (issue_boleto), e a chave de organização aceita 120 criações por minuto: o teto é de 60 boletos por minuto. Com 7 emissões ao mesmo tempo, a integração chega a esse teto e os mesmos 1.800 boletos saem em cerca de 30 minutos, com folga na cota de 40 chamadas a cada 10 segundos. Mais emissões simultâneas não aceleram: as que passam do limite voltam com 429.
  • Envie uma Idempotency-Key própria em cada emissão. Repetir com a mesma chave devolve o mesmo boleto, sem emitir outro.
  • Ao receber 429, espere o Retry-After e aumente a espera a cada nova recusa.
  • Leia o PDF e a linha digitável em next_action.boleto_display_details, na resposta da própria emissão. Cada consulta a mais por boleto, à fatura, ao cliente ou ao pagamento, gasta a cota de consultas e a de 10 segundos e baixa esse teto.
  • Atualize o cliente só quando algum dado mudou. Atualizar ou criar o cliente antes de cada boleto soma uma terceira criação, e o teto cai para 40 boletos por minuto.
  • Mande ao cliente o link do PDF em vez de baixar o arquivo: o seu servidor gera no máximo 10 PDFs novos por minuto. Veja Baixar o PDF.

Lifecycle

Lendo next_action.boleto_display_details

pdf retorna um arquivo com Content-Type: application/pdf. A linha digitável vem em number, sem pontuação. Abrir ou baixar o documento não emite outro boleto nem cria uma nova cobrança.

Baixar o PDF

O PDF e a página do boleto são gerados quando alguém abre o link pela primeira vez. Cada endereço IP gera até 10 documentos novos por minuto; acima disso, o link volta 429, sem corpo e sem Retry-After, e volta a abrir no minuto seguinte. Reabrir o mesmo documento não conta de novo: o PDF fica guardado por 24 horas e a página, por 5 minutos. Mande ao cliente o link de pdf ou de hosted_voucher_url em vez de baixar o arquivo no seu servidor: cada cliente abre o próprio boleto, e o limite não pesa. Se o seu sistema precisa do arquivo, para anexar ao e-mail ou arquivar, baixe no ritmo de 10 por minuto. Mandar vários downloads ao mesmo tempo não acelera: 1.800 PDFs levam 3 horas.

Vencimento

O boleto pode vencer hoje, amanhã, depois de amanhã ou em qualquer dia futuro, no calendário de Brasília. Só um dia que já passou é recusado. O dia vem de quem emite: Por exemplo, numa terça-feira, 20/10: a fatura de R$ 97,00 que vence hoje gera um boleto pagável até 20/10 às 23h59; a que vence amanhã, até 21/10; a que venceu ontem, até 23/10. O boleto pode ser pago até o fim do dia de vencimento no horário de Brasília — o instante em expires_at. Depois disso o banco recusa o pagamento e a página hospedada mostra o boleto como vencido. Um boleto que vence no dia da emissão deixa ao comprador só as horas que faltam desse dia. Um pagamento feito no último dia só é confirmado pelo banco depois da compensação. Por isso a tentativa não termina em expires_at: o intent continua em requires_action até o banco confirmar o desfecho, em geral de 2 a 3 dias úteis depois do vencimento. Se a confirmação não chegar em 10 dias, a Chargefy encerra a tentativa do mesmo jeito. Por exemplo: um boleto de R$ 97,00 vence na terça-feira, 20/10. Ele pode ser pago até 20/10 às 23h59. Se ninguém pagou, o banco confirma o vencimento entre quinta (22/10) e sexta-feira (23/10), e só então chegam os eventos abaixo. Se o comprador pagou na terça, chega payment.intent.succeeded no lugar deles. Quando o vencimento é confirmado:
  • O intent volta a requires_payment_method, next_action volta a null e payment.intent.updated é emitido; a expiração não cancela o intent.
  • charge.failed é emitido com payment_error.category: "expired" e payment_error.code: "payment_code_expired". Expiração tem categoria própria porque não é recusa: ninguém respondeu “não”, um prazo passou.
Não é preciso fazer polling para detectar o vencimento — escute o webhook.

Reemitir um boleto vencido (regenerate)

Depois que o vencimento é confirmado (o intent volta a requires_payment_method), use POST /v1/payment-intents/{id}/regenerate_boleto para emitir outro dentro do mesmo Payment Intent. Um boleto em requires_action ou processing não é reemitido — inclusive nos dias depois do vencimento em que a confirmação do banco ainda não chegou, porque um pagamento feito no último dia ainda pode ser compensado. 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.

Cancelamento

Para faturas, Cancelar boleto encerra apenas a tentativa. A fatura continua aberta, e outro boleto pode ser emitido sem aguardar a confirmação do banco. O boleto anterior recebe cancellation_requested_at; enquanto aguarda, ele ainda pode ser pago, mas a página hospedada deixa de apresentá-lo como opção. Cancelar pagamento encerra a cobrança inteira quando todos os boletos pendentes forem confirmados como cancelados ou vencidos. Anular a fatura, marcá-la como incobrável ou paga por fora também pede o cancelamento dos boletos ainda pendentes. Por exemplo, o comprador troca um boleto de R$ 120 por cartão. O pedido de cancelamento é registrado, mas o banco ainda pode aceitar aquele boleto durante a espera. Se ambos forem pagos, o segundo recebimento segue o tratamento de pagamento duplicado. Se a fatura já tiver sido anulada, o recebimento é registrado sem reabrir a fatura ou reativar a assinatura, e o valor fica com a organização, que decide se o devolve ao comprador. O cancelamento isolado de boletos de sessões de checkout não está disponível por esta ação.