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

# TED through a partner

> Send, receive and return TED through a partner interface.

Send, receive and return TED when a partner connects your institution to STR.

> [!NOTE]
>
> This page suggests one way to read the BACEN manuals for TED. 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).

## TED through JD

***

### Participants

* **Your institution.** Calls the TED JD API and reads the result of each TED.
* **TED JD.** The connectivity interface between Midaz and JD. It posts each TED in Midaz and exchanges the TED messages with JD.
* **Midaz.** The ledger that holds the accounts of your customers.
* **STR.** The BACEN reserve transfer system. It settles each TED.
* **JD.** The partner that exchanges the TED messages with STR.
* **Other institution.** The institution at the other end of a TED that your institution receives or that comes back.

### Before you start

* TED JD is set up for your institution. See [Configuration](https://docs.lerian.studio/en/interfaces/ted-jd/ted-configuration.md).
* The account that sends, receives or returns the TED exists in Midaz and has a holder.
* Where webhook delivery is on for your deployment, register your endpoint with [`POST /v1/webhooks`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/create-webhook). [`GET /v1/webhooks/event-types`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-webhook-event-types) lists the events you can subscribe to.
* To return a received TED, each operation route of the TED credit in Midaz has the `operationType` `bidirectional`. See [Accounting Routes](https://docs.lerian.studio/en/products/midaz/transaction-routing-entities.md).

### Send a TED through JD

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

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | TED JD | Lerian API | [`POST /v1/transfers/initiate`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/initiate-transfer) | Send the paying account in `senderAccountId`, the `recipient`, the `purpose` and the `amount`. Send the `X-Organization-Id` and `X-Idempotency` headers. |
| 2 | TED JD | Midaz | Internal call | | TED JD reads the paying account and its holder in Midaz. |
| 3 | TED JD | Your institution | Lerian API | Response to step 1 | TED JD answers `200` with the `initiationId`, the `feeAmount`, the `totalAmount` and the `expiresAt`. Nothing moved yet. |
| 4 | Your institution | TED JD | Lerian API | [`POST /v1/transfers/process`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/process-transfer) | Send the `initiationId` before `expiresAt`. Send the `X-Organization-Id` and `X-Idempotency` headers. |
| 5 | TED JD | Midaz | Internal call | | TED JD reserves the `totalAmount` on the paying account with a pending transaction. The `amount` goes to the external account. |
| 6 | TED JD | JD | JD API | | TED JD sends the TED to JD. |
| 7 | TED JD | Your institution | Lerian API | Response to step 4 | TED JD answers `200` with the TED in `PROCESSING`. Keep its `transferId`. |
| 8 | JD | STR | Between other parties | | JD sends the TED to STR. |
| 9 | STR | JD | Between other parties | | STR settles or rejects the TED. |
| 10 | TED JD | JD | JD API | | TED JD reads the result from JD. |
| 11 | TED JD | Midaz | Internal call | | For a settled TED, TED JD commits the pending transaction. For a rejected TED, it cancels the pending transaction and releases the amount. |
| 12 | TED JD | Your institution | Webhook | Webhook `transfer.completed` or `transfer.rejected` | The TED is `COMPLETED`, or `REJECTED` for a rejected TED. |
| 13 | Your institution | TED JD | Lerian API | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) | Read the TED with the `transferId` from step 7. |
| 14 | TED JD | Your institution | Lerian API | Response to step 13 | TED JD answers with the TED and its status. |

### Receive a TED through JD

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

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Other institution | STR | Between other parties | | The paying institution sends a TED to one of your accounts. |
| 2 | STR | JD | Between other parties | | STR settles the TED and sends it to JD. |
| 3 | TED JD | JD | JD API | | TED JD reads the new messages from JD. |
| 4 | JD | TED JD | Response | | JD answers with the received TED. |
| 5 | TED JD | Midaz | Internal call | | TED JD finds the receiving account in Midaz by the branch, account number, account type and document of the recipient. |
| 6 | TED JD | Midaz | Internal call | | TED JD credits the receiving account in one transaction. The transaction debits the external account. |
| 7 | TED JD | Your institution | Webhook | Webhook `transfer_incoming.completed` | The received TED is `COMPLETED`. The event carries its `transferId`. |
| 8 | Your institution | TED JD | Lerian API | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) | Read the received TED. Without the event, find it with [`GET /v1/transfers`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-transfers). |
| 9 | TED JD | Your institution | Lerian API | Response to step 8 | The received TED is `COMPLETED`. |

### A sent TED comes back through JD

