> ## 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. # Resolve manual review of an incoming TED (operator) > **Operator** action that decides an incoming TED in `MANUAL_REVIEW` (in any other state, 409 `TED-0060`). - `CREDIT` credits the recipient in the account you send in `accountId` (or in the account already on record). It applies the same validations as the automatic credit: holder, account type, and complete registration (422 `TED-0002` if they fail). - `RETURN` returns the full amount to the sender. It requires `returnCode` (422 `TED-0066`). - `CONFIRM_CREDITED` records a credit already made directly in the ledger. `evidence` is the UUID of the Midaz transaction (422 `TED-0065`). Each TED has at most one credit (key `credit:`). A TED older than the idempotency window of the ledger does not accept `CREDIT` (409 `TED-0060`): reconcile it in the ledger and record it with `CONFIRM_CREDITED`. Requires `X-Idempotency` and a justification. ## OpenAPI ````yaml /es/openapi/v3-current/ted-lerian.yaml post /v1/incoming-transfers/{incomingTransferId}/resolve-review 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](/es/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/incoming-transfers/{incomingTransferId}/resolve-review: post: tags: - Incoming Transfers summary: Resolve manual review of an incoming TED (operator) description: >- **Operator** action that decides an incoming TED in `MANUAL_REVIEW` (in any other state, 409 `TED-0060`). - `CREDIT` credits the recipient in the account you send in `accountId` (or in the account already on record). It applies the same validations as the automatic credit: holder, account type, and complete registration (422 `TED-0002` if they fail). - `RETURN` returns the full amount to the sender. It requires `returnCode` (422 `TED-0066`). - `CONFIRM_CREDITED` records a credit already made directly in the ledger. `evidence` is the UUID of the Midaz transaction (422 `TED-0065`). Each TED has at most one credit (key `credit:`). A TED older than the idempotency window of the ledger does not accept `CREDIT` (409 `TED-0060`): reconcile it in the ledger and record it with `CONFIRM_CREDITED`. Requires `X-Idempotency` and a justification. operationId: resolveIncomingTransferReview 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. The window sets how long the response is replayed. in: header name: X-TTL schema: minimum: 1 type: integer - description: Identifier of the incoming TED in: path name: incomingTransferId required: true schema: description: Identifier of the incoming TED 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: examples: confirm-credited: summary: Record a credit already applied in the ledger value: action: CONFIRM_CREDITED evidence: e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b justification: Credit posted manually in the ledger after an incident. credit: summary: Credit to the account the operator found value: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f action: CREDIT justification: Account found manually by the recipient's CPF. return: summary: Return to the sender value: action: RETURN justification: The recipient has no account at this institution. returnCode: '2' schema: $ref: '#/components/schemas/ResolveReviewRequestBody' required: true responses: '200': content: application/json: example: amount: '1500.00' createdAt: '2026-10-22T14:10:03Z' creditedAmount: '1500.00' creditedAt: '2026-10-22T14:10:09Z' description: Supplier payment feeAmount: '0.00' incomingTransferId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a interbankSettledAt: '2026-10-22T14:10:03Z' kind: CLIENT numCtrlStr: STR20261022000000123 nuop: '87654321202610220000123' organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 purposeCode: '00010' recipient: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f agency: '0001' bankAccount: '0001111222' bankAccountType: CACC bankId: '12345678' document: '98765432100' name: João Pereira sender: agency: '1234' bankAccount: '0001234567' bankAccountType: CACC bankId: '87654321' document: '12345678901' name: Maria da Silva slaDeadlineAt: '2026-10-22T15:10:03Z' status: CREDITED updatedAt: '2026-10-22T14:10:09Z' schema: $ref: '#/components/schemas/IncomingTransferResponse' description: >- Review resolved. The incoming TED returns in the state that results from the action. If `X-Idempotency-Replayed: true`, this is the replay of a previous resolution. 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 are identical in both cases. 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, or the product license is not valid for the organization (`TED-0071`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Incoming TED not in `MANUAL_REVIEW`, or a credit older than the ledger idempotency window (`TED-0060`); or a request with the same `X-Idempotency` is still in progress (`TED-0013`; try again after `Retry-After`). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `returnCode` missing with `action=RETURN` (`TED-0066`) or invalid (`TED-0064`); evidence missing or invalid with `CONFIRM_CREDITED` (`TED-0065`); credit validation failed: holder mismatch, incompatible account type, or incomplete registration (`TED-0002`); the ledger refused the credit or its reversal (`TED-1001`); idempotency key reused with a different body (`TED-0012`). 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: >- Account registry unavailable (`TED-1020`) or institution configuration missing (`TED-0080`): no credit was made. Ledger outcome unknown (`TED-1000`): the credit, or the reversal of the credit for `action=RETURN`, can already be recorded. Do not credit the customer by other means. A new `CREDIT` does not credit the customer twice. 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: ResolveReviewRequestBody: additionalProperties: false description: >- Operator decision on an incoming TED in manual review: credit it, return it, or record a credit already applied in the ledger. properties: accountId: description: >- Destination account when the operator resolves the location (usually with action=CREDIT). format: uuid type: string action: description: >- CREDIT makes the credit; RETURN returns (requires returnCode); CONFIRM_CREDITED records a credit already confirmed in the ledger, with evidence. enum: - CREDIT - RETURN - CONFIRM_CREDITED type: string evidence: description: >- Required when action=CONFIRM_CREDITED: the identifier (UUID) of the Midaz transaction for the credit already applied (TED-0065 if missing or invalid). maxLength: 64 type: string justification: description: Operator justification. maxLength: 500 minLength: 10 type: string returnCode: description: >- Required when action=RETURN (TED-0066 if absent); not allowed in the other actions. examples: - '3' pattern: ^[0-9]{1,2}$ type: string required: - action - justification type: object IncomingTransferResponse: additionalProperties: false description: >- An incoming TED from another institution: amount, parties, regulatory credit deadline, and the state of the credit to the recipient. `status=MANUAL_REVIEW` with `reviewReason` indicates that the operation needs a human decision. properties: amount: description: Amount in BRL as a decimal string with two decimal places. examples: - '1500.00' pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string createdAt: description: Time (UTC) when this service recorded the TED. format: date-time type: string creditedAmount: description: >- Amount actually credited to the recipient (amount − feeAmount), in BRL. Present from CREDITED onward. examples: - '1500.00' pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string creditedAt: description: Time (UTC) of the credit to the recipient. format: date-time type: string description: description: Description given by the sender. type: string feeAmount: description: Fee applied to the credit, in BRL (0.00 when exempt). examples: - '0.00' pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string incomingTransferId: description: Identifier of the incoming TED. Use it in queries and actions. format: uuid type: string interbankSettledAt: description: >- Interbank settlement reported by the STR (start of the 60-min deadline) format: date-time type: string kind: description: Credit to a customer or to the institution's own account enum: - CLIENT - INSTITUTION type: string numCtrlStr: description: Entry identifier assigned by the STR (20 characters). pattern: ^[A-Za-z0-9]{20}$ type: string nuop: description: Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7]) pattern: ^[0-9]{23}$ type: string organizationId: description: Organization resolved through the ISPB→organization binding format: uuid type: string purposeCode: description: Purpose code sent by the sender (FinlddCli, 5 digits). examples: - '00010' pattern: ^[0-9]{5}$ type: string recipient: $ref: '#/components/schemas/IncomingPartyResponse' description: >- Recipient in your own institution; accountId is present when the account was found. returnCode: description: >- Official return reason (CodDevTransf) of the active return, when there is one. examples: - '3' pattern: ^[0-9]{1,2}$ type: string returnedAt: description: Instant (UTC) when the STR confirmed the return. format: date-time type: string reviewReason: description: >- Reason for the manual review, when status=MANUAL_REVIEW. From the credit decision: ISPB_BINDING_UNRESOLVED, ACCOUNT_NOT_FOUND, ACCOUNT_INACTIVE, HOLDER_MISMATCH, ACCOUNT_TYPE_INCOMPATIBLE, ENRICHMENT_INCOMPLETE, RAIL_INDETERMINATE, LEDGER_INDETERMINATE, REGISTRY_INDETERMINATE. From the return cycle: RETURN_REFUSED_BY_STR, RETURN_REQUEST_MALFORMED, RETURN_CODE_UNMAPPED, RETURN_REJECTED_BY_STR. type: string sender: $ref: '#/components/schemas/IncomingPartyResponse' description: Sender, at another institution. slaDeadlineAt: description: >- Regulatory deadline to credit or return: interbankSettledAt + 60 min (UTC). format: date-time type: string status: description: >- Current state: RECEIVED (received from the STR, credit decision in progress) → CREDITED (credited to the customer), RECORDED (the institution's own account, terminal), or MANUAL_REVIEW (waits for an operator; see reviewReason); RETURN_REQUESTED (return sent to the STR) → RETURNED (confirmed, terminal). If the STR refuses a return, the TED goes back to MANUAL_REVIEW with reviewReason filled in. enum: - RECEIVED - CREDITED - RECORDED - RETURN_REQUESTED - RETURNED - MANUAL_REVIEW type: string updatedAt: description: Timestamp (UTC) of the last update to the record. format: date-time type: string required: - incomingTransferId - status - nuop - amount - sender - recipient - interbankSettledAt - slaDeadlineAt - createdAt - updatedAt type: object 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 IncomingPartyResponse: additionalProperties: false description: >- One of the parties of the incoming TED. For the recipient, `accountId` is only filled in after the account is found in the institution. Until then, only the bank data received from the STR is available. properties: accountId: description: >- Account in the institution's own ledger. Present only when the recipient was already found. format: uuid type: string agency: description: Branch. type: string bankAccount: description: Account number. type: string bankAccountType: description: >- Account type: CACC (checking), SVGS (savings), SLRY (salary), or TRAN (payment). enum: - CACC - SVGS - SLRY - TRAN type: string bankId: description: >- ISPB of the institution (8 digits). Always present. Empty string when unknown. pattern: ^[0-9]{8}$ type: string document: description: CPF (11 digits) or CNPJ (14 digits), digits only. examples: - '12345678901' pattern: ^([0-9]{11}|[0-9]{14})$ type: string name: description: Name of the party, not truncated. type: string required: - bankId 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.