engineer
Assess Transactions
Score a payment, order, or account action before your system commits it.
Reviewed 2026-06-21Product 1.1
Call POST /risk-engine/assess at the point where your backend still has time to allow, step up, hold, or block the workflow.
POST
/risk-engine/assessReal-time risk decision
Requires a bearer access token and an active subscription. The request is tenant-scoped from the authenticated user.
Minimal request
bash
curl -X POST "$VERTEXY_API_BASE_URL/risk-engine/assess" \
-H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "ord_sg_77812",
"userId": "usr_8f7b2c9a4d",
"amountMinor": 8490,
"currency": "SGD"
}'Use the minimal request only for early smoke tests. Production scoring works best when you include stable identity, payment, device, and location context.
Production request examples
US card-not-present checkout
json
{
"transactionId": "ord_us_10492",
"userId": "usr_8f7b2c9a4d",
"email": "buyer@example.com",
"ipAddress": "203.0.113.42",
"deviceFingerprint": "dev_iphone_15_7ac9",
"paymentMethodHash": "pmh_visa_44e9",
"shippingAddressHash": "addr_us_ny_9221",
"amountMinor": 12999,
"currency": "USD",
"metadata": {
"orderId": "ord_us_10492",
"channel": "web",
"couponCode": "WELCOME20"
},
"billingAddress": {
"country": "US",
"postalCode": "10001",
"city": "New York"
},
"cardDetails": {
"bin": "411111",
"last4": "1111",
"network": "visa",
"issuingCountry": "US",
"cardType": "credit"
},
"deviceMeta": {
"os": "iOS",
"browser": "Mobile Safari",
"language": "en-US",
"timezone": "America/New_York"
}
}Europe PSD2 checkout
json
{
"transactionId": "ord_eu_66210",
"userId": "usr_eu_7b2aa91",
"email": "shopper@example.eu",
"ipAddress": "198.51.100.18",
"deviceFingerprint": "dev_web_berlin_4411",
"paymentMethodHash": "pmh_mastercard_8cd2",
"amountMinor": 8890,
"currency": "EUR",
"metadata": {
"orderId": "ord_eu_66210",
"market": "de",
"threeDsResult": "challenged"
},
"billingAddress": {
"country": "DE",
"postalCode": "10115",
"city": "Berlin"
},
"cardDetails": {
"bin": "555555",
"last4": "4444",
"network": "mastercard",
"issuingCountry": "DE",
"cardType": "debit"
}
}Southeast Asia mobile-wallet checkout
json
{
"transactionId": "ord_sg_77812",
"userId": "usr_sea_2190ab",
"email": "customer@example.sg",
"ipAddress": "203.0.113.88",
"deviceFingerprint": "dev_android_sg_38ca",
"paymentMethodHash": "wallet_grabpay_3f91",
"amountMinor": 8490,
"currency": "SGD",
"metadata": {
"orderId": "ord_sg_77812",
"channel": "mobile_app",
"walletProvider": "grabpay"
},
"billingAddress": {
"country": "SG",
"postalCode": "018956",
"city": "Singapore"
},
"deviceMeta": {
"os": "Android",
"browser": "In-app WebView",
"language": "en-SG",
"timezone": "Asia/Singapore"
}
}Response
201Review decision
json
{
"assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
"riskScore": 72,
"action": "review",
"recommendedAction": "review",
"policyMode": "hybrid",
"riskLevel": "high",
"reasonCodes": [
"GLOBAL_INDICATOR_MATCH",
"VELOCITY_ZSCORE_SPIKE"
],
"featureContributions": {
"velocity_zscore": 3.8,
"indicator_overlap_ratio": 0.33,
"graph_neighbor_ratio_n2": 0.25
},
"engineVersion": "v2",
"latencyMs": 38
}Decision handling
allow: continue the workflow immediately.review: hold the action, step up verification, or open an analyst review.block: stop the workflow and do not complete the payment or sensitive action.
Fields to store
Persist assessmentId, transactionId, riskScore, action, and reasonCodes with your order or account event. You need these values for feedback, review queues, graph exploration, audit trails, and support investigations.
Common errors
401 Unauthorized: access token is missing or expired.402 Payment Required: plan is inactive or usage is over the hard limit.403 Forbidden: caller lacks the required permission.422 Unprocessable Entity: request validation failed.