TED Lerian use cases

Journeys an institution runs with TED Lerian: supplier payments, withdrawals, internal transfers, incoming TEDs, returns and back-office work.

Each use case shows who acts at each step, the API call or event involved, and what happens when the journey does not go the expected way.

Supplier payments

---

An ERP pays supplier invoices to accounts at other banks. Each payment goes as one TED with an official purpose code and a reference that ties the transfer to the invoice.

1. The ERP approves the batch of invoices to pay.
2. For each payment, it calls POST /v1/transfers/fee-quotes to show the fee, the total and whether the STR window is open.
3. It sends each TED with POST /v1/transfers, the invoice number in clientReference and its own X-Idempotency key.
4. TED Lerian holds the amount plus the fee in Midaz.
5. TED Lerian sends the TED to Lerian SPB, which sends it to the STR.
6. Lerian SPB reports that the STR settled the TED.
7. TED Lerian publishes transfer.settled.
8. The ERP closes the invoice it finds through clientReference.

If the network drops during the batch, resending a request with the same X-Idempotency key creates no second transfer. If the STR rejects the TED, TED Lerian releases the hold and transfer.rejected carries the reason.

Withdrawal to the customer’s account at another bank

---

A customer moves the balance from your platform to their own account at another bank. The app shows the cost, keeps the balance from being spent twice, and tells the customer when the money left.

1. The customer asks for the withdrawal and enters the bank details.
2. The app calls POST /v1/transfers/fee-quotes and shows the fee.
3. The customer confirms.
4. The app sends the TED with POST /v1/transfers.
5. TED Lerian holds the amount plus the fee in Midaz, so the balance cannot be spent twice.
6. TED Lerian sends the TED to Lerian SPB, which sends it to the STR.
7. Lerian SPB reports that the STR settled the TED.
8. TED Lerian publishes transfer.settled.
9. The app tells the customer the withdrawal is complete.

If the window is closed, the quote returns windowOpen as false and the app shows nextWindowOpensAt before the customer confirms. If the TED is rejected, the hold is released and the balance returns to the customer.

Transfer between customers of the same institution

---

When the recipient’s bank is your own institution, the same request becomes an internal transfer. It settles in one Midaz transaction, also outside the STR hours. Usage limits and, when configured, the fee still apply.

1. The customer pays another customer of the same institution.
2. The app sends POST /v1/transfers with the institution’s own ISPB as the recipient’s bank.
3. TED Lerian finds the recipient account in the Midaz CRM.
4. Midaz debits and credits in the same transaction.
5. The response comes back at once with type=INTERNAL and status=SETTLED.

With insufficient balance, the response is 201 with status=REJECTED and TED-0031. If TED Lerian does not find the recipient, it refuses the request with 422 TED-1021 and creates nothing.

Receive a TED and credit the customer within 60 minutes

---

A customer receives a TED from another bank. The rule gives 60 minutes from interbank settlement to credit or return it. TED Lerian does this with no human step in the normal case.

1. Lerian SPB reports a TED that the STR settled. The 60 minute deadline starts.
2. TED Lerian records the incoming TED and publishes incoming_transfer.received.
3. TED Lerian looks up the account and its holder in the Midaz CRM by branch, account and document.
4. TED Lerian checks that the holder and the account type match.
5. Midaz credits the customer.
6. TED Lerian publishes incoming_transfer.credited.
7. The institution’s system tells the customer about the TED.

If the account does not exist or belongs to a different holder, TED Lerian returns the TED with the official reason (incoming_return.*). If it cannot decide, the TED goes to manual review and shows up in the operator’s queue.

Return an incoming TED on suspected fraud

---

A TED was credited, but the sending institution asks for it back or the fraud team finds a problem. The operator orders a full return with the official reason and a justification that stays in the audit trail.

1. The operator flags the suspicion.
2. The operator reads the timeline with GET /v1/incoming-transfers/{incomingTransferId}/timeline.
3. The operator orders the return with POST /v1/incoming-transfers/{incomingTransferId}/return, the official reason and a justification.
4. Midaz reverses the customer’s credit.
5. TED Lerian sends the return to Lerian SPB, which sends it to the STR.
6. Lerian SPB reports that the STR settled the return.
7. TED Lerian publishes incoming_return.returned.

If the STR refuses the return, incoming_return.failed arrives and the TED goes back to manual review.

Back-office work on a transfer with no answer

---

You sent a TED and no answer came in time. TED Lerian keeps the hold and asks Lerian SPB for the real outcome. When the automatic answer is not conclusive, an operator decides with evidence.

1. The transfer moves to AWAITING_RECONCILIATION and keeps the hold.
2. TED Lerian asks Lerian SPB for the outcome.
3. The answer is not conclusive.
4. The operator sees the item in the queue with GET /v1/reconciliation/queue, with its age and deadline.
5. The operator unblocks it with POST /v1/transfers/{transferId}/unblock, the outcome and the STR evidence.
6. Midaz settles or releases the hold, as the outcome says.
7. TED Lerian publishes transfer.settled or transfer.rejected.

When the answer is conclusive, TED Lerian applies the outcome on its own and the operator does not act.