Boleto Bancário

Quick Reference

WhatPagamentos via Boleto Bancário

WhyBoleto offline aceito em qualquer banco, caixa eletrônico ou app bancário no Brasil — alcança a população desbancarizada

Reading Time10 min

DifficultyBeginner

PrerequisitesAutenticação → Ambiente

O que é Boleto Bancário

O Boleto é um título de cobrança bancária regulamentado pelo Banco Central do Brasil. O comerciante gera um boleto com código de barras e data de vencimento; o cliente paga em qualquer agência bancária, caixa eletrônico, casa lotérica ou app bancário. A liquidação ocorre via CIP (Câmara Interbancária de Pagamentos) em 1 a 3 dias úteis.

Característica	Detalhe
Mercado	Brasil
Moeda	BRL
Liquidação	D+1 a D+3
Chargebacks	Nenhum — pagamento push
Validade padrão	3 dias (configurável)

Como funciona

Comerciante cria a cobrança

Seu servidor chama POST /api/v1/bank/wallet/charge/ com type_charge: "boleto".

A55 gera o boleto

A API retorna uma URL do PDF (boleto_url) e a linha digitável do código de barras (barcode).

Cliente paga

O cliente paga em uma agência bancária, caixa eletrônico, casa lotérica ou app bancário usando o código de barras.

Liquidação via CIP

O pagamento é confirmado pela CIP e a A55 envia um webhook com status: "paid".

Fluxo de pagamento

Ciclo de vida do Boleto

Status	Descrição
issued	Boleto gerado; aguardando pagamento
pending	Registrado no banco; aguardando pagamento do cliente
paid	Pagamento confirmado via CIP
canceled	Expirado ou cancelado antes do pagamento
error	Erro na geração ou processamento

Criar uma cobrança por Boleto

POST/api/v1/bank/wallet/charge/Bearer TokenCriar um pagamento via Boleto

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`type_charge`	string	Sim	Deve ser `"boleto"`
`currency`	string	Sim	`"BRL"`
`installment_value`	number	Sim	Valor em BRL (ex.: `150` para R$150)
`installment_count`	number	Sim	Sempre `1` para Boleto
`payer_tax_id`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos)
`payer_name`	string	Sim	Nome completo do pagador
`due_date`	string	Sim	Data de vencimento no formato ISO 8601
`description`	string	Não	Descrição do pedido exibida no boleto

cURL
Python

curl -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Maria Santos",
    "payer_email": "maria.santos@example.com",
    "payer_tax_id": "12345678901",
    "payer_cell_phone": "+5511988887777",
    "installment_value": 250,
    "installment_count": 1,
    "items": [{"name":"Annual Plan","quantity":1,"total_amount":250,"unit_amount":250,"sku":"PLAN-001","code":"AP001"}],
    "payer_address": {"street":"Rua Augusta","address_number":"500","complement":"Sala 12","neighborhood":"Consolação","city":"São Paulo","state":"SP","postal_code":"01304-001","country":"BR"},
    "currency": "BRL",
    "due_date": "2026-12-31T23:59:59Z",
    "description": "Annual subscription plan",
    "type_charge": "boleto",
    "webhook_url": "https://yoursite.com/webhook",
    "redirect_url": "https://yoursite.com/confirmation"
  }'

import requests

charge = requests.post(
    "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
    headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
    json={
        "wallet_uuid": "00000000-0000-0000-0000-000000000000",
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "payer_name": "Maria Santos",
        "payer_email": "maria.santos@example.com",
        "payer_tax_id": "12345678901",
        "payer_cell_phone": "+5511988887777",
        "installment_value": 250,
        "installment_count": 1,
        "items": [{"name": "Annual Plan", "quantity": 1, "total_amount": 250, "unit_amount": 250, "sku": "PLAN-001", "code": "AP001"}],
        "payer_address": {"street": "Rua Augusta", "address_number": "500", "complement": "Sala 12", "neighborhood": "Consolação", "city": "São Paulo", "state": "SP", "postal_code": "01304-001", "country": "BR"},
        "currency": "BRL",
        "due_date": "2026-12-31T23:59:59Z",
        "description": "Annual subscription plan",
        "type_charge": "boleto",
        "webhook_url": "https://yoursite.com/webhook",
        "redirect_url": "https://yoursite.com/confirmation",
    },
)
data = charge.json()
boleto_pdf = data["boleto_url"]
barcode = data["barcode"]

Exemplo de resposta

{
  "charge_uuid": "a3b1c2d4-5678-9abc-def0-1234567890ab",
  "currency": "BRL",
  "type": "boleto",
  "status": "issued",
  "boleto_url": "https://pay.a55.tech/boleto/a3b1c2d4-5678-9abc-def0-1234567890ab.pdf",
  "barcode": "23793.38128 60000.000003 00000.000400 1 84340000025000",
  "due_date": "2026-12-31",
  "charge_payment_url": "https://pay.a55.tech/charge/a3b1c2d4-5678-9abc-def0-1234567890ab"
}

Campo	Descrição
`boleto_url`	Link direto para o PDF do boleto para download ou impressão
`barcode`	Linha digitável — o cliente pode digitá-la em qualquer app bancário
`due_date`	Data de vencimento após a qual o boleto não pode mais ser pago
`charge_payment_url`	Página de pagamento hospedada com os detalhes do boleto

Vencimento

O vencimento padrão do boleto é de 3 dias úteis. Você pode configurar isso através do campo due_date. Após o vencimento, o boleto é automaticamente cancelado e um webhook com status: "canceled" é enviado.

Tentativas com boleto vencido

Clientes ainda podem tentar pagar um boleto vencido em uma agência física. O banco rejeitará o pagamento, mas a experiência do cliente será ruim. Defina uma janela de vencimento razoável.

Prazo de liquidação

Cenário	Liquidação
Boleto padrão	D+1 a D+3 dias úteis
Boleto registrado	D+1

Como funciona a liquidação pela CIP

Quando o cliente paga o boleto, o banco emissor notifica a CIP (Câmara Interbancária de Pagamentos). A CIP processa a liquidação interbancária em ciclos de lote e notifica a A55. A A55 então dispara o webhook paid para o seu endpoint. O ciclo completo leva de 1 a 3 dias úteis, dependendo do banco e do horário do pagamento.

Erros comuns

Erro	Causa	Solução
`invalid_tax_id`	CPF/CNPJ falhou na validação	Verifique o CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador
`invalid_due_date`	`due_date` está no passado	Defina uma data futura, mínimo 1 dia útil à frente
`amount_below_minimum`	Valor abaixo do mínimo do provedor	Verifique o valor mínimo do boleto (geralmente R$5,00)
`boleto_generation_failed`	Banco rejeitou o registro	Tente novamente; se persistir, verifique os dados do pagador e entre em contato com o suporte

PIX →Pagamentos instantâneos no Brasil Cartão de crédito →Pagamentos com cartão e parcelamento Liquidação →Como os fundos chegam à sua conta

Quick Reference

O que é Boleto Bancário​

Como funciona​

Comerciante cria a cobrança

A55 gera o boleto

Cliente paga

Liquidação via CIP

Fluxo de pagamento​

Ciclo de vida do Boleto​

Criar uma cobrança por Boleto​

Corpo da requisição​

Exemplo de resposta​

Vencimento​

Prazo de liquidação​

Erros comuns​