![TED through a partner: A sent TED comes back through JD](https://mintcdn.com/lerian-49cb71fc/gH8_JGGz342YFLyy/images/en/d2/id-partner-ted-3.svg?fit=max\&auto=format\&n=gH8_JGGz342YFLyy\&q=85\&s=675ff0ee8eb0d70ca6a06f65e4579ec8)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Other institution | STR | Between other parties | | The institution that received your TED returns it. |
| 2 | STR | JD | Between other parties | | STR settles the return and sends it to JD. |
| 3 | TED JD | JD | JD API | | TED JD reads the new messages from JD. |
| 4 | JD | TED JD | Response | | JD answers with the return of your TED. |
| 5 | TED JD | Your institution | Webhook | Webhook `transfer_outgoing.devolution_notified` | The event names the TED you sent, the return code in `codDevTransf` and the `amount`. |
| 6 | TED JD | Midaz | Internal call | | TED JD credits the paying account with the returned amount. The transaction debits the external account. |
| 7 | TED JD | Your institution | Webhook | Webhook `transfer_incoming.completed` | The credit is `COMPLETED`. |
| 8 | Your institution | TED JD | Lerian API | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) | Read the TED you sent. |
| 9 | TED JD | Your institution | Lerian API | Response to step 8 | The TED you sent stays `COMPLETED` and shows the return code in `devolutionCode`. |

### Return a received TED through JD

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

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | TED JD | Lerian API | [`POST /v1/transfers/{transferId}/return`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/return-transfer) | Send the `transferId` of the received TED in the path. Send the `X-Organization-Id` and `X-Idempotency` headers. When an application calls, also send `externalReference` in the body. |
| 2 | TED JD | Midaz | Internal call | | TED JD reads the credit of the received TED and its operation routes in Midaz. It checks that the credit can be reversed. |
| 3 | TED JD | Midaz | Internal call | | TED JD reserves the credited amount with a pending transaction. It debits the account that received the TED and credits the external account. |
| 4 | TED JD | Your institution | Webhook | Webhook `transfer_incoming.return_requested` | TED JD started the return. |
| 5 | TED JD | JD | JD API | | TED JD sends the return of the full amount to JD, with the return code `70`. |
| 6 | TED JD | Your institution | Lerian API | Response to step 1 | TED JD answers `201` with the return in `PROCESSING`. Keep its `transferId`. |
| 7 | JD | STR | Between other parties | | JD sends the return to STR. |
| 8 | STR | JD | Between other parties | | STR settles or rejects the return. |
| 9 | TED JD | JD | JD API | | TED JD reads the result from JD. |
| 10 | TED JD | Midaz | Internal call | | For a settled return, TED JD cancels the pending transaction. Then it reverses the credit of the received TED in a new transaction. For a rejected return, it only cancels the pending transaction. |
| 11 | TED JD | Your institution | Webhook | Webhook `transfer_incoming.returned` or `transfer_incoming.return_rejected` | The return is `COMPLETED`, or `REJECTED` for a rejected return. |
| 12 | Your institution | TED JD | Lerian API | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) | Read the return with the `transferId` from step 6. |
| 13 | TED JD | Your institution | Lerian API | Response to step 12 | TED JD answers with the return and its status. |

### Rules for JD

#### Send a TED

* TED JD sends one TED per initiation. When you confirm the same `initiationId` again, TED JD does not send a second TED.
* The reservation in Midaz is not the settlement.

#### Receive a TED

* When JD delivers the same TED again, TED JD does not credit it again.

#### A sent TED comes back

* The credit is a new received transfer with its own `transferId`. Its `originalTransferId` names the TED you sent.
* Where your institution's configuration turns it on, a return of the whole amount can also give back the fee of the TED you sent.
* A return that reaches a TED you sent before it completed is not refunded on its own. The webhook `transfer_outgoing.devolution_notified` carries a `transferStatus` other than `COMPLETED`. If the TED completes, an operator refunds the payer with the `REFUND` action of [`POST /v1/transfers/{transferId}/reconciliation/resolve`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/resolve-transfer-reconciliation).

#### Return a received TED

* The return sends back the full amount of the received TED.
* The return is a new transfer of `type` `TED_OUT` with its own `transferId`. The received TED stays `COMPLETED`.

### How you know it finished with JD

* **Send a TED.** The webhook `transfer.completed` or `transfer.rejected` reports the final status. After a reconciliation, the webhook `transfer.reconciliation_resolved` or `transfer.reconciliation_failed` reports it, and the TED can also end `FAILED`. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) shows the status.
* **Receive a TED.** The webhook `transfer_incoming.completed` reports the credit. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) shows the received TED in `COMPLETED`.
* **A sent TED comes back.** The webhook `transfer_outgoing.devolution_notified` reports the return, and `transfer_incoming.completed` reports the credit. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) shows the TED you sent with a `devolutionCode`.
* **Return a received TED.** The webhook `transfer_incoming.returned` or `transfer_incoming.return_rejected` reports the final status. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer) with the `transferId` of the return shows `COMPLETED` or `REJECTED`.

### What can go wrong with JD

#### Send a TED

