Bills and payments through a partner

Pay boletos, utility bills and DARF through a partner interface, and know when each payment settled.

Pay boletos, utility bills and DARF from a Midaz account when BTG pays them for your institution.

The partner’s documentation prevails over this page. Your institution validates the flow and implements it on the Lerian APIs. See how to read the diagrams.

​

Participants

---

• Your institution. Calls the Payments BTG API and receives its webhooks.
• Payments BTG. Reserves the amount in Midaz and pays the bill at BTG.
• Midaz. The ledger that holds the accounts of your customers.
• BTG. The partner that pays the bill.

​

Before you start

---

• The paying account exists in Midaz and has a holder.
• Payments BTG is connected to BTG for your institution.
• Configure your webhook with POST /v1/admin/webhooks. Send an HTTPS callbackUrl, a secret of at least 32 characters, and the events that you want in enabledEvents. Send an Idempotency-Key.

​

Diagram

---

​

Pay a boleto or a utility bill

#	From	To	Message	Lerian API	What happens
1	Your institution	Payments BTG	Lerian API	POST /v1/payments/consult	Optional. Read the bill by its digitableLine before you pay it.
2	Payments BTG	BTG	BTG API		Payments BTG reads the bill at BTG.
3	Payments BTG	Your institution	Lerian API	Response to step 1	Payments BTG answers with the data of the bill.
4	Your institution	Payments BTG	Lerian API	POST /v1/payments	Send the digitableLine, the paying account in midazAccountId and its ledgerId. Send the X-Organization-Id header and a new Idempotency-Key.
5	Payments BTG	Midaz	Internal call		Payments BTG checks that the account belongs to the organization and the ledger. It reads the holder of the account as the payer.
6	Payments BTG	BTG	BTG API		Payments BTG reads the bill and its amount at BTG.
7	Payments BTG	Midaz	Internal call		Payments BTG reserves the amount with a pending transaction. It debits the paying account and credits the external account.
8	Payments BTG	BTG	BTG API		Payments BTG pays the bill at BTG.
9	Payments BTG	Your institution	Lerian API	Response to step 4	Payments BTG answers 201 with the payment id and its status. When the answer of BTG is not known, it answers 202 with the payment in UNCONFIRMED.

​

Pay a DARF

#	From	To	Message	Lerian API	What happens
1	Your institution	Payments BTG	Lerian API	POST /v1/payments/darf	Send the treasuryRevenueCode, the referenceDate, the type, the mainAmount, the interestAmount and the fineAmount. Send the paying account in midazAccountId and its ledgerId. Send the X-Organization-Id header and a new Idempotency-Key.
2	Payments BTG	Midaz	Internal call		Payments BTG checks the account and reads its holder as the payer.
3	Payments BTG	Payments BTG	Internal step		Payments BTG adds the main amount, the interest and the fine. The sum is the amount to pay.
4	Payments BTG	Midaz	Internal call		Payments BTG reserves the amount with a pending transaction. It debits the paying account and credits the external account.
5	Payments BTG	BTG	BTG API		Payments BTG pays the DARF at BTG.
6	Payments BTG	Your institution	Lerian API	Response to step 1	Payments BTG answers 201 with the payment id and its status. When the answer of BTG is not known, it answers 202 with the payment in UNCONFIRMED.

​

Know when a payment settled

#	From	To	Message	Lerian API	What happens
1	BTG	Payments BTG	Webhook		BTG sends the result of the payment to Payments BTG.
2	Payments BTG	Midaz	Internal call		For a settled payment, Payments BTG commits the pending transaction. For a rejected, canceled or failed payment, it cancels the pending transaction and releases the amount.
3	Payments BTG	Your institution	Webhook	Webhook PAYMENT_SETTLED	Payments BTG sends PAYMENT_SETTLED to your callbackUrl. For a rejected, canceled or failed payment, it sends PAYMENT_REJECTED, PAYMENT_CANCELED or PAYMENT_FAILED.
4	Your institution	Payments BTG	Lerian API	GET /v1/payments/{id}	Read the payment with its id.
5	Payments BTG	Your institution	Lerian API	Response to step 4	After step 3, the payment shows the same result: SETTLED, REJECTED, CANCELED or FAILED.

​

Rules

---

​

Pay a boleto, a utility bill or a DARF

• Payments BTG reserves the amount in Midaz before it pays. When the reservation fails, BTG does not receive the payment.
• Send an Idempotency-Key with each payment request. The key is a UUID.
• A new key starts a new payment. Read the payment before you send a new key for the same bill.

​

Know when a payment settled

• The webhook of step 3 can arrive before step 2 ends.
• Payments BTG sends only the events that you list in enabledEvents.

​

How you know it finished

---

• GET /v1/payments/{id} shows the result: SETTLED, REJECTED, CANCELED or FAILED.
• At your callbackUrl, the webhooks PAYMENT_SETTLED, PAYMENT_REJECTED, PAYMENT_CANCELED and PAYMENT_FAILED show the same results.

​

What can go wrong

---

Situation	What you see	What to do
The answer of BTG to the payment is not known.	202, with the payment in UNCONFIRMED.	Read the payment with GET /v1/payments/{id}. If you send the request again, use the same Idempotency-Key.
The answer to a payment request does not arrive.	No answer, or a timeout.	Send the same request again with the same Idempotency-Key.
An earlier request with the same key still runs.	409, code PBP-0007.	Wait. Then send the request again with the same key.
You send a key again with other fields.	422, code PBP-0013.	Send the first request again with its key. For a new payment, use a new key.
BTG refuses the payment.	422, code PBP-0014.	Nothing was paid. Check the bill before you try again.
BTG did not receive the payment.	503, code PBP-0211.	Nothing was paid. Send the payment again with a new Idempotency-Key.

The Payments BTG error list describes each code.

​

Related

---

• Boletos & Bill Payment
• Reserve an amount, then confirm or cancel (API)
• Pix through a partner