Sanctions Screening Guide

CROSSFX API · SANCTIONS SCREENING

Screening is built into the transaction flow.

CrossFX screens both beneficiaries and senders against global sanctions lists before a payment can proceed.

There is no separate screening endpoint to integrate. Screening runs automatically inside beneficiary creation and transfer confirmation.

Beneficiary screeningSender screeningMandatoryNo separate API

Where screening runs

Screening happens at two points in the API lifecycle, before CrossFX creates the resource that would allow the transaction to continue.

01 · BENEFICIARY

Create beneficiary

CrossFX screens the beneficiary identity before any beneficiary record is written.

SCREEN

→

02 · TRANSFER

Confirm transfer

CrossFX screens the sender identity before the transfer is created.

Beneficiary creation

Beneficiary screening

A high-confidence match means the beneficiary is not created.

There is no record to retry against and nothing to clean up.

Guide: Create Beneficiary Guide

Transfer confirmation

Sender screening

A high-confidence match means the transfer is not created and no funds move.

Guide: Confirm Transfer Guide

FAIL CLOSED

An unscreened payment does not proceed.

If the screening service cannot be reached, CrossFX refuses the operation with 503 SCREENING_UNAVAILABLE rather than allowing it through without screening.

What screening reads

Screening evaluates the identity fields already submitted in the beneficiary or transfer request.

Identity fields used for screening

MATCH ACCURACY

Include date_of_birth where you can.

Although optional in the schema, date_of_birth narrows identity matching and is the most effective field for reducing false positives.

Confidence scoring

CrossFX assigns a confidence score between 0.0 and 1.0 to the closest sanctions match it finds.

NO MATCH

Continue normally

The request proceeds and no screening block appears in the success response.

LOW CONFIDENCE

Continue normally

The call proceeds as normal and no screening fields appear in the response.

HIGH CONFIDENCE

422 SANCTIONS_HIT

The request is refused and the confidence score is returned so your application can log it.

There is no published threshold on this page for what constitutes high confidence. Handle the result returned by the API rather than reproducing the scoring logic in your application.

Screening responses

Screening passed

There is no separate screening object in a successful response.

PASS

Normal endpoint response

Treat the absence of an error as the screening pass. The endpoint returns its normal success body.

Sanctions hit

A high-confidence match returns:

422 SANCTIONS_HIT

The operation does not create the beneficiary or transfer.

Action: send the case to compliance review. Do not retry the same identity unchanged.

Screening unavailable

If the screening service cannot be reached, CrossFX returns:

{
  "error": "Sanctions screening service unavailable",
  "code": "SCREENING_UNAVAILABLE",
  "message": "Sanctions screening service unavailable",
  "error_id": "9c2e5b81-04af-4d16-8b73-52e1a9c4f608"
}

RETRYABLE

503 SCREENING_UNAVAILABLE

The screening service was unavailable and the operation had no effect. Retry with backoff.

Error handling

Both screening errors can be returned by Create Beneficiary and Confirm Transfer.

HTTP	`code`	Trigger	What you do
422	`SANCTIONS_HIT`	The submitted identity matched a sanctions list entry with high confidence	Send to compliance review. Do not retry the same identity.
503	`SCREENING_UNAVAILABLE`	The screening service could not be reached	Retry with backoff.

BRANCH ON CODE

SANCTIONS_HIT is not VALIDATION_FAILED.

Although SANCTIONS_HIT arrives with HTTP 422, its error value is a plain string rather than the nested field map used for validation errors. Branch on code, not HTTP status alone.

Where screening runs#

What screening reads#

Confidence scoring#

Screening responses#

Screening passed#

Sanctions hit#

Screening unavailable#

Error handling#