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

# Cancel or return a TED

> Cancel a TED that the STR holds as pending, or return a credited TED to the sending institution, through TED Lerian and Lerian SPB.

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

> [!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 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](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 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

![Cancel or return a TED: Cancel a TED pending at the STR](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-cancel-or-return-a-ted-1.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=6675206dd366a8ecea71d9ca089a888f)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | TED Lerian | Lerian SPB | Internal call | [`GET /v1/str/messages/{nuOp}`](https://docs.lerian.studio/en/reference/rails/spb/get-message-status) | 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`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/cancel-a-transfer) | 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`](https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-cancellation-operation) | 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`](https://docs.lerian.studio/en/reference/products/midaz/v2/cancel-transaction) | 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

![Cancel or return a TED: Return an incoming TED](https://mintcdn.com/lerian-49cb71fc/qgZtW0Vn3HlCLdfR/images/en/d2/id-cancel-or-return-a-ted-2.svg?fit=max\&auto=format\&n=qgZtW0Vn3HlCLdfR\&q=85\&s=db0bf0df077ce63c2f32b0e4218d48ee)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | TED Lerian | API call | [`POST /v1/incoming-transfers/{incomingTransferId}/return`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/return-an-incoming-ted) | 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`](https://docs.lerian.studio/en/reference/products/midaz/v2/revert-transaction) | 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`](https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-return-operation) | 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}`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/get-a-transfer) with `status` set to `CANCELLED`.
* **Return.** The event `incoming_return.returned`, or [`GET /v1/incoming-transfers/{incomingTransferId}`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/get-an-incoming-ted) 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`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/unblock-a-transfer). |
| 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`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/resolve-an-incoming-ted-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`](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/resolve-an-incoming-ted-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`](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

***

* [Send and receive TED](https://docs.lerian.studio/en/diagrams/native-rails/send-and-receive-ted.md)
* [Reverse a transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-reverse-a-transaction.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.