> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudeg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/transactions/score — Score Transaction Risk

> POST /v1/transactions/score — submit transaction details and receive a real-time risk score, decision, and fraud signals within milliseconds.

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

```http theme={null}
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

<ParamField body="amount" type="integer" required>
  Transaction amount in the smallest currency unit (e.g., `1999` for \$19.99 USD). Must be a positive integer.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`).
</ParamField>

<ParamField body="payment_method" type="object" required>
  Payment method details for this transaction.

  <Expandable title="payment_method fields">
    <ParamField body="type" type="string" required>
      Payment method type. Accepted values: `card`, `wallet`, `bank_transfer`, `qr`, `crypto`.
    </ParamField>

    <ParamField body="card_bin" type="string">
      First 6–8 digits of the card number (Bank Identification Number). Enables BIN-level risk signals.
    </ParamField>

    <ParamField body="last_four" type="string">
      Last 4 digits of the card number. Used for card fingerprinting and velocity checks.
    </ParamField>

    <ParamField body="expiry_month" type="integer">
      Card expiry month as an integer between `1` and `12`.
    </ParamField>

    <ParamField body="expiry_year" type="integer">
      Card expiry year as a 4-digit integer (e.g., `2027`).
    </ParamField>

    <ParamField body="wallet_type" type="string">
      Required when `type` is `wallet`. Accepted values: `apple_pay`, `google_pay`, `paypal`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="user" type="object" required>
  Information about the user initiating the transaction.

  <Expandable title="user fields">
    <ParamField body="id" type="string" required>
      Your internal user ID. FraudEG uses this to build a behavioral profile over time.
    </ParamField>

    <ParamField body="email" type="string">
      User's email address. Used for email reputation and cross-merchant signals.
    </ParamField>

    <ParamField body="ip_address" type="string">
      User's IP address at the time of the transaction. Used for geolocation and proxy detection.
    </ParamField>

    <ParamField body="phone" type="string">
      User's phone number in E.164 format (e.g., `"+14155552671"`). Used for phone reputation checks.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="merchant" type="object">
  Optional merchant context. Providing this enables merchant-specific velocity and policy rules.

  <Expandable title="merchant fields">
    <ParamField body="id" type="string">
      Your internal merchant ID for marketplace or multi-merchant platforms.
    </ParamField>

    <ParamField body="category" type="string">
      Merchant category describing the type of goods or services (e.g., `"electronics"`, `"travel"`, `"gaming"`). Used to apply category-specific fraud models.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="session_id" type="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.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs you want to store and retrieve alongside this transaction. Not used in scoring. Values must be strings.
</ParamField>

<ParamField body="idempotency_key" type="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.
</ParamField>

## Response Fields

<ResponseField name="transaction_id" type="string">
  Unique FraudEG identifier for this transaction risk assessment. Use this ID to submit a decision via `POST /v1/decisions`.
</ResponseField>

<ResponseField name="risk_score" type="integer">
  Integer risk score from `0` (no risk) to `100` (highest risk). Your dashboard lets you configure decision thresholds per score band.
</ResponseField>

<ResponseField name="decision" type="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.
</ResponseField>

<ResponseField name="signals" type="array">
  List of risk signal objects that contributed to the score. Inspect these to understand why a score was returned.

  <Expandable title="signal object fields">
    <ResponseField name="name" type="string">
      Signal identifier (e.g., `device_trusted`, `velocity_high`, `ip_proxy_detected`, `bin_prepaid`).
    </ResponseField>

    <ResponseField name="weight" type="string">
      Signal contribution to the overall risk score. One of `low_risk`, `medium_risk`, or `high_risk`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="latency_ms" type="integer">
  Time in milliseconds FraudEG took to process the request server-side. Does not include network round-trip time.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the risk assessment was created (e.g., `"2024-11-15T10:32:00Z"`).
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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'
  // }
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "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"
}
```

<Note>
  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.
</Note>