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.

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.

​

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.
• 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. GET /v1/webhooks/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.

​

Send a TED through JD

#	From	To	Message	Lerian API	What happens
1	Your institution	TED JD	Lerian API	POST /v1/transfers/initiate	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	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}	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

#	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}	Read the received TED. Without the event, find it with GET /v1/transfers.
9	TED JD	Your institution	Lerian API	Response to step 8	The received TED is COMPLETED.

​

A sent TED comes back through JD

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

#	From	To	Message	Lerian API	What happens
1	Your institution	TED JD	Lerian API	POST /v1/transfers/{transferId}/return	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}	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.

​

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} shows the status.
• Receive a TED. The webhook transfer_incoming.completed reports the credit. GET /v1/transfers/{transferId} 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} 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} 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 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 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. 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.

​

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.
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: the same journeys on the native Lerian SPB.
• Cancel or return a TED: the return on the native Lerian SPB.
• Send (TED OUT)
• Receive (TED IN)
• Webhooks
• Developer guide