POST /v1/transactions/score — Score Transaction Risk

Submit transaction details to FraudEG and receive an instant risk score, a recommended decision, and a set of human-readable fraud signals. The scoring engine evaluates device intelligence, behavioral patterns, payment method reputation, and velocity signals to return a result typically within 50 ms — without adding friction to your checkout flow.

Endpoint

POST https://api.fraudeg.com/v1/transactions/score

Request Headers

Header	Value	Required
`Authorization`	`Bearer <API_KEY>`	Yes
`Content-Type`	`application/json`	Yes
`Idempotency-Key`	Unique string for safe retries	No

Request Body

integer

required

Transaction amount in the smallest currency unit (e.g., 1999 for $19.99 USD). Must be a positive integer.

string

required

ISO 4217 currency code (e.g., "USD", "EUR", "GBP").

object

required

Payment method details for this transaction.

Show payment_method fields

string

required

Payment method type. Accepted values: card, wallet, bank_transfer, qr, crypto.

string

First 6–8 digits of the card number (Bank Identification Number). Enables BIN-level risk signals.

string

Last 4 digits of the card number. Used for card fingerprinting and velocity checks.

integer

Card expiry month as an integer between 1 and 12.

integer

Card expiry year as a 4-digit integer (e.g., 2027).

string

Required when type is wallet. Accepted values: apple_pay, google_pay, paypal.

object

required

Information about the user initiating the transaction.

Show user fields

string

required

Your internal user ID. FraudEG uses this to build a behavioral profile over time.

string

User’s email address. Used for email reputation and cross-merchant signals.

string

User’s IP address at the time of the transaction. Used for geolocation and proxy detection.

string

User’s phone number in E.164 format (e.g., "+14155552671"). Used for phone reputation checks.

object

Optional merchant context. Providing this enables merchant-specific velocity and policy rules.

Show merchant fields

string

Your internal merchant ID for marketplace or multi-merchant platforms.

string

Merchant category describing the type of goods or services (e.g., "electronics", "travel", "gaming"). Used to apply category-specific fraud models.

string

Device session ID obtained from POST /v1/device/session. Attaching a session ID unlocks device intelligence signals including device fingerprint, behavioral biometrics, and bot detection scores.

object

Arbitrary key-value pairs you want to store and retrieve alongside this transaction. Not used in scoring. Values must be strings.

string

A unique string you generate to safely retry this request without creating duplicate assessments. You can also pass this as the Idempotency-Key request header.

Response Fields

string

Unique FraudEG identifier for this transaction risk assessment. Use this ID to submit a decision via POST /v1/decisions.

integer

Integer risk score from 0 (no risk) to 100 (highest risk). Your dashboard lets you configure decision thresholds per score band.

string

Recommended action based on your configured policies. One of:

allow — Proceed with the transaction.
challenge — Apply step-up authentication (e.g., 3DS, OTP).
block — Decline the transaction.

array

List of risk signal objects that contributed to the score. Inspect these to understand why a score was returned.

Show signal object fields

string

Signal identifier (e.g., device_trusted, velocity_high, ip_proxy_detected, bin_prepaid).

string

Signal contribution to the overall risk score. One of low_risk, medium_risk, or high_risk.

integer

Time in milliseconds FraudEG took to process the request server-side. Does not include network round-trip time.

string

ISO 8601 timestamp of when the risk assessment was created (e.g., "2024-11-15T10:32:00Z").

Code Examples

curl --request POST \
  --url https://api.fraudeg.com/v1/transactions/score \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: txn_idem_abc123' \
  --data '{
    "amount": 4999,
    "currency": "USD",
    "payment_method": {
      "type": "card",
      "card_bin": "424242",
      "last_four": "4242",
      "expiry_month": 12,
      "expiry_year": 2027
    },
    "user": {
      "id": "usr_8f3kd92",
      "email": "jane@example.com",
      "ip_address": "203.0.113.42",
      "phone": "+14155552671"
    },
    "merchant": {
      "id": "mrc_7x1pq04",
      "category": "electronics"
    },
    "session_id": "sess_3hT9mKp2wZx",
    "metadata": {
      "order_id": "ord_982347",
      "platform": "web"
    },
    "idempotency_key": "txn_idem_abc123"
  }'

const response = await fetch('https://api.fraudeg.com/v1/transactions/score', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'txn_idem_abc123',
  },
  body: JSON.stringify({
    amount: 4999,
    currency: 'USD',
    payment_method: {
      type: 'card',
      card_bin: '424242',
      last_four: '4242',
      expiry_month: 12,
      expiry_year: 2027,
    },
    user: {
      id: 'usr_8f3kd92',
      email: 'jane@example.com',
      ip_address: '203.0.113.42',
      phone: '+14155552671',
    },
    merchant: {
      id: 'mrc_7x1pq04',
      category: 'electronics',
    },
    session_id: 'sess_3hT9mKp2wZx',
    metadata: {
      order_id: 'ord_982347',
      platform: 'web',
    },
    idempotency_key: 'txn_idem_abc123',
  }),
});

const data = await response.json();
console.log(data);
// {
//   transaction_id: 'txn_9kLmN3pQ7rS',
//   risk_score: 24,
//   decision: 'allow',
//   signals: [
//     { name: 'device_trusted', weight: 'low_risk' },
//     { name: 'email_seen_before', weight: 'low_risk' }
//   ],
//   latency_ms: 47,
//   created_at: '2024-11-15T10:32:00Z'
// }

Example Response

{
  "transaction_id": "txn_9kLmN3pQ7rS",
  "risk_score": 24,
  "decision": "allow",
  "signals": [
    { "name": "device_trusted", "weight": "low_risk" },
    { "name": "email_seen_before", "weight": "low_risk" }
  ],
  "latency_ms": 47,
  "created_at": "2024-11-15T10:32:00Z"
}

Use the Idempotency-Key header (or the idempotency_key body field) when retrying requests after a network timeout. FraudEG will return the original response for any duplicate request with the same key, preventing duplicate risk assessments for the same transaction.

Overview

Transactions

Identity

Monitoring

POST /v1/transactions/score — Score Transaction Risk

Endpoint

Request Headers

Request Body

Response Fields

Code Examples

Example Response

​Endpoint

​Request Headers

​Request Body

​Response Fields

​Code Examples

​Example Response

Endpoint

Request Headers

Request Body

Response Fields

Code Examples

Example Response