Skip to main content
POST

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

Required: <analysisId>:<decision>, for example an-7f3c91:ALLOW. Repeat a 5xx with the SAME key and the SAME body, byte for byte. Same key + same body returns the original response with X-Idempotency-Replayed: true. Same key + different body responds 422 TED-0012. Same key still in processing responds 503 TED-0053 with Retry-After, never 409. 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
analysisId
string
required

The analysis id the partner received with its REVIEW: 1 to 64 printable ASCII characters, no space.

Required string length: 1 - 64
decision
enum<string>
required

The final decision.

Available options:
ALLOW,
DENY
reasons
object[]

Optional. A malformed entry is dropped and the decision still applies; the reasons sent replace the evaluation's on the check, an empty or omitted list included.

Response

Decision applied: CREDITED for ALLOW, RETURN_REQUESTED for DENY. If X-Idempotency-Replayed: true, this is the replay of an earlier decision.

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; outside MANUAL_REVIEW the reviewReason is not emitted, and the history of reasons is on the timeline. ledgerCreditId and ledgerRevertId identify the ledger transactions of the credit and of its reversal, when they exist; ledgerCreditId is the evidence CONFIRM_CREDITED expects for a credit already on file.

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"

fraudCheck
object | null

The antifraud partner's recorded answer, as one check with flow IN under decideBy. The key is always present: null while no answer is recorded.

kind
enum<string>

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

Available options:
CLIENT,
INSTITUTION
ledgerCreditId
string<uuid>

Identifier of the ledger (Midaz) transaction that credited the recipient. Present once a credit is on file (CREDITED, RETURN_REQUESTED, RETURNED, and a MANUAL_REVIEW that holds one); it is the evidence CONFIRM_CREDITED expects when a credit is already on file.

ledgerRevertId
string<uuid>

Identifier of the ledger (Midaz) transaction that reversed the credit for a return, when one was applied.

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 antifraud check: FRAUD_REVIEW (the partner asked for a human review), FRAUD_CHECK_UNAVAILABLE (the partner could not answer; the outcome is unknown) and FRAUD_DENIED (the partner denied it; the TED is returned with code 9). 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).