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

# Send and receive TED

> Send a TED from a Midaz account or from your own core, and receive a TED into a Midaz account, through TED Lerian and Lerian SPB.

Send a TED from a customer account in Midaz or from your own core, and receive a TED for your customers.

> [!NOTE]
>
> The BACEN manuals for STR prevail 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.** Your system. It sends the TEDs, reads them and receives the events.
* **TED Lerian.** The TED interface between Midaz and Lerian SPB. It checks each TED, moves the money in Midaz and publishes the events. [Streaming Hub](https://docs.lerian.studio/en/platform/streaming-hub/what-is-streaming-hub.md) delivers the events to your system.
* **Midaz.** The ledger. It keeps the customer accounts and their balances.
* **Lerian SPB.** Lerian's STR messaging. It sends and receives the STR messages and reports their settlement.
* **STR (BACEN).** The BACEN reserve transfer system. It settles each TED between the reserve accounts.
* **Sending institution.** Another institution. It sends a TED to a customer of yours.

## Before you start

***

* Set your usage limits with [`PUT /v1/policy/limits`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/set-usage-limits).
* Load the national holiday calendar of each year with [`PUT /v1/policy/holidays`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/replace-the-holidays-of-a-year), before the year starts. A loaded year covers every date in it. On a date whose year is not loaded, TED Lerian refuses the TED.
* Optionally, set your cut-off with [`PUT /v1/policy/window`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/set-the-cut-off). It cannot be later than the official close.
* To charge a fee, create a Midaz fee package on the ledger that selects on the [TED Lerian posting labels](https://docs.lerian.studio/en/interfaces/ted-lerian/ted-lerian-business-rules.md#fees).
* To receive TEDs, bind your ISPB to the Midaz organization and ledger that receive the credits, with [`PUT /v1/policy/ispb-bindings`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/replace-ispb-bindings). The binding needs the organization in Midaz, the `@external/BRL` account on the ledger, and your institution's holder with an account in the CRM.
* Each account that receives TEDs has a holder and an instrument in Midaz, with the branch, the account number and the account type in `bankingDetails`. See [Register a holder and open an account](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-register-a-holder.md).

## Diagram

***

### Send from a Midaz account

![Send and receive TED: Send from a Midaz account](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-send-and-receive-ted-1.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=f569f3bf8ebe455809101f53fc3ef36b)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | TED Lerian | API call | [`POST /v1/transfers/fee-quotes`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/quote-a-transfer-fee) | Optional. Send the recipient, the amount and the purpose code. The header `X-Account-Id` names the source account. |
| 2 | TED Lerian | Your institution | API answer | Response to step 1 | `200` with the fee estimate in `feeAmount`, `totalAmount`, `windowOpen` and `nextWindowOpensAt`. The quote moves no money. |
| 3 | Your institution | TED Lerian | API call | [`POST /v1/transfers`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/send-a-ted) | Send the TED with `recipient`, `amount`, `purposeCode` and, optionally, `clientReference`. Send the source account in `X-Account-Id` and a key in `X-Idempotency`. |
| 4 | TED Lerian | TED Lerian | Internal step | | TED Lerian checks the purpose code, the recipient's document, the recipient's bank in the STR participant list, the window and your usage limits. |
| 5 | TED Lerian | Midaz | Internal call | [`POST /v2/transactions/hold`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-hold) | TED Lerian creates a pending transaction for the amount, labeled `ted_sent`. Midaz adds the fee that your fee packages apply and holds the amount plus the fee on the source account. The transfer is `RESERVED`. |
| 6 | TED Lerian | Lerian SPB | Internal call | [`POST /v1/str/operations/bank-transfers`](https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-operation) | TED Lerian sends the TED to Lerian SPB, with the sender and the recipient as customers. |
| 7 | TED Lerian | Your institution | API answer | Response to step 3 | `201` with the transfer in `SUBMITTED`. |
| 8 | Lerian SPB | STR (BACEN) | `STR0008` | | Lerian SPB sends the TED between two customers to the STR. |
| 9 | STR (BACEN) | Lerian SPB | `STR0008R1` | | The STR settles the TED and answers. |
| 10 | Lerian SPB | TED Lerian | Event | | Lerian SPB reports the settlement with `settlement.settled`. |
| 11 | TED Lerian | Your institution | Event | Event `transfer.settled` | The transfer is `SETTLED`. |
| 12 | TED Lerian | Midaz | Internal call | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit`](https://docs.lerian.studio/en/reference/products/midaz/v2/commit-transaction) | TED Lerian commits the pending transaction. The held amount goes to `@external/BRL`, and the fee goes to the account that your fee package credits. |

### Send from your own core

![Send and receive TED: Send from your own core](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-send-and-receive-ted-2.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=a04b581dc6e78b133e723442067fc318)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Lerian SPB | API call | [`POST /v1/str/operations/bank-transfers`](https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-operation) | Send `sender` and `recipient` with `party` set to `client`, the `amount` and the `purposeCode`. Send a key in `X-Idempotency`. |
| 2 | Lerian SPB | Your institution | API answer | Response to step 1 | `201` with the operation. Lerian SPB accepted the TED for sending. |
| 3 | Lerian SPB | STR (BACEN) | `STR0008` | | Lerian SPB sends the TED between two customers to the STR. |
| 4 | STR (BACEN) | Lerian SPB | `STR0008R1` | | The STR settles the TED and answers. |
| 5 | Lerian SPB | Your institution | Event | Event `settlement.settled` | Lerian SPB reports the final position of the operation. |
| 6 | Your institution | Your institution | Internal step | | Book the debit in your core. |

### Receive and credit

![Send and receive TED: Receive and credit](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-send-and-receive-ted-3.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=23ddffa53e3d4b8422e7edee78e680c4)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Sending institution | STR (BACEN) | `STR0008` | | Another institution sends a TED to a customer of yours. |
| 2 | STR (BACEN) | Lerian SPB | `STR0008R2` | | The STR settles the TED and reports the credit to your institution. |
| 3 | Lerian SPB | TED Lerian | Event | | Lerian SPB gives the credit to TED Lerian with `str.operation.received`. |
| 4 | TED Lerian | Your institution | Event | Event `incoming_transfer.received` | TED Lerian records the TED as `RECEIVED`. Nothing is credited yet. |
| 5 | TED Lerian | Midaz | Internal call | [`GET /v2/organizations/{organization_id}/instruments`](https://docs.lerian.studio/en/reference/products/midaz/v2/list-instruments) | TED Lerian looks for the account at the branch and the account number of the recipient. It looks in the organization that your ISPB is bound to. |
| 6 | Midaz | TED Lerian | Internal call | | Midaz returns the account, the document of its holder and its closing date, if any. |
| 7 | TED Lerian | TED Lerian | Internal step | | TED Lerian checks that the account is open, that the holder's document matches the TED and that the account type in the TED is the account's type. |
| 8 | TED Lerian | Midaz | Internal call | [`POST /v2/transactions/direct`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-direct) | TED Lerian posts one transaction, labeled `ted_received`. It debits `@external/BRL` and credits the customer's account. When your fee package deducts a fee from the credit, the customer receives the amount less the fee. |
| 9 | TED Lerian | Your institution | Event | Event `incoming_transfer.credited` | The TED is `CREDITED`, with `creditedAmount` and `feeAmount`. |

### Return when the account cannot receive

![Send and receive TED: Return when the account cannot receive](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-send-and-receive-ted-4.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=624bccf0ba5007568549bb69019fd338)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Sending institution | STR (BACEN) | `STR0008` | | Another institution sends a TED to a customer of yours. |
| 2 | STR (BACEN) | Lerian SPB | `STR0008R2` | | The STR settles the TED and reports the credit to your institution. |
| 3 | Lerian SPB | TED Lerian | Event | | Lerian SPB gives the credit to TED Lerian with `str.operation.received`. |
| 4 | TED Lerian | Your institution | Event | Event `incoming_transfer.received` | TED Lerian records the TED as `RECEIVED`. |
| 5 | TED Lerian | Midaz | Internal call | [`GET /v2/organizations/{organization_id}/instruments`](https://docs.lerian.studio/en/reference/products/midaz/v2/list-instruments) | TED Lerian looks for the account at the branch and the account number of the recipient. |
| 6 | Midaz | TED Lerian | Internal call | | Midaz finds no account there, or it returns an account that cannot receive the TED. |
| 7 | TED Lerian | TED Lerian | Internal step | | TED Lerian decides to return the TED with the official reason. |
| 8 | TED Lerian | Your institution | Event | Event `incoming_return.requested` | TED Lerian records the return before it sends it. The TED is `RETURN_REQUESTED`. |
| 9 | TED Lerian | Lerian SPB | Internal call | [`POST /v1/str/operations/bank-transfers/{operationId}/returns`](https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-return-operation) | TED Lerian tells Lerian SPB to return the TED with the reason. |
| 10 | Lerian SPB | STR (BACEN) | `STR0010` | | Lerian SPB sends the return to the STR. |
| 11 | STR (BACEN) | Lerian SPB | `STR0010R1` | | The STR settles the return and answers. |
| 12 | Lerian SPB | TED Lerian | Event | | Lerian SPB reports the settlement of the return with `settlement.settled`. |
| 13 | TED Lerian | Your institution | Event | Event `incoming_return.returned` | The TED is `RETURNED`. The money went back to the sending institution, and no balance changed in Midaz. |

### Receive into an account of your institution

![Send and receive TED: Receive into an account of your institution](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-send-and-receive-ted-5.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=6e1251c6ba0289b31701d37a88c8c802)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Sending institution | STR (BACEN) | `STR0008` | | Another institution sends a TED to an account that your institution holds. |
| 2 | STR (BACEN) | Lerian SPB | `STR0008R2` | | The STR settles the TED and reports the credit to your institution. |
| 3 | Lerian SPB | TED Lerian | Event | | Lerian SPB gives the credit to TED Lerian with `str.operation.received`. |
| 4 | TED Lerian | Your institution | Event | Event `incoming_transfer.received` | TED Lerian records the TED as `RECEIVED`. |
| 5 | TED Lerian | Midaz | Internal call | [`GET /v2/organizations/{organization_id}/instruments`](https://docs.lerian.studio/en/reference/products/midaz/v2/list-instruments) | TED Lerian looks for the account at the branch and the account number of the recipient. |
| 6 | Midaz | TED Lerian | Internal call | | Midaz returns the account. The document of its holder is the CNPJ of your Midaz organization. |
| 7 | TED Lerian | TED Lerian | Internal step | | TED Lerian records the TED and credits nothing in Midaz. |
| 8 | TED Lerian | Your institution | Event | Event `incoming_transfer.recorded` | The TED is `RECORDED`, with `kind` set to `INSTITUTION`. |

## Rules

***

* Accepted is not settled. A `201` with `SUBMITTED` means that Lerian SPB accepted the TED for sending. The held money leaves the source account only after the STR settles the TED.
* Usage limits count the amount plus the fee. A rejected or cancelled TED frees them again.
* When the recipient's bank is your own ISPB, the transfer is internal (`type` set to `INTERNAL`). Midaz settles it, and nothing goes to the STR.
* From your own core, set `party` on the sender and on the recipient. Without it, the party is `institution`, and Lerian SPB sends a different STR message.
* TED Lerian credits an incoming TED once, also when Lerian SPB delivers it twice.
* When the account cannot receive an incoming TED, TED Lerian returns it with the official reason:
  * `1`: a closed account.
  * `2`: no account at that branch and number.
  * `5`: the holder's document does not match.
  * `84`: the account type in the TED is not the account's type.
* An account counts as closed when its closing date is today or earlier, in Brasília time.
* When TED Lerian cannot decide on its own, the TED goes to `MANUAL_REVIEW`.

## How you know it finished

***

* **Send.** The event `transfer.settled`, or [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/get-a-transfer) with `status` set to `SETTLED`. From your own core, the event `settlement.settled` for the operation.
* **Receive.** The event `incoming_transfer.credited`, `incoming_return.returned` or `incoming_transfer.recorded`, or [`GET /v1/incoming-transfers/{incomingTransferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/get-an-incoming-ted) with `status` set to `CREDITED`, `RETURNED` or `RECORDED`.

## What can go wrong

***

| Situation | What you see | What to do |
| - | - | - |
| Outside the official schedule or after your cut-off | `422` with `TED-0020` | Nothing is held. Send the TED in the next window. [`GET /v1/policy/window`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/get-the-operating-window) shows it. |
| A weekend or a holiday | `422` with `TED-0021` | Nothing is held. Send the TED on the next business day. |
| TED Lerian cannot determine the window | `503` with `TED-0022` | Nothing is held. If the holiday calendar of that year is not loaded, load it. Then send the TED again. |
| Your usage limits are not set | `503` with `TED-0080` | Set them with [`PUT /v1/policy/limits`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/set-usage-limits). |
| A usage limit is exceeded | `422` with `TED-0030` | Nothing is held. Lower the amount, or wait for the next day or month. |
| The fee cannot be determined | `503` with `TED-0040` | Nothing is held. Read `detail`: fix the fee package configuration or retry later, according to the cause. |
| The source account cannot pay the amount plus the fee | `201` with `REJECTED` and `rejection.code` set to `TED-0031` | Nothing is held. Adjust the amount. |
| Lerian SPB or the STR refuses the TED | `REJECTED` in the answer, or later with `transfer.rejected` | TED Lerian releases the hold. Read `rejection`, correct the data and send a new TED with a new key. |
| Midaz or Lerian SPB does not answer TED Lerian in time | `201` with `AWAITING_RECONCILIATION`, or `transfer.awaiting_reconciliation` | Do not send the TED again. If the transfer becomes `EXHAUSTED`, an operator unblocks it with the STR evidence through [`POST /v1/transfers/{transferId}/unblock`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/unblock-a-transfer). |
| Your request gets no answer | A timeout | Do not assume that the TED failed. Send the same request with the same `X-Idempotency` key. The same key never creates a second transfer. Before you use a new key, look for the transfer with [`GET /v1/transfers`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/list-transfers) filtered by `client_reference`. |
| The receiving institution returns a TED that you sent | `transfer.returned` | TED Lerian credits the amount back to the source account. The transfer stays `SETTLED`. |
| From your own core, the STR does not settle the TED | `settlement.failed` | The TED did not settle. Do not book the debit. |
| A TED for a customer arrives through an ISPB with no binding | No incoming TED and no event | In a single-tenant installation, TED Lerian returns the TED to the sending institution with the official reason `2`. In Lerian Cloud, it is not credited. Bind every ISPB before you receive TEDs through it, with [`PUT /v1/policy/ispb-bindings`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/replace-ispb-bindings). |
| An incoming TED waits for a decision | `incoming_transfer.manual_review` | Read `reviewReason` on the incoming TED. Then credit the TED, return it or confirm its credit with [`POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/resolve-an-incoming-ted-review). Decide before `slaDeadlineAt`. |
| The STR refuses an automatic return | `incoming_return.failed` | The TED goes to `MANUAL_REVIEW`. Decide with [`POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/resolve-an-incoming-ted-review). |

The [TED Lerian error list](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/ted-lerian-error-list.md) describes each code.

## Related

***

* [Cancel or return a TED](https://docs.lerian.studio/en/diagrams/native-rails/cancel-or-return-a-ted.md)
* [Reserve an amount, then confirm or cancel](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-reserve-then-confirm-or-cancel.md)
* [How TED Lerian works](https://docs.lerian.studio/en/interfaces/ted-lerian/ted-lerian-how-it-works.md)
* [TED Lerian events](https://docs.lerian.studio/en/interfaces/ted-lerian/ted-lerian-events.md)
* [Lerian SPB events and ledger integration](https://docs.lerian.studio/en/rails/spb/spb-events-and-ledger-integration.md)


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