Skip to main content
Boletos & Bill Payment covers Brazil’s boleto rail: issuing boletos bancários and paying bills such as DARF tax documents and utility/concessionaire invoices. On the Lerian platform, you operate this capability through the Payments module in Lerian Console, a managed plugin for Midaz provisioned for your organization.

​
What you can do

  • Issue boletos with due dates, recorded against your Midaz ledger. Through the API, a boleto can also carry fines, interest, and discounts, and you can choose its nosso número.
  • Pay bills (DARF tax payments and utility/concessionaire bills) directly from the Console.
  • Consult a bill by its digitable line through the API before you pay it. The answer shows the amount, the dates, and who receives the money.
  • Track operations from a dashboard with KPI cards, recent activity, and quick actions.

​
How a bill payment moves money

  1. The ledger reserves the amount in the funding account. If the balance or the overdraft limit does not allow it, the payment fails here, and BTG does not receive it.
  2. Payments sends the payment to BTG.
  3. When BTG accepts the payment, the API answers 201 and the payment is CREATED. When the outcome at BTG is unknown, the API answers 202 and the payment is UNCONFIRMED. Its funds stay reserved.
  4. For a bank slip or utility payment, the reconciliation reads the payment from BTG. If BTG has no record of it for the whole window that the deployment sets, the payment fails with PBP-0211, and Payments releases the funds.
  5. For a DARF payment, the funds stay reserved until the outcome from BTG arrives.
Do not send an UNCONFIRMED payment again under a new Idempotency-Key. BTG can already have it, and a second request can pay the bill twice. A resend under the same key is safe.

​
Find a payment after an error

A request to create a payment can end without a payment id, for example after a timeout or an answer with status 5xx. First send the request again under the same Idempotency-Key. After a 409 with PBP-0007 or a 503 with PBP-0008, wait, then send it again under the same key. After the same key returns another answer, call GET /v1/payments with idempotencyKey set to that key to find what the request created. Send the same X-Organization-Id as that request. After you send a request again under a new Idempotency-Key, do not send it under the old key again. The old key can run the request again, and the two requests can both pay.

​
Where to start

Payments in Lerian Console

Activate the Payments plugin and take a first tour of the module.

Payments Overview

The dashboard: KPI cards, recent operations, and shortcuts.

Boletos

Issue, consult, and manage boletos.

Bill Payments

Pay DARF and utility bills from the Console.