Request a full return of an incoming TED (operator)
Operator action that returns the full amount of an incoming TED that was already credited. The credit is reversed, and the return goes to the STR with the official reason in returnCode.
Applies only in CREDITED. In RECEIVED it responds 409 TED-0062 (the credit can be in progress). In MANUAL_REVIEW, 409 TED-0062: resolve it with POST .../resolve-review and action=RETURN. Returns are always for the full amount.
Returns 202 with status=RETURN_REQUESTED. The confirmation (RETURNED) arrives through a query or an event. Requires X-Idempotency and a justification.
Autorizações
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
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.
x >= 1Idempotency 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.
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
Identifier of the incoming TED
Corpo
Request for the full return of an incoming TED that is already credited, with the official reason (CodDevTransf) and the operator's justification.
Resposta
Return requested: the incoming TED moves to RETURN_REQUESTED. The confirmation (RETURNED) arrives through a query or an event. If X-Idempotency-Replayed: true, this is the replay of an earlier return.
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.
Amount in BRL as a decimal string with two decimal places.
^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$"1500.00"
Time (UTC) when this service recorded the TED.
Identifier of the incoming TED. Use it in queries and actions.
Interbank settlement reported by the STR (start of the 60-min deadline)
Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7])
^[0-9]{23}$Recipient in your own institution; accountId is present when the account was found.
Sender, at another institution.
Regulatory deadline to credit or return: interbankSettledAt + 60 min (UTC).
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.
RECEIVED, CREDITED, RECORDED, RETURN_REQUESTED, RETURNED, MANUAL_REVIEW Timestamp (UTC) of the last update to the record.
Amount actually credited to the recipient (amount − feeAmount), in BRL. Present from CREDITED onward.
^(0|[1-9][0-9]{0,11})\.[0-9]{2}$"1500.00"
Time (UTC) of the credit to the recipient.
Description given by the sender.
Fee applied to the credit, in BRL (0.00 when exempt).
^(0|[1-9][0-9]{0,11})\.[0-9]{2}$"0.00"
Credit to a customer or to the institution's own account
CLIENT, INSTITUTION Entry identifier assigned by the STR (20 characters).
^[A-Za-z0-9]{20}$Organization resolved through the ISPB→organization binding
Purpose code sent by the sender (FinlddCli, 5 digits).
^[0-9]{5}$"00010"
Official return reason (CodDevTransf) of the active return, when there is one.
^[0-9]{1,2}$"3"
Instant (UTC) when the STR confirmed the return.
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.