Submit a beneficiary screening decision

POST 
/v1/transfers/:transfer_id/screening-decisions

Approve, reject or extend a transfer that is waiting for beneficiary screening. Requires scope connector:transfers:screening-decide.

Who calls it, and when. Beneficiary screening applies to INTERBANK and BANK_ROUTED transfers when it is enabled on the network. After the sending bank's transfer passes liquidity selection, the transfer enters AWAITING_SCREENING and the receiving (beneficiary) bank is sent a beneficiary.screening.requested webhook. Only that receiving bank can decide; for any other caller the transfer is reported as not found (404). Nothing is written to the ledger until the transfer is approved.

Decisions.

• APPROVE: the transfer moves to PROCESSING and continues to the ledger (and then to the sending bank's checker review).
• REJECT: the transfer ends REJECTED; its operation gets result_code SCREENING_REJECTED. Nothing is written to the ledger.
• EXTEND: the transfer stays AWAITING_SCREENING and its deadline moves out by extend_ttl_seconds (default: one screening window). EXTEND is refused until the webhook delivery has been confirmed.

Screening window. The window (5 seconds by default; the length is network configuration) starts when the webhook is delivered to the receiving bank, not when the transfer was accepted. A decision is on time if it reaches the Lyriq Connector before the deadline; the time the platform then takes to apply it does not count. If no decision arrives in time the transfer ends EXPIRED (result_code SCREENING_EXPIRED). Extensions can never push the deadline beyond the screening ceiling (2 hours by default) measured from the moment the transfer entered screening. If the webhook cannot be delivered the transfer ends FAILED (SCREENING_UNDELIVERABLE, or SCREENING_NOT_STARTED when delivery is never confirmed).

Response. 202 Accepted returns a new operation for the decision itself (operation_type SCREENING_DECISION_CREATE, resource_family transfers); it has no relationships. The decision is applied asynchronously: that operation ends SUCCEEDED once the transfer has moved, or FAILED (for example result_code STATE_CONFLICT) if it could not be applied. Follow the transfer itself with GET /v1/transfers/{transfer_id}.

Idempotency. Idempotency-Key is required. The same key and body return the original 202; the same key with a different body returns 409 IDEMPOTENCY_CONFLICT.

Errors.

Status	code	When
400	(none)	extend_ttl_seconds sent with APPROVE or REJECT, or not positive; missing Idempotency-Key; the transfer is no longer AWAITING_SCREENING (title Transfer is no longer awaiting screening, current operation state is <STATE>, where a decision after the deadline reports EXPIRED); EXTEND before the window opened (title screening window has not opened yet, so it cannot be extended).
403	UNAUTHORIZED_SCOPE	The token lacks connector:transfers:screening-decide.
404	(none)	The transfer does not exist, or the calling bank is not its receiving bank (title resource not found).
409	IDEMPOTENCY_CONFLICT, IDEMPOTENCY_PENDING	Idempotency-Key reuse.
422	(none)	The body does not match the schema, for example an unknown decision (title Invalid request body).
503	OUTBOUND_HALTED, READ_ONLY, OPERATIONAL_STATE_UNKNOWN	The network is not fully operational; decisions are refused.

A duplicate or conflicting decision on a transfer that has already left AWAITING_SCREENING is rejected and leaves the transfer unchanged.

Request

Responses

202

Decision accepted. data is the operation that applies the decision; it has no relationships or links.

400

Invalid input, or the transfer is no longer awaiting screening. The reason is in title; these errors carry no code.

401

The bearer token is missing, malformed, expired, signed by an unknown key, or was not issued by the platform IAM for the Lyriq Connector. Obtain a new token and retry. See the Authentication section.

403

The token is valid but may not perform this request: it lacks the required scope, has no bank membership, needs an x-dan-bank-id header to choose between several memberships, names a bank in x-dan-bank-id it has no membership for, or the caller's bank is suspended or terminated. A new token with the same configuration fails the same way. See the Authentication section.

404

The transfer does not exist, or the calling bank is not its receiving bank.

409

The request conflicts with an earlier request or with the current state of the target: an Idempotency-Key reused with a different body (IDEMPOTENCY_CONFLICT), a request with the same key still in progress (IDEMPOTENCY_PENDING), or a target resource in a state that does not allow the request (STATE_CONFLICT).

422

The request is well-formed JSON but cannot be processed: the body does not match the expected shape (a missing or unknown member, a wrong type, or a wrong data.type), or it breaks a business or cross-field rule. Correct the request before retrying.

429

The request was refused because a rate limit was reached (code RATE_LIMITED). No Retry-After header is sent; retry with exponential backoff.

503

The request could not be served right now. Either the network is not fully operational (OUTBOUND_HALTED or READ_ONLY: mutations are refused while read endpoints keep working; OPERATIONAL_STATE_UNKNOWN: the state could not be determined), or a platform dependency is temporarily unavailable. No Retry-After header is sent; retry later with backoff. When retrying a mutation, reuse the same Idempotency-Key and body.