> ## 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.
# FraudEG Quickstart: Score Your First API Transaction
> Make your first fraud risk assessment with FraudEG. Get an API key, score a live transaction, and handle the risk decision in under 5 minutes.
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](https://dashboard.fraudeg.com/signup) 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
Log in to the [FraudEG dashboard](https://dashboard.fraudeg.com), 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:
```text theme={null}
feg_test_sk_a1b2c3d4e5f6g7h8i9j0
```
Set it as an environment variable so you don't hard-code it in any file:
```bash theme={null}
export FRAUDEG_API_KEY="feg_test_sk_a1b2c3d4e5f6g7h8i9j0"
```
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.
```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": 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"
}'
```
```javascript Node.js theme={null}
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) |
A successful request returns HTTP `200` with a JSON body. Here is a typical response for a low-risk transaction:
```json theme={null}
{
"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**.
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.
```javascript Node.js theme={null}
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
Learn about key types, security best practices, and how to rotate credentials.
Understand how scores are calculated and how to tune decision thresholds.
End-to-end guide for protecting card and wallet payments in production.