Boleto está disponível apenas em contas de split. Numa loja fora desse arranjo,
POST /v1/charges com payment_method: "boleto" responde 422 com boleto_not_available.
Fale com o suporte para saber em qual arranjo a sua conta está.As três diferenças que importam
A janela é de dias, não de segundos
A cobrança nascepending e só o webhook a resolve — igual ao Pix nisso. A diferença é o tempo: a
conciliação bancária é em lote, e a confirmação chega até 3 dias úteis depois do pagamento.
Não desenhe tela de espera para boleto. Um spinner aguardando conciliação fica girando por dias.
Entregue a linha digitável e deixe o comprador ir embora — quem avisa depois é o charge.paid.
O vencimento não mata o boleto
boleto.due_at é vencimento, não expiração. O banco aceita boleto depois dessa data, com juros
e multa se o seu contrato tiver.
Isso tem uma consequência prática: não trate due_at como fim. Se você cancelar o pedido no
vencimento, vai encerrar uma venda que ainda pode ser paga — e o pagamento chega depois, num pedido
que você já desfez. Nós não varremos boleto vencido para expired por esse exato motivo; quem o
encerra é o banco ou o provedor.
Não devolvemos o documento, devolvemos os endereços
Como no QR do Pix:line é o campo que diz se o boleto existe. Quando ele vem null, o provedor recusou a emissão
e a cobrança nasce failed — não há o que o comprador pague, e pending descreveria uma espera que
não vai acontecer.
O que você pode escolher na emissão
Os dois campos deboleto no corpo são opcionais. Sem eles, valem o prazo e a frase padrão da
plataforma.
O mínimo de 1 dia existe porque boleto que vence no mesmo dia nasce vencido: o banco não o processa
na data de emissão.
O que não está no seu controle, e é decisão nossa com a adquirente: espécie do documento, banco
emissor e
nosso_numero.
Boleto não parcela
card.installments não se aplica, e mandar o objeto card numa cobrança de boleto é recusado com
422 — pela mesma razão de mandá-lo num Pix: aceitar e ignorar faria você acreditar que cobrou de
outro jeito.
A taxa é por documento pago
Diferente do Pix e do cartão, que cobram percentual sobre a venda, a taxa de boleto é um valor fixo por boleto pago. Emitir não custa nada, e boleto que vence sem pagamento não cobra taxa nenhuma. Isso muda o cálculo de quem emite muito e converte pouco: o custo acompanha a conversão, não o volume de emissão. Ver Taxas e liquidação. Boleto tem piso próprio de venda, maior que o do Pix — uma taxa fixa sobre ticket pequeno não deixaria nada para o vendedor. Abaixo dele a cobrança é recusada comamount_below_minimum.
Veja também
Checkout boleto
O fluxo completo, do pedido à liberação do produto.
Ciclo de vida
Os estados por que uma cobrança passa.
Ficou algo de fora? Chame no WhatsApp. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o
X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.