Send and receive TED

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

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.

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 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.
Load the national holiday calendar of each year with PUT /v1/policy/holidays, 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. 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.
To receive TEDs, bind your ISPB to the Midaz organization and ledger that receive the credits, with PUT /v1/policy/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.

Diagram

Send from a Midaz account

#	From	To	Message	Lerian API	What happens
1	Your institution	TED Lerian	API call	`POST /v1/transfers/fee-quotes`	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`	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`	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`	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`	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

#	From	To	Message	Lerian API	What happens
1	Your institution	Lerian SPB	API call	`POST /v1/str/operations/bank-transfers`	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

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

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

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

The TED Lerian error list describes each code.

Overview

Secured credit

Payments

Settlement and daily operation

Consignado CLT (Dataprev)

Send and receive TED

Participants

Before you start