Assess Transactions
The canonical assessment request, response, and decision handling.
Call POST /risk-engine/assess from your backend before it commits the payment, order, or account action.
/risk-engine/assessReal-time risk decision
Requires a bearer token, an active subscription, and events:assess permission.
Canonical request
curl -X POST "$VERTEXY_API_BASE_URL/risk-engine/assess" \
-H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "ord_10492",
"userId": "usr_8f7b2c9a4d",
"email": "buyer@example.com",
"ipAddress": "203.0.113.42",
"deviceFingerprint": "dev_iphone_15_7ac9",
"paymentMethodHash": "pmh_visa_44e9",
"amountMinor": 12999,
"currency": "USD",
"billingAddress": { "country": "US", "postalCode": "10001" },
"cardDetails": {
"bin": "411111",
"last4": "1111",
"network": "visa",
"issuingCountry": "US",
"cardType": "credit"
},
"deviceMeta": { "timezone": "America/New_York" }
}'Use stable user, device, and payment identifiers. See Objects and Dictionary for optional and regional fields.
Response
{
"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
}Handle the decision
| action | Typical handling |
| --- | --- |
| allow | Continue the workflow. |
| review | Hold, step up verification, or create an analyst review. |
| block | Stop the sensitive action. |
Persist assessmentId, transactionId, score, action, and reason codes with your record. Submit the final outcome using the Feedback Loop.
Interpret scoring in Risk Scores, configure enforcement in Policy Modes, and use the canonical error reference.