Screen a transaction | UWAY Documentation

Endpoint

POST/v1/screen/transactionPrivate preview

Submit transaction, customer, counterparty, and Travel Rule context for a configured screening decision. The fields enabled for a tenant depend on the implementation contract.

Request

curl -X POST "https://TENANT_BASE_URL/v1/screen/transaction" \
  -H "Authorization: Bearer YOUR_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn_8f72b1c4e5d9" \
  -d '{
    "transaction_id": "txn_8f72b1c4e5d9",
    "sender": {"id": "cus_sender_01", "entity_type": "individual"},
    "recipient": {"id": "cus_recipient_01", "entity_type": "individual"},
    "amount": {"value": "50000.00", "currency": "USDT"},
    "network": "ethereum",
    "travel_rule": {"required": true}
  }'

Request fields

Field	Type	Requirement	Purpose
transaction_id	string	Required	Stable business identifier used across decisions and evidence
sender	object	Required	Originating party reference and permitted context
recipient	object	Required	Beneficiary or counterparty reference and permitted context
amount	object	Required	Decimal value as a string plus asset or currency
network	string	Conditional	Network or rail used by the transaction
travel_rule	object	Conditional	Applicability and exchange context

Example response

{
  "transaction_id": "txn_8f72b1c4e5d9",
  "uway_reference": "scr_7d3a91c2",
  "status": "review",
  "risk_level": "medium",
  "reason_codes": ["COUNTERPARTY_CONTEXT_REQUIRED"],
  "evidence_refs": ["ev_14f2"],
  "policy_version": "tenant-policy-2026-08"
}

Handling the response

Persist the business identifier, UWAY reference, status, reason codes, evidence references, and policy version before taking an irreversible action. A synchronous response may be followed by a webhook if analyst review or partner exchange changes the case.

Failure handling

Retry network timeouts with the same idempotency key.
Do not treat an HTTP or parsing failure as an approved transaction.
Route unavailable or incomplete decisions according to the institution's degraded-service policy.
Preserve the error code and correlation reference for support and audit.