Cancel or return a TED

Cancel a TED that you sent before the STR settles it, or return a TED that a customer received.

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 cancels the TEDs it sent and returns the TEDs it received.
TED Lerian. The TED interface between Midaz and Lerian SPB. It checks each request, 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 cancels pending entries and settles each return.

Before you start

To cancel a TED that the STR holds as pending, this cancellation must be on for your institution. It is off by default.
To return a TED, you have the official return reason: a CodDevTransf code of the SFN domain dictionary.

Diagram

Cancel a TED pending at the STR

#	From	To	Message	Lerian API	What happens
1	TED Lerian	Lerian SPB	Internal call	`GET /v1/str/messages/{nuOp}`	TED Lerian reads the status at the STR of each TED in `SUBMITTED`.
2	Lerian SPB	TED Lerian	Internal call		The STR holds the entry as pending.
3	TED Lerian	Your institution	Event	Event `transfer.pending_str`	The transfer is `PENDING_STR`. The hold stays on the source account.
4	Your institution	TED Lerian	API call	`POST /v1/transfers/{transferId}/cancel`	Ask for the cancellation. Send a key in `X-Idempotency` and, optionally, a `reason`.
5	TED Lerian	Lerian SPB	Internal call	`POST /v1/str/operations/bank-transfers/{operationId}/cancellations`	TED Lerian tells Lerian SPB to cancel the entry.
6	TED Lerian	Your institution	API answer	Response to step 4	`202`.
7	Lerian SPB	STR (BACEN)	`STR0011`		Lerian SPB asks the STR to cancel the pending entry.
8	STR (BACEN)	Lerian SPB	`STR0011R1`		The STR cancels the entry and answers.
9	Lerian SPB	TED Lerian	Event		Lerian SPB reports with `settlement.failed` that the TED will not settle.
10	TED Lerian	Your institution	Event	Event `transfer.cancelled`	The transfer is `CANCELLED`.
11	TED Lerian	Midaz	Internal call	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel`	TED Lerian cancels the pending transaction. The held amount and the fee go back to the available balance of the source account.

Return an incoming TED

#	From	To	Message	Lerian API	What happens
1	Your institution	TED Lerian	API call	`POST /v1/incoming-transfers/{incomingTransferId}/return`	Ask for the return. Send `returnCode` and a `justification` of 10 to 500 characters, with a key in `X-Idempotency`.
2	TED Lerian	Your institution	Event	Event `incoming_return.requested`	TED Lerian records the return. The TED is `RETURN_REQUESTED`.
3	TED Lerian	Midaz	Internal call	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/revert`	TED Lerian reverses the credit. Midaz posts a new reverse transaction, and the original credit does not change.
4	TED Lerian	Lerian SPB	Internal call	`POST /v1/str/operations/bank-transfers/{operationId}/returns`	TED Lerian tells Lerian SPB to return the TED with your reason.
5	TED Lerian	Your institution	API answer	Response to step 1	`202` with the incoming TED in `RETURN_REQUESTED`.
6	Lerian SPB	STR (BACEN)	`STR0010`		Lerian SPB sends the return to the STR.
7	STR (BACEN)	Lerian SPB	`STR0010R1`		The STR settles the return and answers.
8	Lerian SPB	TED Lerian	Event		Lerian SPB reports the settlement of the return with `settlement.settled`.
9	TED Lerian	Your institution	Event	Event `incoming_return.returned`	The TED is `RETURNED`. The money went back to the sending institution.

Rules

TED Lerian cancels a transfer in CREATED or RESERVED with 200 and releases any hold. While TED Lerian places the hold or sends the transfer, the answer is 409 with TED-0061.
For a transfer in PENDING_STR, TED Lerian asks the STR to cancel the entry. The answer is 202, and the hold stays until the STR answers. The result arrives as transfer.cancelled, transfer.settled or transfer.rejected.
A transfer already CANCELLED answers 200 again.
TED Lerian refuses to cancel a transfer in SUBMITTED, SETTLED or REJECTED.
This call returns only an incoming TED in CREDITED, and always in full.

How you know it finished

Cancel. The event transfer.cancelled, or GET /v1/transfers/{transferId} with status set to CANCELLED.
Return. The event incoming_return.returned, or GET /v1/incoming-transfers/{incomingTransferId} with status set to RETURNED.

What can go wrong

Situation	What you see	What to do
The cancellation of a pending TED is off	`503` with `TED-1012`	Follow the transfer until it reaches a final status.
The transfer cannot be cancelled in its status	`409` with `TED-0061`	Read the transfer. For `AWAITING_RECONCILIATION` or `EXHAUSTED`, an operator unblocks it with the STR evidence through `POST /v1/transfers/{transferId}/unblock`.
The answer of Lerian SPB to the cancellation is not known	`503` with `TED-1010`	Send the request again with the same `X-Idempotency` key and the same `reason`.
The customer’s balance cannot pay the reversal	`422` with `TED-1001`	Nothing went to the STR, and the customer keeps the credit. The TED goes to `MANUAL_REVIEW`. Decide with `POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`.
Midaz does not confirm the reversal	`503` with `TED-1000`	Nothing went to the STR. The TED goes to `MANUAL_REVIEW`. Read the TED before you act again.
The TED is in manual review	`409` with `TED-0062`	Return it with `POST /v1/incoming-transfers/{incomingTransferId}/resolve-review` and the action `RETURN`.
The STR refuses the 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)

Cancel or return a TED

Participants

Before you start

Diagram

Cancel a TED pending at the STR

Return an incoming TED

Rules

How you know it finished

What can go wrong

​Participants

​Before you start

​Diagram

​Cancel a TED pending at the STR

​Return an incoming TED

​Rules

​How you know it finished

​What can go wrong

​Related

Participants

Before you start

Diagram

Cancel a TED pending at the STR

Return an incoming TED

Rules

How you know it finished

What can go wrong

Related