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:<nuop>). 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.

A repeat with the same X-Idempotency returns the original response (2xx or 4xx) with X-Idempotency-Replayed: true. A 5xx response is not stored: a repeat with the same key runs the action again and, if the decision is already applied, responds 409 TED-0060. A new key on a decision that is already applied responds 409 TED-0060: CREDIT on a TED that the review already credited, or RETURN on a TED already in RETURN_REQUESTED or RETURNED.

On RETURN, if the STR refuses the return, or the request is malformed or cannot be sent, the response is 422 TED-1011: no money left, and the TED goes to MANUAL_REVIEW with reviewReason=RETURN_REFUSED_BY_STR or RETURN_REQUEST_MALFORMED. The detail says if the review is already recorded. If the record fails, the TED stays in RETURN_REQUESTED until the routine for stuck TEDs moves it to the review. If the answer of the STR is unknown, the response is 503 TED-1010: the return stays requested and is reconciled or sent to manual review. On CREDIT, if the ledger refuses, the response is 422 TED-1001 and nothing changes. If the ledger outcome is unknown, the response is 503 TED-1000 and the TED stays in manual review.

POST /v1/incoming-transfers/{incomingTransferId}/resolve-review

cURL

confirm-credited

curl --request POST \
  --url https://api.example.com/v1/incoming-transfers/{incomingTransferId}/resolve-review \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "action": "CONFIRM_CREDITED",
  "evidence": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "justification": "Credit posted manually in the ledger after an incident."
}
'

200

{
  "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": "12345678909",
    "name": "Maria da Silva"
  },
  "slaDeadlineAt": "2026-10-22T15:10:03Z",
  "status": "CREDITED",
  "updatedAt": "2026-10-22T14:10:09Z"
}

Authorizations

Authorization · string · header · required

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.

Headers

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.

Required range: x >= 1

X-Idempotency · string · required

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.

Path Parameters

incomingTransferId · string<uuid> · required

Identifier of the incoming TED

Body

application/json

Operator decision on an incoming TED in manual review: credit it, return it, or record a credit already applied in the ledger.

action · enum<string> · required

CREDIT makes the credit; RETURN returns (requires returnCode); CONFIRM_CREDITED records a credit already confirmed in the ledger, with evidence.

Available options: CREDIT, RETURN, CONFIRM_CREDITED

justification · string · required

Operator justification.

Required string length: 10 - 500

accountId · string<uuid>

Destination account when the operator resolves the location (usually with action=CREDIT).

evidence · string

Required when action=CONFIRM_CREDITED: the identifier (UUID) of the Midaz transaction for the credit already applied (TED-0065 if missing or invalid).

Maximum string length: 64

returnCode · string

Required when action=RETURN (TED-0066 if absent); not allowed in the other actions.

Pattern: ^[0-9]{1,2}$

Example:

"3"

Response

200

application/json

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.

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. The timeline keeps the history of reasons.

amount · string · required

Amount in BRL as a decimal string with two decimal places.

Pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$

Example:

"1500.00"

createdAt · string<date-time> · required

Time (UTC) when this service recorded the TED.

incomingTransferId · string<uuid> · required

Identifier of the incoming TED. Use it in queries and actions.

interbankSettledAt · string<date-time> · required

Interbank settlement reported by the STR (start of the 60-min deadline)

nuop · string · required

Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7])

Pattern: ^[0-9]{23}$

recipient · object · required

Recipient in your own institution; accountId is present when the account was found.

Show child attributes

sender · object · required

Sender, at another institution.

Show child attributes

slaDeadlineAt · string<date-time> · required

Regulatory deadline to credit or return: interbankSettledAt + 60 min (UTC).

status · enum<string> · required

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.

Available options: RECEIVED, CREDITED, RECORDED, RETURN_REQUESTED, RETURNED, MANUAL_REVIEW

updatedAt · string<date-time> · required

Timestamp (UTC) of the last update to the record.

creditedAmount · string

Amount actually credited to the recipient (amount − feeAmount), in BRL. Present from CREDITED onward.

Pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$

Example:

"1500.00"

creditedAt · string<date-time>

Time (UTC) of the credit to the recipient.

description · string

Description given by the sender.

feeAmount · string

Fee applied to the credit, in BRL (0.00 when exempt).

Pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$

Example:

"0.00"

kind · enum<string>

Credit to a customer or to the institution's own account

Available options: CLIENT, INSTITUTION

numCtrlStr · string

Control number of the credit assigned by the STR (NumCtrlSTR of the R2 message, 20 alphanumeric characters). It can be absent: the rail did not send the number, or sent a value that is not 20 alphanumeric characters. Correlate by nuop in that case.

Pattern: ^[A-Za-z0-9]{20}$

organizationId · string<uuid>

Organization resolved through the ISPB→organization binding

purposeCode · string

Purpose code sent by the sender (FinlddCli, 5 digits).

Pattern: ^[0-9]{5}$

Example:

"00010"

returnCode · string

Official return reason (CodDevTransf) of the active return, when there is one.

Pattern: ^[0-9]{1,2}$

Example:

"3"

returnedAt · string<date-time>

Instant (UTC) when the STR confirmed the return.

reviewReason · string

Reason for the manual review. Present only when status=MANUAL_REVIEW; the timeline keeps the history of reasons. 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. From the reversal that an operator requested: LEDGER_REVERT_REFUSED (the ledger refused the reversal; the credit was kept) and LEDGER_REVERT_INDETERMINATE (the outcome of the reversal is unknown; the credit may be reversed).