> ## 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.

# Prevent Payment Fraud with Real-Time Risk Scoring API

> Learn how to integrate FraudEG to score transactions, detect card fraud, and automate allow, challenge, and block decisions across payment rails.

Payment fraud takes many forms — stolen card details used in card-not-present transactions, automated card testing attacks that probe your checkout with thousands of low-value charges, and synthetic payment identities assembled from leaked data. FraudEG intercepts each transaction before it reaches your payment processor, scores it against a real-time risk model, and returns a clear decision so your application can act immediately. The result is fewer fraudulent authorizations, lower chargeback rates, and a smoother experience for legitimate customers.

## How the integration works

Every transaction follows the same three-step pattern: **score → decide → act**. Before you authorize a payment with your processor, you send the transaction data to FraudEG. FraudEG evaluates device signals, behavioral data, velocity patterns, and identity intelligence, then returns a `decision` of `allow`, `challenge`, or `block`. Your application branches on that decision before touching your payment processor — this keeps fraudulent charges from ever reaching authorization.

## Supported payment rails

FraudEG supports risk scoring across all major payment surfaces:

* **Credit and debit cards** — card-present and card-not-present
* **Digital wallets** — Apple Pay, Google Pay, Samsung Pay
* **ACH and wire transfers** — bank-to-bank payment flows
* **QR payments** — merchant-presented and customer-presented codes
* **Cryptocurrency** — on-chain and custodial crypto payments

## Integration guide

<Steps>
  <Step title="Initialize a device session on your checkout page">
    Add the FraudEG JavaScript snippet to your checkout page as early as possible. This captures device fingerprint, browser signals, and behavioral data before the user submits the form.

    ```html theme={null}
    <script>
      (function(f,r,a,u,d,e,g){
        f['FraudEGObject']=d;
        f[d]=f[d]||function(){ (f[d].q=f[d].q||[]).push(arguments) };
        e=r.createElement(a); e.async=1;
        e.src='https://cdn.fraudeg.com/v1/sdk.js';
        g=r.getElementsByTagName(a)[0];
        g.parentNode.insertBefore(e,g);
      })(window,document,'script','','fraudeg');

      fraudeg('init', 'YOUR_PUBLIC_KEY');
      fraudeg('session', function(sessionId) {
        document.getElementById('fraudeg_session').value = sessionId;
      });
    </script>

    <!-- Hidden field to carry the session ID into your form submission -->
    <input type="hidden" id="fraudeg_session" name="fraudeg_session" />
    ```

    Store the returned `session_id` — you will include it in the scoring request.
  </Step>

  <Step title="Collect transaction data at form submission">
    When the user submits the checkout form, gather the fields required for scoring: payment method details, the authenticated user's profile, and the merchant context. Avoid passing full card numbers — use the BIN (first six digits) and last four digits only.
  </Step>

  <Step title="Call POST /v1/transactions/score before processing payment">
    Send the transaction payload to FraudEG **before** calling your payment processor. FraudEG evaluates the request synchronously and returns a decision, typically in under 100 ms.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.fraudeg.com/v1/transactions/score \
        -H "Authorization: Bearer $FRAUDEG_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": 12999,
          "currency": "USD",
          "payment_method": {
            "type": "credit_card",
            "card_bin": "411111",
            "last_four": "4242"
          },
          "user": {
            "id": "usr_8f3k2p",
            "email": "jane@example.com",
            "ip_address": "203.0.113.42"
          },
          "merchant": {
            "id": "mer_9z1x4q",
            "category": "electronics"
          },
          "session_id": "ses_7hk3mn29"
        }'
      ```

      ```javascript Node.js theme={null}
      async function scoreTransaction(txnData) {
        const response = await fetch('https://api.fraudeg.com/v1/transactions/score', {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${process.env.FRAUDEG_API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(txnData)
        });
        const result = await response.json();

        switch (result.decision) {
          case 'allow':
            return processPayment(txnData);
          case 'challenge':
            return triggerStepUpAuth(result.transaction_id);
          case 'block':
            return { error: 'Transaction declined', code: 'FRAUD_BLOCK' };
        }
      }
      ```
    </CodeGroup>

    **Request body fields:**

    | Field                      | Type    | Description                                                    |
    | -------------------------- | ------- | -------------------------------------------------------------- |
    | `amount`                   | integer | Transaction amount in the smallest currency unit (e.g., cents) |
    | `currency`                 | string  | ISO 4217 currency code                                         |
    | `payment_method.type`      | string  | `credit_card`, `debit_card`, `digital_wallet`, `ach`, `crypto` |
    | `payment_method.card_bin`  | string  | First six digits of the card number                            |
    | `payment_method.last_four` | string  | Last four digits of the card number                            |
    | `user.id`                  | string  | Your internal user identifier                                  |
    | `user.email`               | string  | User's email address                                           |
    | `user.ip_address`          | string  | Client IP address at time of transaction                       |
    | `merchant.id`              | string  | Your internal merchant identifier                              |
    | `merchant.category`        | string  | Merchant category (e.g., `electronics`, `travel`)              |
    | `session_id`               | string  | Session ID returned by the FraudEG JS SDK                      |

    **Example response:**

    ```json theme={null}
    {
      "transaction_id": "txn_4r8wq1zb",
      "risk_score": 82,
      "decision": "challenge",
      "signals": ["new_device", "ip_reputation_medium_risk", "velocity_burst"],
      "latency_ms": 74
    }
    ```
  </Step>

  <Step title="Branch on the decision field">
    Read `result.decision` and route the transaction accordingly:

    * **`allow`** — the transaction appears legitimate. Proceed directly to your payment processor to authorize the charge.
    * **`challenge`** — the transaction shows moderate risk signals. Trigger a step-up authentication flow such as 3D Secure (3DS) or a one-time passcode (OTP) before proceeding. Passing 3DS shifts liability to the card issuer if a chargeback occurs.
    * **`block`** — the transaction is high risk. Decline immediately and return an appropriate error to the user. Do not send the charge to your payment processor.
  </Step>

  <Step title="Log the transaction_id for dispute reference">
    Store the `transaction_id` returned in the scoring response alongside your internal order record. If a chargeback or dispute arises, this ID links directly to the immutable fraud evidence record FraudEG retained at the time of the transaction.
  </Step>
</Steps>

## Detecting card testing attacks

Card testing attacks involve an attacker submitting large volumes of small-value or zero-value charges to identify live card numbers before monetizing them elsewhere. FraudEG surfaces these patterns through the `velocity_burst` signal in the `signals` array.

When you see `velocity_burst` in a scoring response, treat it as a strong indicator that the card or device is involved in automated abuse. Consider automatically escalating `challenge` decisions to `block` for any transaction carrying this signal, and applying temporary rate limits at the IP or device level.

<Warning>
  Always call `POST /v1/transactions/score` **before** submitting the charge to your payment processor. Scoring a transaction after authorization provides no protection — the fraud has already occurred and you are liable for any resulting chargeback. Build the scoring call into your payment handler as a mandatory pre-authorization gate, not an optional logging step.
</Warning>

<Tip>
  Use the FraudEG sandbox environment (`https://sandbox.api.fraudeg.com/v1`) to simulate high-risk transactions during development. Send `"card_bin": "400000"` to trigger a `block` decision, `"card_bin": "400001"` to trigger a `challenge`, and any other test BIN to trigger `allow`. This lets you fully exercise all three decision branches without real payment data.
</Tip>