Boleto Integration with Bradesco's Cobrança API

The boleto bancário is a uniquely Brazilian payment instrument — a bank-issued payment slip that can be paid at any bank branch, ATM, lottery house, or via internet banking. Despite the rise of PIX, boletos remain widely used, particularly for B2B transactions, utility bills, and customers who prefer or require offline payment options.

Bradesco's Cobrança API allows developers to generate, register, and manage boletos programmatically, enabling automated billing workflows at scale.

How the Boleto Ecosystem Works

In Brazil, boletos must be registered with the national clearinghouse (CIP — Câmara Interbancária de Pagamentos) before they can be paid. Bradesco handles this registration automatically through its API when you create a boleto, ensuring your charges are valid and payable across all channels.

Key concepts to understand:

  • Cedente — The beneficiary (your company) receiving the payment
  • Sacado — The payer (your customer)
  • Nosso Número — A unique identifier assigned by Bradesco to track each boleto
  • Linha Digitável — The typeable line (barcode number) the payer uses if they can't scan
  • Vencimento — The due date, after which fines and interest may apply

Prerequisites for Boleto API Integration

  1. Active Bradesco business account with an established convênio de cobrança (billing agreement)
  2. Your Código do Cedente (beneficiary code) — provided by Bradesco when you set up cobrança
  3. API credentials (Client ID, Client Secret) from the developer portal
  4. mTLS certificate for production API calls

Creating a Boleto via the API

Generating a boleto involves a POST request to Bradesco's cobrança endpoint. A typical request payload includes:

  • Valor — The charge amount in BRL
  • Vencimento — Due date in ISO 8601 format
  • Sacado — Payer's name, CPF/CNPJ, and address
  • Instruções — Optional payment instructions printed on the boleto (e.g., "Do not accept after 30 days")
  • Juros/Multa — Interest rate per day and fine percentage after due date (optional)
  • Desconto — Early payment discount configuration (optional)

On success, the API returns the boleto's nossoNumero, the linhaDigitavel, a base64-encoded PDF, and a URL to the printable boleto page.

Boleto Status Lifecycle

Understanding boleto states is critical for building reliable reconciliation workflows:

Status Meaning
Emitido Created and registered, awaiting payment
Pago Payment confirmed by the bank
Vencido Past due date, may still be payable with fines
Cancelado Cancelled before payment
Baixado Written off / removed from collection

Querying and Cancelling Boletos

Bradesco's API provides endpoints to:

  • Query a boleto by nossoNumero to check current status and payment details
  • Cancel (baixar) a boleto — useful when an order is cancelled or payment was received via another method
  • Update a boleto — modify due date, value, or discount within permitted windows
  • List boletos — retrieve a paginated list of charges within a date range

Automated Reconciliation Tips

For businesses generating high boleto volumes, automated reconciliation is essential:

  1. Use Bradesco's CNAB return files for batch payment confirmation — these are daily files containing all payments received.
  2. Supplement CNAB files with webhook notifications for near real-time payment updates.
  3. Always match payments using nossoNumero rather than value or debtor name, as amounts can differ due to fines/interest.
  4. Build idempotent reconciliation logic to handle duplicate notifications gracefully.