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 compayment_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
UsePOST /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-Keyprópria em cada emissão. Repetir com a mesma chave devolve o mesmo boleto, sem emitir outro. - Ao receber
429, espere oRetry-Aftere 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 volta429, 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_actionvolta anullepayment.intent.updatedé emitido; a expiração não cancela o intent. charge.failedé emitido compayment_error.category: "expired"epayment_error.code: "payment_code_expired". Expiração tem categoria própria porque não é recusa: ninguém respondeu “não”, um prazo passou.
Reemitir um boleto vencido (regenerate)
Depois que o vencimento é confirmado (o intent volta arequires_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_intente mesmoclient_secret. - Mesmo vínculo com a checkout session (se aplicável).
- Novo
latest_charge, novonext_action, novoexpires_at.
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 recebecancellation_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.
