> ## 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.

# Pix through a partner

> Send, receive and return Pix through a partner interface, with one section per partner.

Send, receive and return Pix when a partner connects your institution to SPI.

> [!NOTE]
>
> This page suggests one way to read the BACEN manuals for Pix. The partner's documentation and the manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](https://docs.lerian.studio/en/diagrams/introduction.md).

## Pix through JD

***

### Participants

* **Your institution.** Calls the Pix JD API and reads the result of each payment.
* **Pix JD.** Posts each Pix in Midaz and exchanges the orders with JD.
* **Midaz.** The ledger that holds the accounts of your customers.
* **SPI.** The BACEN instant payment system. It settles each Pix.
* **JD.** The partner that exchanges the Pix messages with SPI.

### Before you start

* Pix JD is set up for your institution. See [Setting up the rail](https://docs.lerian.studio/en/interfaces/pix-jd/pix-jd-setup.md).
* The account that sends, receives or returns the Pix exists in Midaz and has a holder.

### Send a Pix through JD

![Pix through a partner: Send a Pix through JD](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-pix-1.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=0ae67eb271bc539e45be385069f2804a)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Pix JD | Lerian API | [`GET /v1/entries/{entryId}/lookup`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/look-up-a-pix-key-before-paying-it) | Optional. Look up the Pix key before you pay it. To pay a QR code, decode it with [`POST /v1/qrcodes/decode`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/decode-qr-code) instead. |
| 2 | Pix JD | JD | JD API | | Pix JD reads the key in DICT through JD. |
| 3 | Pix JD | Your institution | Lerian API | Response to step 1 | Pix JD answers with the payee and an end-to-end ID. |
| 4 | Your institution | Pix JD | Lerian API | [`POST /v1/transactions`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-transaction) | Send the paying account in `accountId`, the `amount` in centavos and the `payee`. Send the `X-Idempotency` header. After a lookup, also send its `endToEndId` and `payee.key`. After a decode, also send its `qrCodeType`, `endToEndId` and `payee.key`, and the `txId` of a dynamic QR code. |
| 5 | Pix JD | Midaz | Internal call | | Pix JD reserves the amount with a pending transaction. It debits the paying account and credits the external account. |
| 6 | Pix JD | JD | JD API | | Pix JD sends the payment order to JD. |
| 7 | Pix JD | Your institution | Lerian API | Response to step 4 | Pix JD answers `201` with the payment in `PENDING`. Keep its `id`. |
| 8 | JD | SPI | Between other parties | | JD sends the payment order to SPI. |
| 9 | SPI | JD | Between other parties | | SPI settles or rejects the payment. |
| 10 | Pix JD | JD | JD API | | Pix JD reads the status of the order from JD to learn the final result. |
| 11 | Pix JD | Midaz | Internal call | | For a settled payment, Pix JD commits the pending transaction. For a rejected payment, it cancels the pending transaction and releases the amount. |
| 12 | Your institution | Pix JD | Lerian API | [`GET /v1/transactions/{transactionId}`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-transaction-status) | Read the payment with the `id` from step 7. |
| 13 | Pix JD | Your institution | Lerian API | Response to step 12 | The payment is `EXECUTED` when SPI settled it, and `ERROR` when it was rejected. |

### Receive a Pix through JD

![Pix through a partner: Receive a Pix through JD](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-pix-2.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=bfa51e8d52cd010c97ee21d35135610f)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | SPI | JD | Between other parties | | A Pix to one of your accounts settles at SPI. |
| 2 | JD | Pix JD | Webhook | | JD notifies Pix JD of the settled Pix. |
| 3 | Pix JD | Midaz | Internal call | | Pix JD credits the receiving account. The transaction debits the external account. |
| 4 | Pix JD | JD | Response | | Pix JD confirms to JD that the credit is booked. |
| 5 | Your institution | Pix JD | Lerian API | [`GET /v1/transactions`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-transactions) | Find the received Pix by `end_to_end_id` or by `account_id`. |
| 6 | Pix JD | Your institution | Lerian API | Response to step 5 | The received Pix is `EXECUTED`. |

### Return a received Pix through JD

![Pix through a partner: Return a received Pix through JD](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-pix-3.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=44a0d43bdb466d97b482d0dbbd1a7c33)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Pix JD | Lerian API | [`POST /v1/refunds`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-refund) | Send the `transactionId` and the `endToEndId` of the received Pix, the `accountId`, the return `code` and the `amount`. Send the `X-Idempotency` header. |
| 2 | Pix JD | Midaz | Internal call | | Pix JD reserves the amount with a pending transaction. It debits the account that received the Pix and credits the external account. |
| 3 | Pix JD | JD | JD API | | Pix JD sends the return to JD. |
| 4 | Pix JD | Your institution | Lerian API | Response to step 1 | Pix JD answers `201` with the return in `PENDING`. Keep its `id`. |
| 5 | JD | SPI | Between other parties | | JD sends the return to SPI. |
| 6 | SPI | JD | Between other parties | | SPI settles or rejects the return. |
| 7 | Pix JD | JD | JD API | | Pix JD reads the status of the return from JD to learn the final result. |
| 8 | Pix JD | Midaz | Internal call | | For a settled return, Pix JD commits the pending transaction. For a rejected return, it cancels the pending transaction and releases the amount. |
| 9 | Your institution | Pix JD | Lerian API | [`GET /v1/transactions/{transactionId}`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-transaction-status) | Read the return with the `id` from step 4. |
| 10 | Pix JD | Your institution | Lerian API | Response to step 9 | The return is `EXECUTED` when SPI settled it, and `ERROR` when it was rejected. |

### Rules for JD

#### Send a Pix

* The `X-Idempotency` header is required. A new key is a new payment.
* When the payee has an account at your institution, the payment does not go to SPI, and step 7 can answer `EXECUTED`.
* The reservation in Midaz is not the settlement. The payment is final only when it is `EXECUTED` or `ERROR`.

#### Receive a Pix

* When JD sends the same notice again, Pix JD does not credit the Pix again.

#### Return a received Pix

* The holder of `accountId` must be the payee of the Pix.
* The return `code` is `BE08`, `FR01`, `MD06` or `SL02`.
* You can return parts of a Pix more than once. Together, the returns cannot pass the amount of the Pix.
* A return is a new transaction with its own `id`. The received Pix stays `EXECUTED`.

### How you know it finished with JD

* **Send a Pix.** [`GET /v1/transactions/{transactionId}`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-transaction-status) shows `EXECUTED` or `ERROR`.
* **Receive a Pix.** [`GET /v1/transactions`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-transactions) shows the received Pix in `EXECUTED`.
* **Return a received Pix.** [`GET /v1/transactions/{transactionId}`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-transaction-status) with the `id` of the return shows `EXECUTED` or `ERROR`.

Where event delivery is on for your deployment, Pix JD also publishes the result as an event: `transaction.executed`, `transaction.refunded` or `transaction.failed`. See [Pix Direct via JD events](https://docs.lerian.studio/en/reference/events/pix-direct-jd.md).

### What can go wrong with JD

| Situation | What you see | What to do |
| - | - | - |
| The paying account does not have the balance. | `409`, code `PIX-0076`. | Before you send a new payment, read the payments with [`GET /v1/transactions`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-transactions). An earlier payment can hold the amount. If none does, add funds or pay a smaller amount. |
| The answer to a payment or a return does not arrive. | No answer, or a timeout. | Send the same call again with the same `X-Idempotency` key. A `409` with `PIX-0029` means that Pix JD recorded it. Find it with [`GET /v1/transactions`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-transactions). |
| You send again a payment that JD refused. | `409`, code `PIX-0133`. | Nothing moved. Send a new payment with a new `X-Idempotency` key. |
| JD refuses the payment after step 5. | The answer carries the refusal. | Read the payment. `ERROR` means that Pix JD released the reserved amount. |
| The payment stays `PENDING`. | Step 13 answers `PENDING`. | The result is not final. Read the payment again later. Do not send a new payment for the same purchase. |
| The balance of the receiving account does not accept credits. | The received Pix is `PENDING`, with `pendingReason` `BALANCE_NOT_RECEIVING`. | When the balance accepts credits, credit the Pix with [`POST /v1/parked-credits/{transactionId}/credit`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/credit-a-parked-received-pix). Or return it to the payer with [`POST /v1/parked-credits/{transactionId}/return`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/return-a-parked-received-pix-to-its-payer). |
| Your Tracer refuses the credit of a received Pix, by a rule, a limit or a review. | The received Pix is `PENDING`, with `pendingReason` `TRACER_DENIED`. | When your Tracer lets the credit through, credit the Pix with [`POST /v1/parked-credits/{transactionId}/credit`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/credit-a-parked-received-pix). Or return it to the payer with [`POST /v1/parked-credits/{transactionId}/return`](https://docs.lerian.studio/en/reference/interfaces/pix-jd/return-a-parked-received-pix-to-its-payer). |
| The return is more than the amount left to return. | `409`, code `PIX-0075`. | Nothing moved. Return a smaller amount. |

The [Pix JD error list](https://docs.lerian.studio/en/reference/interfaces/pix-jd/pix-jd-error-list.md) describes each code.

## Pix through BTG

***

### Participants

* **Your institution.** Calls the Pix BTG API and receives its webhooks.
* **Pix BTG.** Posts each Pix in Midaz and sends the payments to BTG.
* **Midaz.** The ledger that holds the accounts of your customers.
* **SPI.** The BACEN instant payment system. It settles each Pix.
* **BTG.** The partner that exchanges the Pix messages with SPI.

### Before you start

* The account that sends, receives or returns the Pix exists in Midaz, is active, and has a holder.
* Lerian sets your endpoint for the transfer and refund webhooks of Pix BTG. See [Webhooks](https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-webhooks.md).

### Send a Pix through BTG

![Pix through a partner: Send a Pix through BTG](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-pix-4.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=a9f7de0e102937106965225b3c939979)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Pix BTG | Lerian API | [`POST /v1/transfers/cashout/initiate`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/initiate-a-pix-transfer) | Send the source account in `X-Account-Id` and the `initiationType`. Add the `key`, the QR code in `emv`, or the account details in `destination`. |
| 2 | Pix BTG | Midaz | Internal call | | Pix BTG reads the source account and its holder. |
| 3 | Pix BTG | BTG | BTG API | | For a Pix key or a QR code, Pix BTG finds the destination account. It asks BTG when necessary. |
| 4 | Pix BTG | Your institution | Lerian API | Response to step 1 | Pix BTG answers `201` with the initiation `id`, the `destination` and `expiresAt`. |
| 5 | Your institution | Pix BTG | Lerian API | [`POST /v1/transfers/cashout/process`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/process-a-pix-transfer) | Send the initiation `id` as `initiationId` and the `amount`. Send the same `X-Account-Id`. |
| 6 | Pix BTG | Midaz | Internal call | | Pix BTG debits the source account at once. The transaction credits the external account. For an intra-PSP Pix, one transaction moves the money from the payer to the payee, and steps 7 and 9 to 12 do not happen. |
| 7 | Pix BTG | BTG | BTG API | | Pix BTG sends the payment to BTG. |
| 8 | Pix BTG | Your institution | Lerian API | Response to step 5 | Pix BTG answers `201` with the transfer in `PROCESSING`. When BTG does not take the payment at once, the transfer is `PENDING`. When the outcome of the debit in Midaz is unknown, the transfer is `CREATED`. |
| 9 | BTG | SPI | Between other parties | | BTG sends the payment order to SPI. |
| 10 | SPI | BTG | Between other parties | | SPI settles or rejects the payment. |
| 11 | BTG | Pix BTG | Webhook | | BTG sends the final result of the payment to Pix BTG. |
| 12 | Pix BTG | Midaz | Internal call | | Only for a rejected payment: Pix BTG reverts the debit with a new reverse transaction. |
| 13 | Pix BTG | Your institution | Webhook | Webhook `transfer.cashout` | The transfer is `COMPLETED`, or `REJECTED` for a rejected payment. |

### Receive a Pix through BTG

![Pix through a partner: Receive a Pix through BTG](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-pix-5.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=d4d377ddec6b35f3941bb6ffe9e5fc40)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | SPI | BTG | Between other parties | | A Pix to one of your accounts arrives. |
| 2 | BTG | Pix BTG | Webhook | | BTG asks Pix BTG to accept the Pix. |
| 3 | Pix BTG | Midaz | Internal call | | Pix BTG finds the destination account and checks that it can receive the amount. |
| 4 | Pix BTG | BTG | Response | | Pix BTG accepts the Pix, or refuses it. |
| 5 | BTG | SPI | Between other parties | | BTG sends the acceptance or the refusal to SPI. |
| 6 | SPI | BTG | Between other parties | | SPI confirms the settlement. |
| 7 | BTG | Pix BTG | Webhook | | BTG sends the settlement to Pix BTG. |
| 8 | Pix BTG | Midaz | Internal call | | Pix BTG credits the destination account with an inflow transaction. |
| 9 | Pix BTG | Your institution | Webhook | Webhook `transfer.cashin` | The received transfer is `COMPLETED`. |

### Return a received Pix through BTG

![Pix through a partner: Return a received Pix through BTG](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-pix-6.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=aba0927b61aa722bce1ec0890ca3b250)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Pix BTG | Lerian API | [`POST /v1/transfers/{transfer_id}/refunds`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/refund-a-received-pix-transfer) | Send the `id` of the received transfer in the path and the `amount`. Send the account in `X-Account-Id` and the return code in `X-Reason`. Send the `X-Idempotency` header. |
| 2 | Pix BTG | Midaz | Internal call | | Pix BTG debits the account at once. The transaction credits the external account. For an intra-PSP return, one transaction moves the money to the original payer, and steps 3 and 5 to 8 do not happen. |
| 3 | Pix BTG | BTG | BTG API | | Pix BTG sends the return to BTG. |
| 4 | Pix BTG | Your institution | Lerian API | Response to step 1 | Pix BTG answers `201` with the return in `PROCESSING`. When the answer of BTG is not known, the return is `PENDING`. When the outcome of the debit in Midaz is unknown, the return is `CREATED`. |
| 5 | BTG | SPI | Between other parties | | BTG sends the return to SPI. |
| 6 | SPI | BTG | Between other parties | | SPI settles or rejects the return. |
| 7 | BTG | Pix BTG | Webhook | | BTG sends the final result of the return to Pix BTG. |
| 8 | Pix BTG | Midaz | Internal call | | Only for a rejected return: Pix BTG reverts the debit with a new reverse transaction. |
| 9 | Pix BTG | Your institution | Webhook | Webhook `refund.cashout` | The return is `COMPLETED`, or `REJECTED` for a rejected return. |

### Rules for BTG

#### Send a Pix

* Send the `X-Idempotency` header at steps 1 and 5.
* The initiation stays open for 5 minutes. After that, step 5 answers `422` with `PIX-0411`.
* When you process the same initiation again, Pix BTG returns the transfer that it created. It moves no money again.
* The debit in Midaz is not the settlement.
* When the receiver returns a Pix that you sent, Pix BTG credits the amount in Midaz. Then it sends the webhook `refund.cashin`.

#### Receive a Pix

* Pix BTG refuses a Pix when it does not find the account, or when the account cannot receive the amount. Midaz records nothing for a refused Pix.

#### Return a received Pix

* You can return only a received Pix. Together, the returns cannot pass the amount of the Pix.
* The return code in `X-Reason` is `BE08`, `FR01`, `MD06` or `SL02`.
* The debit of step 2 is not the settlement.

### How you know it finished with BTG

* **Send a Pix.** The webhook `transfer.cashout` gives the final status. [`GET /v1/transfers/{transfer_id}`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-a-pix-transfer) shows the same status.
* **Receive a Pix.** Pix BTG sends the webhook `transfer.cashin` with `COMPLETED`.
* **Return a received Pix.** The webhook `refund.cashout` gives the final status. [`GET /v1/refunds/{refund_id}`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-a-refund) shows the same status.

### What can go wrong with BTG

| Situation | What you see | What to do |
| - | - | - |
| The initiation is older than 5 minutes. | `422`, code `PIX-0411`. | Nothing moved. Start a new initiation. |
| The answer to step 1 or step 5 does not arrive. | No answer, or a timeout. | Send the same call again with the same `X-Idempotency` key. |
| The answer to a return does not arrive. | No answer, or a timeout. | Read the returns of the Pix with [`GET /v1/refunds`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-refunds) filtered by `end_to_end`. Send the return again only when it is not there. |
| The webhook of step 13 does not arrive. | The transfer stays `PENDING` or `PROCESSING`. | Read the transfer. To ask BTG for its status, use [`POST /v1/transfers/{transfer_id}/unblock`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/unblock-a-pix-transfer). Do not send a new payment for the same purchase. |
| The transfer or the return stays `CREATED`. | The status is `CREATED`. | For an inter-PSP Pix, unblock refuses it with `422`. Open a support request with Lerian and give the transfer or return id. |
| The webhook of step 9 of a return does not arrive. | The return stays `PENDING` or `PROCESSING`. | Read the return. To ask BTG for its status, use [`POST /v1/refunds/{refund_id}/unblock`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/unblock-a-pix-refund). |
| Your endpoint did not accept a webhook. | The webhook is `FAILED` or `DEAD_LETTER` in [`GET /v1/webhooks/outbound`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-outbound-webhooks). | Send it again with [`POST /v1/webhooks/outbound/{id}/retry`](https://docs.lerian.studio/en/reference/interfaces/pix-btg/retry-an-outbound-webhook). |

The [Pix BTG error list](https://docs.lerian.studio/en/reference/interfaces/pix-btg/indirect-pix-error-list.md) describes each code.

## Related

***

* [Send and receive Pix](https://docs.lerian.studio/en/diagrams/native-rails/send-and-receive-pix.md): the same journeys on the native Lerian SPI.
* [Return a received Pix](https://docs.lerian.studio/en/diagrams/native-rails/return-a-received-pix.md): the return on the native Lerian SPI.
* [Pix via JD](https://docs.lerian.studio/en/interfaces/pix-jd/direct-pix-via-jd.md)
* [Transfers and cash-out](https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-transfers.md)
* [Refund operations](https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-refund-operations.md)
* [Webhooks](https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.