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

Applies the antifraud partner’s final decision to a transfer that the partner left in analysis (status=FRAUD_ANALYSIS). The caller is the client’s integration, with the editor role.

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
DENY	Accepted at any time while the transfer is in analysis: REJECTED with TED-0050, the hold is cancelled and the limit returned.
ALLOW on a TED, before the analysis deadline and inside the operating window	Sent to the STR; the response carries the new status.
ALLOW on a TED with the window closed	Refused like a DENY, with TED-0020 or TED-0021. If the window cannot be determined: 503 TED-0022, nothing written.
ALLOW on an internal transfer	Records that side; once every evaluated side is allowed, the transfer is SETTLED.

409 TED-0060 is final, do not repeat: the transfer already left the analysis, the analysisId matches no open check, the check is already resolved, the transfer is already on its way to the STR, or an ALLOW arrived after the analysis deadline.

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. Every 503 carries Retry-After.

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

POST /v1/transfers/{transferId}/fraud-analysis/resolve

cURL

allow

curl --request POST \
  --url https://api.example.com/v1/transfers/{transferId}/fraud-analysis/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",
  "clientReference": "PED-2026-000123",
  "createdAt": "2026-10-22T13:05:12Z",
  "description": "Supplier payment",
  "feeAmount": "3.25",
  "metadata": {
    "channel": "mobile",
    "orderId": "PED-2026-000123"
  },
  "purposeCode": "00010",
  "recipient": {
    "agency": "1234",
    "bankAccount": "0001234567",
    "bankAccountType": "CACC",
    "bankCode": "001",
    "bankId": "87654321",
    "document": "12345678909",
    "name": "Maria da Silva"
  },
  "reservedAt": "2026-10-22T13:05:13Z",
  "sender": {
    "accountId": "0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b",
    "agency": "0001",
    "bankAccount": "0001111222",
    "bankAccountType": "CACC",
    "bankId": "12345678",
    "document": "98765432100",
    "name": "João Pereira"
  },
  "status": "SUBMITTED",
  "totalAmount": "1503.25",
  "transferId": "6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b",
  "type": "TED",
  "updatedAt": "2026-10-22T13:06:02Z"
}

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

transferId · string<uuid> · requerido

Transfer identifier

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; status is the transfer's new state. If X-Idempotency-Replayed: true, this is the replay of an earlier decision.

Representation of an outgoing (TED) or internal transfer. The create, query, and list operations return it, and so do the cancel and unblock actions. Track the lifecycle through the status field and the instants reservedAt/submittedAt/settledAt. When status=REJECTED, rejection tells you who refused it and why.

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

feeAmount · string · requerido

Fee, in BRL. After the hold, or after the settlement of an internal transfer, it is the fee that Midaz charged the sender. Before that, it is the estimate.

Pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$

Ejemplo:

"0.00"

purposeCode · string · requerido

Purpose code given in the send request (FinlddCli, 5 digits).

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

Ejemplo:

"00001"

recipient · object · requerido

Recipient sent when the transfer was created. In an internal transfer it includes accountId.

Show child attributes

sender · object · requerido

Source account, always in your own institution (includes accountId).

Show child attributes

status · string · requerido

Current state (published as a free string: handle unknown values with tolerance). Current values: CREATED, RESERVED, SUBMITTED, PENDING_STR, SETTLED, REJECTED, CANCELLED, AWAITING_RECONCILIATION, EXHAUSTED, FRAUD_ANALYSIS. TED: CREATED → RESERVED (amount + fee on hold) → SUBMITTED (sent to the STR) → SETTLED | REJECTED; PENDING_STR when the STR keeps the entry pending; AWAITING_RECONCILIATION and EXHAUSTED when the outcome could not be confirmed automatically; CANCELLED on a cancellation before submission or of a confirmed pending entry; RESERVED → FRAUD_ANALYSIS when the antifraud partner asks for a review (the hold stays), then SUBMITTED, REJECTED or CANCELLED. INTERNAL: CREATED → SETTLED | REJECTED in the same call, or it stays CREATED when the ledger response was undetermined (the reconciliation worker resolves it); CREATED → FRAUD_ANALYSIS when the antifraud partner asks for a review (the payer's amount is held at the ledger), then SETTLED, REJECTED or CANCELLED. Terminal: SETTLED, REJECTED, CANCELLED.

totalAmount · string · requerido

Amount + fee: the total debited (on hold) from the source account, in BRL.

Pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$

Ejemplo:

"1500.00"

transferId · string<uuid> · requerido

Transfer identifier. Use it in queries and actions.

type · enum<string> · requerido

TED (another institution, through the STR) or INTERNAL (same institution, settled in the ledger).

Opciones disponibles: TED, INTERNAL

updatedAt · string<date-time> · requerido

Time (UTC) of the last write to the record. This is not always a status change. ⚠️ An INTERNAL transfer can stay in CREATED because the ledger response was undetermined. In that case, the reprocessor uses updatedAt as the queue position on each new attempt, and it moves a transfer whose resend window expired one hour ahead: updatedAt CAN BE IN THE FUTURE (up to 1 h after the current time). Do not use it as a transition time.

clientReference · string

Requester reference sent with the transfer request.

Maximum string length: 64

description · string

Description given in the send request.

Maximum string length: 140

fraudCheck · object | null

Antifraud analysis of the transfer: the deadline and one check per antifraud flow enabled when it was created. null when it was created with every antifraud flow off. While status=FRAUD_ANALYSIS the analysis runs until the partner decides, you cancel or decideBy passes. A TED's amount is already held; an INTERNAL transfer's payer amount is held at the ledger right after entering the analysis, and a ledger refusal (insufficient balance) can still reject it.

Show child attributes

metadata · object

Free-form key-value pairs from the requester, kept verbatim. Never sent to the STR. Sent to the client's antifraud partner when the client turns an antifraud flow on.

Show child attributes

numCtrlStr · string

Identifier of the entry assigned by the STR (20 characters, XXXAAAAMMDDnnnnnnnnn), present after the STR settles the entry. It can be absent even with status=SETTLED, on a TED settled by reconciliation when the rail query does not give the number. Correlate by nuop in that case. A settlement fact that arrives later fills the field.

Pattern: ^[A-Za-z0-9]{20}$

nuop · string

SPB identifier of the operation, 23 digits. It can be absent even in status=SUBMITTED. In that case, correlate by railOperationId.

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

railOperationId · string<uuid>

Identifier of the operation in the rail (after acceptance).

rejection · object

Present only when status=REJECTED.

Show child attributes

reservedAt · string<date-time>

Instant (UTC) when the amount and fee were put on hold in the source account. Start of the 30-min regulatory deadline for submission.

returned · object

Return received for this outgoing TED (credit back to the sender). Requires status=SETTLED and a LATER return from the recipient institution. For this reason it never appears in the creation response or in the list items, only in GET /v1/transfers/{transferId}.

Show child attributes

settledAt · string<date-time>

Instant of settlement. Exists only from status=SETTLED.

submittedAt · string<date-time>

Timestamp (UTC) when the rail accepted the TED for sending to the STR.