> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. > [!NOTE] > > 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](https://docs.lerian.studio/en/diagrams/introduction.md). ## 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`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/configure-webhook). 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 ![Bills and payments through a partner: Pay a boleto or a utility bill](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-bills-1.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=bd4ea6219f8ea49e01b8b671ab0c0989) | # | From | To | Message | Lerian API | What happens | | - | - | - | - | - | - | | 1 | Your institution | Payments BTG | Lerian API | [`POST /v1/payments/consult`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/consult-a-bill-by-digitable-line) | 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`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/initiate-payment) | 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 ![Bills and payments through a partner: Pay a DARF](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-bills-2.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=f1d329fc8f17f907d700f76f8ba60126) | # | From | To | Message | Lerian API | What happens | | - | - | - | - | - | - | | 1 | Your institution | Payments BTG | Lerian API | [`POST /v1/payments/darf`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/initiate-darf-payment) | 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 ![Bills and payments through a partner: Know when a payment settled](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-bills-3.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=ec10b262017640da0509c17a0b957628) | # | 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}`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-payment) | 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}`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-payment) 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}`](https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-payment). 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](https://docs.lerian.studio/en/reference/interfaces/payments-btg/payments-error-list.md) describes each code. ## Related *** * [Boletos & Bill Payment](https://docs.lerian.studio/en/interfaces/payments-btg/boleto-and-bill-payment.md) * [Reserve an amount, then confirm or cancel (API)](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-reserve-then-confirm-or-cancel.md) * [Pix through a partner](https://docs.lerian.studio/en/diagrams/partner-interfaces/pix.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.