Skip to main content
POST
Request a full return of an incoming TED (operator)

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. The window sets how long the response is replayed.

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

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

​
sender
object
required

Sender, at another institution.

​
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

Entry identifier assigned by the STR (20 characters).

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