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.

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 return is already in place, responds 409 TED-0060. The response is 409 TED-0060, whatever the returnCode, when an active return is already sent to the STR, already reversed, AUTOMATIC, or RETURNED. The action is already applied and no new 202 is emitted.

If the STR refuses the return, or the request is malformed or cannot be sent, the response is 422 TED-1011. The reversal is already done: the credit of the customer was reversed, no money left the institution, 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. If the ledger refuses the reversal, the response is 422 TED-1001: the credit is kept and the TED goes to MANUAL_REVIEW. If that record fails, the TED stays in RETURN_REQUESTED and the return can resume. If the ledger outcome is unknown, the response is 503 TED-1000.

POST /v1/incoming-transfers/{incomingTransferId}/return

Request a full return of an incoming TED (operator)

cURL

curl --request POST \
  --url https://api.example.com/v1/incoming-transfers/{incomingTransferId}/return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "justification": "The account holder does not match the recipient sent.",
  "returnCode": "5"
}
'

202

{
  "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"
  },
  "returnCode": "5",
  "sender": {
    "agency": "1234",
    "bankAccount": "0001234567",
    "bankAccountType": "CACC",
    "bankId": "87654321",
    "document": "12345678909",
    "name": "Maria da Silva"
  },
  "slaDeadlineAt": "2026-10-22T15:10:03Z",
  "status": "RETURN_REQUESTED",
  "updatedAt": "2026-10-22T16:20:00Z"
}

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

Request for the full return of an incoming TED that is already credited, with the official reason (CodDevTransf) and the operator's justification.

justification · string · required

Operator justification.

Required string length: 10 - 500

returnCode · string · required

Official return reason (CodDevTransf, SFN Domain Dictionary).

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

Example:

"3"

Response

202

application/json

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