| Situation | What you see | What to do |
| - | - | - |
| The TED operating window is closed. | `422`, code `BTF-0010`. | Nothing moved. Send the TED when the window is open. |
| The initiation expired. | Step 4 answers `410`, code `BTF-0202`. | Nothing moved. Start a new TED. |
| The paying account does not have the balance. | Step 4 answers `422`, code `BTF-2003`. | Nothing moved. Add funds, and start a new TED. |
| JD refuses the TED. | Step 4 answers `422`, code `BTF-1001`, with the JD code in `upstream.code`. | TED JD released the reserved amount. The TED is `REJECTED`. Check the recipient data, and start a new TED. |
| JD does not answer. | Step 4 answers `503`, code `BTF-1000` or `BTF-1003`, with the `transferId`. | Do not send a new TED. TED JD keeps the reservation and asks JD for the result. Read the TED later. |
| JD did not receive the TED, or reports an error for it. | The webhook `transfer.reconciliation_resolved` or `transfer.reconciliation_failed`. The TED is `FAILED`, with `reconciliationStatus` `RESOLVED`. | TED JD released the reserved amount. Start a new TED. |
| The answer to step 4 does not arrive. | No answer, or a timeout. | Send step 4 again with the same `initiationId` and the same `X-Idempotency` key. |
| TED JD cannot learn the result from JD. | The TED shows `reconciliationStatus` `MANUAL_REVIEW`, and the amount stays reserved. The TED is `PROCESSING`, or `FAILED` when TED JD ran out of tries. The webhook `transfer.reconciliation_exhausted` reports the `FAILED` case and some `PROCESSING` cases. | Confirm the result with JD. When JD answers settled, resolve the TED with [`POST /v1/transfers/{transferId}/reconciliation/resolve`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/resolve-transfer-reconciliation) and `SETTLE`, which completes the TED. When JD answers refused, resolve it with `REVERT`, which releases the reserved amount. When JD answers pending or not found, send a `PROCESSING` TED back to reconciliation with [`POST /v1/transfers/{transferId}/reconciliation/retry`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/retry-transfer-reconciliation) instead. TED JD asks JD again, and the reservation stays. |
| You want to stop a TED that TED JD did not send yet. | The TED is `CREATED` or `PENDING`. | Cancel it with [`POST /v1/transfers/{transferId}/cancel`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/cancel-transfer). TED JD cancels the TED and releases any reserved amount. |

#### Receive a TED

| Situation | What you see | What to do |
| - | - | - |
| TED JD cannot credit the received TED. | The webhook `transfer_incoming.undeliverable`. | TED JD returns the TED to the paying institution, or keeps it for your review. Find it with [`GET /v1/transfers/ted-in/undeliverables`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-undeliverable-ted-in-credits). |

#### Return a received TED

| Situation | What you see | What to do |
| - | - | - |
| The TED cannot be returned. | `422`, code `BTF-0118`. | Nothing was created. Check the `transferId`. |
| The received TED already has a return. | `409`, code `BTF-0119`. The `transferId` names that return. | Read that return. |
| The TED operating window is closed. | `422`, code `BTF-0010`. | Nothing was created. Ask again when the window is open. |
| Midaz cannot reverse the credit of the received TED. | `422`, code `BTF-0120`. The `reason` says why. | Nothing was reserved or sent. `route_not_reversible` means that the routing of the TED credit in Midaz does not allow a reversal. |
| Midaz refuses the reservation. | `422`, code `BTF-0121`, with the `reason` `insufficient_balance` or `prior_reservation_pending`. | Nothing was sent. With `insufficient_balance`, ask again when the account has the credited amount. With `prior_reservation_pending`, ask again later. Use a new `X-Idempotency` key. |
| TED JD cannot complete the request. | `503`, code `BTF-2000`. When the return exists, the `transferId` names it. | Nothing was sent. TED JD closes that return and releases any reserved amount. Then ask again with a new `X-Idempotency` key. |
| JD refuses the return. | `422`, code `BTF-1001`, with the JD code in `upstream.code`. | TED JD releases the reserved amount, and the return ends `REJECTED`. |
| TED JD is not sure that JD received the return. | Step 6 carries `reconciliationStatus` `AWAITING`. | TED JD asks JD for the result. Read the return later. |
| TED JD parks the return for a manual decision. | The webhook `transfer_incoming.return_manual_review`. | Read the return. Its `reconciliationReasonCode` says why. Then resolve the return with [`POST /v1/transfers/{transferId}/reconciliation/resolve`](https://docs.lerian.studio/en/reference/interfaces/ted-jd/resolve-transfer-reconciliation). |
| The answer to step 1 does not arrive. | No answer, or a timeout. | Send the same call again with the same `X-Idempotency` key. |

## Related

***

* [Send and receive TED](https://docs.lerian.studio/en/diagrams/native-rails/send-and-receive-ted.md): the same journeys on the native Lerian SPB.
* [Cancel or return a TED](https://docs.lerian.studio/en/diagrams/native-rails/cancel-or-return-a-ted.md): the return on the native Lerian SPB.
* [Send (TED OUT)](https://docs.lerian.studio/en/interfaces/ted-jd/ted-out.md)
* [Receive (TED IN)](https://docs.lerian.studio/en/interfaces/ted-jd/ted-in.md)
* [Webhooks](https://docs.lerian.studio/en/interfaces/ted-jd/ted-webhooks.md)
* [Developer guide](https://docs.lerian.studio/en/interfaces/ted-jd/ted-developer-guide.md)


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