Close a held return with ledger evidence (operator)

Operator action that closes a held return with the ledger transaction that evidences it (ledgerTransactionId), recording the operator and the time. TED Lerian does not move money: the credit to the sender, when due, is made in the ledger beforehand, and only recorded here.

Which transaction to send:

• No TED Lerian transfer carries the NumCtrlSTR (transferId null): the transaction that credited the sender. If the TED was a TED Lerian transfer that ended REJECTED or CANCELLED, the sender was never debited: never credit the sender, and send the transaction that released the sender’s hold.
• transferStatus REJECTED or CANCELLED: the STR settled a TED that TED Lerian recorded as failed, and the return reverses that settlement. The sender was never debited, so there is nothing to credit, and the sender must never be credited. The evidence is the transaction that released the sender’s hold. The response shows that transferStatus.

A closed return is never refunded by TED Lerian, even if the original TED settles later. Repeating the closure with the same transaction returns the existing record. With another transaction, the response is 409 TED-0060: the recorded transaction stays the closure, and the sender may have been credited twice, so reverse only the credit made for this attempt. If TED Lerian already took the return when the TED settled (it refunded the sender or parked the return for review), the response is also 409 TED-0060: when the transfer shows this return refunded, reverse any ledger credit made for it. If the TED Lerian transfer can still settle, the response is 409 TED-0067: TED Lerian refunds the sender when it settles, so reverse the credit as well. Requires X-Idempotency; always check X-Idempotency-Replayed.

POST /v1/reconciliation/held-returns/{heldReturnId}/close

cURL

credited

curl --request POST \ --url https://api.example.com/v1/reconciliation/held-returns/{heldReturnId}/close \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency: <x-idempotency>' \ --data ' { "ledgerTransactionId": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f" } '

200

{
  "amount": "250.00",
  "closedAt": "2026-10-22T15:02:00Z",
  "closedBy": "[e-mail]",
  "id": "7a9c2e4f-1b3d-4c5e-8f6a-2d4b6c8e0a1f",
  "ledgerTransactionId": "e8f9a0b1-c2d3-4e4f-8a5b-6c7d8e9f0a1b",
  "originalNumCtrlStr": "STR20261022000000456",
  "returnCode": "2",
  "returnedAt": "2026-10-22T14:12:30Z",
  "transferId": "6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b",
  "transferStatus": "REJECTED"
}

Autorizações

Authorization · string · header · obrigatório

JWT token that the Lerian Access Manager issues for your institution. Send it in Authorization: Bearer <token> on every call (except the public health probes). The tenant never comes from the body, the query, or the path. Each operation requires a role with the matching permission (see the API overview). Without it, 403 TED-0071. Missing, invalid, or expired token: 401 TED-0070.

Cabeçalhos

X-TTL · integer

Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte.

Intervalo obrigatório: x >= 1

X-Idempotency · string · obrigatório

Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with X-Idempotency-Replayed: true and no new effect. Same key + different body responds 422 TED-0012. Same key still in processing responds 409 TED-0013 (retry after Retry-After). Missing or in the wrong format: 400 TED-0011.

X-Request-Id · string<uuid>

Correlation identifier of this request (UUID). Optional: when you omit it, or when the value is not a well-formed UUID, the platform creates a UUID and returns it in the X-Request-Id header of the response. The resolved identifier goes to the logs, spans, and audit events of this request. Keep it to open a support ticket.

Parâmetros de caminho

heldReturnId · string<uuid> · obrigatório

Identifier of the held return.

Corpo

application/json

Evidence of the closure of a held return: the ledger transaction that credited the sender or, when the TED Lerian transfer ended REJECTED/CANCELLED, the one that released the sender's hold.

ledgerTransactionId · string<uuid> · obrigatório

Ledger transaction that evidences the closure: the one that credited the sender or, if the TED Lerian transfer that carries the return ended REJECTED or CANCELLED, the one that released the sender's hold (nothing to credit).

Resposta

200

application/json

Held return closed. If X-Idempotency-Replayed: true, this is the replay of a previous closure.

Held return: a return (STR0010R2) received from the STR for a TED that no SETTLED transfer of this institution carries by NumCtrlSTR, waiting for the operator. transferId/transferStatus say whether a TED Lerian transfer carries it; closedBy, closedAt, and ledgerTransactionId exist only after the closure.

amount · string · obrigatório

Returned amount.

id · string<uuid> · obrigatório

Identifier of the held return.

originalNumCtrlStr · string · obrigatório

NumCtrlSTR of the returned TED (NumCtrlSTROr).

returnCode · string · obrigatório

Official return reason (CodDevTransf).

returnedAt · string<date-time> · obrigatório

Instant of the return at the STR.

transferId · string<uuid> | null · obrigatório

TED Lerian transfer that carries the NumCtrlSTR of the returned TED. Null while no transfer carries it: TED Lerian did not send the TED, or its TED did not receive a NumCtrlSTR from a rail fact (in any status, SUBMITTED included).

transferStatus · string | null · obrigatório

Current status of that transfer; null without it. REJECTED or CANCELLED: the sender was never debited and there is nothing to credit. Never credit the sender; close the return with evidence.

closedAt · string<date-time>

Instant (UTC) of the closure.

closedBy · string

Operator who closed the return.

ledgerTransactionId · string<uuid>

Ledger transaction that evidences the closure: the one that credited the sender or, with transferStatus REJECTED or CANCELLED, the one that released the sender's hold (nothing to credit).