Boleto Bancário
Quick Reference
What is Boleto Bancário
Boleto is a Brazilian payment slip (bank slip) regulated by the Central Bank of Brazil. The merchant generates a boleto with a barcode and due date; the customer pays it at any bank branch, ATM, lottery house, or banking app. Settlement happens via CIP (Câmara Interbancária de Pagamentos) in 1–3 business days.
| Feature | Detail |
|---|---|
| Market | Brazil |
| Currency | BRL |
| Settlement | D+1 to D+3 |
| Chargebacks | None — push payment |
| Default expiration | 3 days (configurable) |
How it works
Merchant creates charge
Your server calls POST /api/v1/bank/wallet/charge/ with type_charge: "boleto".
A55 generates the boleto
The API returns a PDF URL (boleto_url) and a digitable barcode line (barcode).
Customer pays
The customer pays at a bank branch, ATM, lottery house, or banking app using the barcode.
Settlement via CIP
The payment is confirmed through CIP and A55 sends a webhook with status: "paid".
Payment flow
Boleto lifecycle
| Status | Description |
|---|---|
| issued | Boleto generated; awaiting payment |
| pending | Registered at the bank; awaiting customer payment |
| paid | Payment confirmed via CIP |
| canceled | Expired or voided before payment |
| error | Generation or processing error |
Create a Boleto charge
/api/v1/bank/wallet/charge/Bearer TokenCreate a Boleto paymentRequest body
| Field | Type | Required | Description |
|---|---|---|---|
type_charge | string | Yes | Must be "boleto" |
currency | string | Yes | "BRL" |
installment_value | number | Yes | Amount in BRL (e.g. 150 for R$150) |
installment_count | number | Yes | Always 1 for Boleto |
payer_tax_id | string | Yes | CPF (11 digits) or CNPJ (14 digits) |
payer_name | string | Yes | Full payer name |
due_date | string | Yes | ISO 8601 expiration date |
description | string | No | Order description shown on the 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"]
Response example
{
"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"
}
| Field | Description |
|---|---|
boleto_url | Direct link to the boleto PDF for download or print |
barcode | Digitable line — customer can type this into any banking app |
due_date | Expiration date after which the boleto can no longer be paid |
charge_payment_url | Hosted payment page with boleto details |
Expiration
The default boleto expiration is 3 business days. You can configure this via the due_date field. After expiration, the boleto is automatically canceled and a webhook with status: "canceled" is sent.
Customers may still attempt to pay an expired boleto at a physical branch. The bank will reject the payment, but the customer experience is poor. Set a reasonable expiration window.
Settlement timing
| Scenario | Settlement |
|---|---|
| Standard boleto | D+1 to D+3 business days |
| Registered boleto (boleto registrado) | D+1 |
How CIP settlement works
When the customer pays the boleto, the issuing bank notifies CIP (Câmara Interbancária de Pagamentos). CIP processes the inter-bank settlement in batch cycles and notifies A55. A55 then triggers the paid webhook to your endpoint. The entire cycle takes 1–3 business days depending on the bank and time of payment.
Common errors
| Error | Cause | Fix |
|---|---|---|
invalid_tax_id | CPF/CNPJ failed validation | Verify the payer's CPF (11 digits) or CNPJ (14 digits) |
invalid_due_date | due_date is in the past | Set a future date, minimum 1 business day ahead |
amount_below_minimum | Amount is below the minimum R$5.00 | Boleto requires a minimum of R$5.00. Banks reject boletos below this threshold |
boleto_generation_failed | Bank rejected registration | Retry; if persistent, check payer data and contact support |