Apply the antifraud partner's final decision to a received TED in analysis

Applies the antifraud partner’s final decision to a received TED that the partner left in analysis (status=MANUAL_REVIEW, reviewReason=FRAUD_REVIEW). The caller is the client’s integration, with the editor role. The client’s operator resolves a review with resolve-review instead and cannot call this route.

The body is {"analysisId", "decision", "reasons"}: decision is ALLOW or DENY, and analysisId is the id the partner received with its REVIEW. A malformed reasons is dropped and the decision still applies; valid reasons are recorded on the check, replacing the ones the evaluation recorded (the score stays the evaluation’s), and appear in the events and the read API; the body is at most 16 KiB.

Decision	Result
ALLOW, before fraudCheck.decideBy	The TED is credited to the recipient account; the response is the CREDITED incoming TED.
DENY, before fraudCheck.decideBy	The TED is returned to the sender with CodDevTransf 9, whether or not the tenant enabled the automatic return.

409 TED-0060 is final, do not repeat: the incoming TED is not waiting on this analysis, the analysisId differs, another decision is already recorded, fraudCheck.decideBy has passed, or the desk already tried to credit it and a DENY could return money already paid.

503 is temporary, repeat with the same X-Idempotency: TED-0053 when the decision arrived before the analysis was recorded, or when the same key is still processing (never 409); TED-9002 when the audit trail cannot record the decision; TED-1000 or TED-0080 when the effect did not complete, in which case the decision stays recorded and the repetition finishes it. Every 503 carries Retry-After.

X-Idempotency is required and must be <analysisId>:<decision>; X-Idempotency-Replayed: true indicates a replay.

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

cURL

allow

curl --request POST \
  --url https://api.example.com/v1/incoming-transfers/{incomingTransferId}/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "analysisId": "an-7f3c91",
  "decision": "ALLOW"
}
'

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",
  "ledgerCreditId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "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"
}

Autorizaciones

Authorization · string · header · requerido

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.

Encabezados

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.

Rango requerido: x >= 1

X-Idempotency · string · requerido

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.

Parámetros de ruta

incomingTransferId · string<uuid> · requerido

Identifier of the incoming TED

Cuerpo

application/json

analysisId · string · requerido

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> · requerido

The final decision.

Opciones disponibles: 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.

Respuesta

200

application/json

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 · requerido

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})$

Ejemplo:

"1500.00"

createdAt · string<date-time> · requerido

Time (UTC) when this service recorded the TED.

incomingTransferId · string<uuid> · requerido

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

interbankSettledAt · string<date-time> · requerido

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

nuop · string · requerido

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

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

recipient · object · requerido

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

Show child attributes

sender · object · requerido

Sender, at another institution.

Show child attributes

slaDeadlineAt · string<date-time> · requerido

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

status · enum<string> · requerido

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.

Opciones disponibles: RECEIVED, CREDITED, RECORDED, RETURN_REQUESTED, RETURNED, MANUAL_REVIEW

updatedAt · string<date-time> · requerido

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}$

Ejemplo:

"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}$

Ejemplo:

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

Show child attributes

kind · enum<string>

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

Opciones disponibles: 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}$

Ejemplo:

"00010"

returnCode · string

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

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

Ejemplo:

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