> ## 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. # 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`. ## OpenAPI ````yaml /pt/openapi/v3-current/ted-lerian.yaml post /v1/reconciliation/held-returns/{heldReturnId}/close openapi: 3.1.0 info: description: >- API of **TED Lerian**, the interface over Lerian SPB. Your institution uses it to send TEDs, make internal transfers, track incoming TEDs, and operate returns, queues, and policy on its Midaz ledger. The [API overview](/pt/reference/interfaces/ted-lerian/ted-lerian-api-overview) gives the concepts, the roles, and the conventions. title: TED Lerian API version: v1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- Outgoing TEDs and internal transfers: fee quote, creation, query, timeline, and cancellation. Every integration starts here. name: Transfers - description: >- Incoming TEDs from other institutions: query, timeline, and operator actions (full return and manual review resolution). name: Incoming Transfers - description: >- STR participant list, to resolve COMPE code ↔ ISPB and validate the destination bank before you create a transfer. name: Participants - description: >- Back office: operations queue, inconsistency findings between the ledger and the STR, reviews of rail facts, held returns, and manual unblock with evidence. name: Reconciliation - description: >- Operations dashboard: daily aggregates, regulatory deadlines (30/60/60 min), and the closing balance that the STR reported. name: Operations - description: >- Institution configuration (editor): operating window and cut-off, usage limits, holiday calendar, and ISPB → organization bindings. name: Policy paths: /v1/reconciliation/held-returns/{heldReturnId}/close: post: tags: - Reconciliation summary: Close a held return with ledger evidence (operator) description: >- **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`. operationId: closeHeldReturn parameters: - description: >- 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. in: header name: X-TTL schema: minimum: 1 type: integer - description: Identifier of the held return. in: path name: heldReturnId required: true schema: description: Identifier of the held return. format: uuid type: string - description: >- 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`. in: header name: X-Idempotency required: true schema: type: string - $ref: '#/components/parameters/XRequestId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CloseHeldReturnRequest' examples: credited: summary: 'TED not sent through TED Lerian: sender credited in the ledger' value: ledgerTransactionId: c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f released: summary: >- TED Lerian transfer ended REJECTED: hold released, nothing to credit value: ledgerTransactionId: e8f9a0b1-c2d3-4e4f-8a5b-6c7d8e9f0a1b required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/HeldReturnResponse' example: amount: '250.00' closedAt: '2026-10-22T15:02:00Z' closedBy: operator@instituicao.example 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 description: >- Held return closed. If `X-Idempotency-Replayed: true`, this is the replay of a previous closure. headers: X-Idempotency-Replayed: description: >- `true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state. schema: type: boolean X-Request-Id: $ref: '#/components/headers/XRequestId' '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: 'Not authenticated: token missing, invalid, or expired (`TED-0070`).' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- No permission: the token's role does not authorize this action (`TED-0071`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The held return does not exist in this institution (`TED-0010`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Return closed with another ledger transaction, or already taken by TED Lerian when its TED settled (`TED-0060`); a transfer that can still settle carries the return (`TED-0067`); or a request with the same `X-Idempotency` is still processing (`TED-0013`; retry after `Retry-After`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- A validation or business rule failed: invalid fields (`TED-0002`, see `errors`), or `X-Idempotency` reused with a different body (`TED-0012`). Refusals specific to the operation are in its description. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' components: parameters: XRequestId: description: >- 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. in: header name: X-Request-Id schema: format: uuid type: string schemas: CloseHeldReturnRequest: additionalProperties: false properties: ledgerTransactionId: description: >- 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). format: uuid type: string required: - ledgerTransactionId type: object description: >- 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. HeldReturnResponse: additionalProperties: false properties: amount: description: Returned amount. type: string closedAt: description: Instant (UTC) of the closure. format: date-time type: string closedBy: description: Operator who closed the return. type: string id: description: Identifier of the held return. format: uuid type: string ledgerTransactionId: description: >- 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). format: uuid type: string originalNumCtrlStr: description: NumCtrlSTR of the returned TED (NumCtrlSTROr). type: string returnCode: description: Official return reason (CodDevTransf). type: string returnedAt: description: Instant of the return at the STR. format: date-time type: string transferId: description: >- 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). format: uuid type: - string - 'null' transferStatus: description: >- 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. type: - string - 'null' required: - id - originalNumCtrlStr - amount - returnCode - returnedAt - transferId - transferStatus type: object description: >- 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. Detail: additionalProperties: true description: >- Standard error body (RFC 9457, `application/problem+json`) for every `/v1` operation. Use `code` (TED-NNNN) to handle the error in code, `detail` for the readable message, and `errors` for the invalid fields of a 422. The `X-Request-Id` of the response identifies the occurrence for support. properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorDetail: additionalProperties: false description: >- An invalid field inside a validation error: where it is (`location`), what is wrong (`message`), and the value received. properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false description: >- Error reported by an upstream system (ledger or rail), when the service chooses to expose it. Absent in most errors. properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object headers: XRequestId: description: >- Echo of the request X-Request-Id: the value that the client sent, or the UUID that the platform generated when the client sent none. Present in every response, success or error. schema: format: uuid type: string securitySchemes: BearerAuth: bearerFormat: JWT description: >- JWT token that the Lerian Access Manager issues for your institution. Send it in `Authorization: Bearer ` 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`. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.