Pagamentos de Boletos
Objetivo
Pagar boleto bancário ou convênio com saldo da conta titular (não é Pix).
Pré-requisito: Login da conta. Scopes baas.bankslip-payments.read (consulta, revisão) e baas.bankslip-payments.write (atualizar, confirmar). Verifique saldo e limites antes de confirmar.
Fluxo sequencial
- Consultar código de barras: decodifica a linha digitável; retorna beneficiário, valores e
reference - Revisar: valida se pode pagar hoje (
canPayToday,minPaymentTime,maxPaymentTime,nextUtilDay) - Atualizar: opcional; ajusta valor (
total) em boleto de valor divergente ou definescheduled_for - Confirmar: debita a conta e liquida o título; irreversível após sucesso
Etapas 2 a 4 exigem a reference da consulta. Se a sessão expirar, reinicie pelo passo 1.
Horário típico para pagamento no mesmo dia: 07:00 às 16:00 (horário de Brasília). Fora da janela, a confirmação pode agendar para o próximo dia útil.
Contrato HTTP: Consultar por código de barras.
Linha digitável
- Envie apenas dígitos no path
{barcode}(44 a 48 posições conforme o título). - Boleto já pago, fora do prazo ou com valor zero tende a
422. - Valores na consulta e na revisão costumam vir em centavos; no Atualizar, o campo
totaldo corpo é em reais (decimal). Confira o contrato na Referência.
Endpoints
Consultar código de barras
| Método | GET |
| Path | /api/v2/baas/bankslip-payments/barcode/{barcode} |
Contrato: Consultar por código de barras.
Autenticação
Bearer da conta, HMAC. Em GET, corpo [] na assinatura.
Regras de negócio
- Primeiro passo obrigatório do fluxo.
- Resposta
202trazreferencepara as etapas seguintes. - Saldo insuficiente para boleto de valor fixo pode retornar
422já na consulta.
Exemplo fictício de linha digitável (somente dígitos na URL): 23793381286008301352856000063330894325100000015200.
Revisar
| Método | GET |
| Path | /api/v2/baas/bankslip-payments/review/{reference} |
Contrato: Revisar pagamento.
Autenticação
Bearer da conta, HMAC.
Regras de negócio
{reference}= valor retornado na consulta (ex.:{linha}_{data}_{documento_beneficiario}).- Retorna resumo do pagamento e janela horária permitida.
referenceinválida ou expirada →422.
Atualizar
| Método | POST |
| Path | /api/v2/baas/bankslip-payments/update/{reference} |
Contrato: Atualizar agendamento.
Autenticação
Bearer da conta, HMAC.
Corpo mínimo
| Campo | Regra |
|---|---|
total | Valor em reais (ex.: 152.00); obrigatório |
scheduled_for | Data dd/mm/AAAA; hoje ou futuro |
beneficiary_name | Nome do beneficiário conforme consulta |
beneficiary_document | CPF/CNPJ só dígitos; opcional conforme boleto |
observation | Opcional, até 500 caracteres |
Regras de negócio
- Use quando o boleto permite valor divergente ou para agendar pagamento.
- Saldo é validado contra o
totalinformado. - Pule esta etapa se consulta e revisão já refletem o valor e a data desejados.
Confirmar
| Método | POST |
| Path | /api/v2/baas/bankslip-payments/confirm/{reference} |
Contrato: Confirmar pagamento.
Autenticação
Bearer da conta, HMAC. Corpo vazio ou {} conforme ambiente.
Regras de negócio
- Etapa final: após sucesso o débito não é revertido pelo integrador.
- Dentro do horário permitido: status tende a
processing. - Fora do horário ou com data futura: pagamento agendado (
scheduled). - Erro de processamento →
422; revise saldo, limites ereferenceantes de reenviar.