Assess a Transaction

Use VertexY to score a transaction in real time before you approve it.

When to call /risk-engine/assess

Call POST /risk-engine/assess immediately before:

  • authorizing a payment
  • confirming an order
  • completing an account action with fraud risk

The endpoint returns a decision payload in a single round trip.

Minimal request

bash
curl -X POST https://api.vertexY.com/api/risk-engine/assess \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_100001",
    "userId": "user_123",
    "amountMinor": 4999,
    "currency": "USD"
  }'

Recommended enriched request

json
{
  "transactionId": "txn_100001",
  "userId": "user_123",
  "email": "buyer@example.com",
  "ipAddress": "203.0.113.10",
  "deviceFingerprint": "device_abc_001",
  "phoneNumber": "+14155550123",
  "paymentMethodHash": "pm_hash_001",
  "shippingAddressHash": "addr_hash_001",
  "amountMinor": 4999,
  "currency": "USD",
  "scoringProfile": "default",
  "metadata": {
    "orderId": "order_100001",
    "channel": "web",
    "couponCode": "SUMMER10"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "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"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.006
  }
}

Response shape

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,
    "contextual_score": 61
  },
  "engineVersion": "v2",
  "latencyMs": 38
}

How to act on the response

  • allow: risk is acceptable. Most clients continue the workflow immediately.
  • review: risk is elevated but not fully decisive. Hold the transaction for analyst review or step-up verification.
  • block: risk is too high. Stop the workflow and do not complete the action.

Store these values

Always persist:

  • assessmentId
  • transactionId
  • riskScore
  • action
  • reasonCodes

You will need assessmentId or transactionId later for:

  • outcome feedback
  • reviews
  • graph exploration

Validation rules

Required:

  • transactionId
  • userId
  • amountMinor
  • currency

Important format rules:

  • currency must be a 3-letter uppercase code such as USD
  • amountMinor must be a non-negative integer
  • cardDetails.last4 must be exactly 4 digits if provided

Limits and billing behavior

  • This endpoint requires a valid bearer token.
  • It also requires an active subscription.
  • Usage is counted against your plan’s fraud_events_ingested allowance.
  • If you exceed your plan’s hard limit, the API returns 402 Payment Required.

Best practices

  • Use stable transactionId values from your system.
  • Send the same identity fields on both assess and ingest when possible.
  • Include contextual data like BIN, geo, and device timezone for higher-quality decisions.
  • Submit feedback later so the score improves over time.

Related guides