FraudEG Quickstart: Score Your First API Transaction

This guide walks you through everything you need to send your first transaction to FraudEG and interpret the response. By the end, you will have a working API call that returns a real-time risk score, a machine decision, and a set of explainable signals — the building blocks of every FraudEG integration.

Prerequisites

Before you begin, make sure you have:

A FraudEG account — sign up free if you don’t have one.
Your API key — you’ll retrieve this in Step 1 below.
A terminal or HTTP client to run cURL commands (or Node.js if you prefer the code examples).

Steps

Get your API key

Log in to the FraudEG dashboard, navigate to Settings → API Keys, and click Create new key. Give the key a descriptive label (for example, local-dev) and select the Test environment.Your new key will be shown once. Copy it and store it in a safe place — you will not be able to view it again. It will look like this:

feg_test_sk_a1b2c3d4e5f6g7h8i9j0

Set it as an environment variable so you don’t hard-code it in any file:

export FRAUDEG_API_KEY="feg_test_sk_a1b2c3d4e5f6g7h8i9j0"

Score your first transaction

Send a POST request to /v1/transactions/score with your transaction context. The request below represents a card payment of $150.00 from a known user, including device session and merchant details.

curl -X POST https://api.fraudeg.com/v1/transactions/score \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "USD",
    "payment_method": {
      "type": "card",
      "card_bin": "424242",
      "last_four": "4242",
      "expiry_month": 12,
      "expiry_year": 2027
    },
    "user": {
      "id": "usr_8f3k2p",
      "email": "buyer@example.com",
      "ip_address": "203.0.113.45"
    },
    "merchant": {
      "id": "mch_7x9qrt",
      "category": "electronics"
    },
    "session_id": "ses_4d2k9m"
  }'

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({
    amount: 15000,
    currency: 'USD',
    payment_method: {
      type: 'card',
      card_bin: '424242',
      last_four: '4242',
      expiry_month: 12,
      expiry_year: 2027
    },
    user: {
      id: 'usr_8f3k2p',
      email: 'buyer@example.com',
      ip_address: '203.0.113.45'
    },
    merchant: {
      id: 'mch_7x9qrt',
      category: 'electronics'
    },
    session_id: 'ses_4d2k9m'
  })
});

const result = await response.json();
console.log(result);

Request field reference:

Field	Type	Description
`amount`	integer	Transaction amount in the smallest currency unit (cents for USD)
`currency`	string	ISO 4217 currency code
`payment_method.type`	string	Payment rail: `card`, `wallet`, `bank_transfer`, `qr`, `crypto`
`payment_method.card_bin`	string	First six digits of the card number
`user.id`	string	Your internal user identifier
`user.ip_address`	string	The user’s IP address at the time of the transaction
`session_id`	string	The FraudEG session token collected by the browser SDK (optional but recommended)

Understand the response

A successful request returns HTTP 200 with a JSON body. Here is a typical response for a low-risk transaction:

{
  "transaction_id": "txn_9z3p1q",
  "risk_score": 23,
  "decision": "allow",
  "signals": [
    { "name": "device_trusted", "weight": "low_risk" },
    { "name": "velocity_normal", "weight": "low_risk" }
  ],
  "latency_ms": 48,
  "created_at": "2024-03-15T14:22:33Z"
}

Response field reference:

Field	Type	Description
`transaction_id`	string	FraudEG’s unique identifier for this scored transaction
`risk_score`	integer	Score from `0` (no risk) to `100` (highest risk)
`decision`	string	Machine decision: `allow`, `challenge`, or `block`
`signals`	array	Ranked list of factors that influenced the score
`signals[].name`	string	Signal identifier (human-readable in the dashboard)
`signals[].weight`	string	Signal contribution: `low_risk`, `elevated_risk`, or `high_risk`
`latency_ms`	integer	Time FraudEG spent processing the request, in milliseconds
`created_at`	string	ISO 8601 timestamp of when the assessment was created

The decision field is the primary value to act on. Your risk thresholds are configurable in the FraudEG dashboard under Platform → Risk Rules.

Handle the decision in your code

Branch your application logic on the decision field. The three possible values map to clear actions:

allow — proceed with the transaction normally.
challenge — require additional verification (for example, 3DS, OTP, or a manual review queue).
block — decline the transaction and present an appropriate message to the user.

Node.js

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(transactionPayload)
});

const { decision, transaction_id, risk_score } = await response.json();

switch (decision) {
  case 'allow':
    // Proceed — authorize the payment
    await authorizePayment(transactionPayload);
    break;

  case 'challenge':
    // Step up — send user through additional verification
    await initiateStepUpAuth({ transaction_id, risk_score });
    break;

  case 'block':
    // Decline — do not process the payment
    return res.status(402).json({
      error: 'Transaction declined. Please contact support.'
    });

  default:
    // Unexpected value — fail safe
    throw new Error(`Unknown FraudEG decision: ${decision}`);
}

Store the transaction_id alongside your own transaction record. You can use it to retrieve the full assessment, submit feedback, and link events in the FraudEG dashboard.

Always use a test API key (feg_test_sk_...) during development and CI. Test keys hit the sandbox environment, which mirrors production behavior exactly but never affects your live fraud models or billing. Switch to a live key (feg_live_sk_...) only when you deploy to production.

Next Steps

Authentication

Learn about key types, security best practices, and how to rotate credentials.

Risk Scoring Concepts

Understand how scores are calculated and how to tune decision thresholds.

Payment Fraud Prevention

End-to-end guide for protecting card and wallet payments in production.

Get Started

Core Concepts

Guides

Platform

FraudEG Quickstart: Score Your First API Transaction

Prerequisites

Steps

Next Steps

Authentication

Risk Scoring Concepts

Payment Fraud Prevention

​Prerequisites

​Steps

​Next Steps

Authentication

Risk Scoring Concepts

Payment Fraud Prevention

Prerequisites

Steps

Next Steps