Getting Started

FraudGuard API

The FraudGuard API gives financial institutions and fintechs real-time access to Vacalion's machine learning fraud prevention engine. Analyze transactions, build risk profiles, and configure custom prevention rules — all through a single REST interface.

Base URL

Production https://api.vacalion.com/v2

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Authentication is required for every request.

Responses are encoded in JSON. Send Content-Type: application/json for all POST/PUT requests.

curl -X GET https://api.vacalion.com/v2/health \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import FraudGuard from '@vacalion/sdk';

const client = new FraudGuard({
  apiKey: process.env.VACALION_API_KEY
});

const health = await client.health();
console.log(health.status); // "ok"

from vacalion import FraudGuard

client = FraudGuard(api_key="YOUR_API_KEY")

health = client.health()
print(health.status)  # "ok"

Response

{
  "status": "ok",
  "version": "2.0.0",
  "latency_ms": 12
}

Getting Started

Quick Start

Get up and running in under 5 minutes. Follow these steps to make your first fraud prevention call.

1

Get Your API Key

Sign up for a Vacalion account and navigate to the Developer Dashboard. Generate your API key from the API Keys section. Keep it secret — treat it like a password.
2

Install the SDK

We provide official SDKs for Node.js, Python, Ruby, and Java. Choose your preferred language and install the package from your package manager.
3

Make Your First Request

Initialize the client with your API key and call analyzeTransaction(). You'll receive a risk score and recommendation in under 10ms.
4

Configure Webhooks

Register a webhook endpoint to receive real-time notifications when high-risk transactions are detected or fraud rules are triggered.

// Step 2: Install
npm install @vacalion/sdk

// Step 3: Analyze a transaction
import FraudGuard from '@vacalion/sdk';

const client = new FraudGuard({
  apiKey: process.env.VACALION_API_KEY
});

const result = await client.fraud.analyze({
  transactionId: "txn_abc123",
  amount:        1250.00,
  currency:      "USD",
  userId:        "user_xyz789",
  merchantId:    "merch_001",
  ipAddress:     "192.168.1.1",
  deviceId:      "dev_a1b2c3",
  location: {
    country:   "US",
    city:      "New York",
    latitude:  40.7128,
    longitude: -74.0060
  }
});

console.log(result.riskScore);       // 0.87
console.log(result.recommendation); // "BLOCK"

# Step 2: Install
pip install vacalion

# Step 3: Analyze a transaction
from vacalion import FraudGuard

client = FraudGuard(api_key="YOUR_API_KEY")

result = client.fraud.analyze(
  transaction_id="txn_abc123",
  amount=1250.00,
  currency="USD",
  user_id="user_xyz789",
  merchant_id="merch_001",
  ip_address="192.168.1.1"
)

print(result.risk_score)       # 0.87
print(result.recommendation)  # "BLOCK"

Getting Started

Environments

Use the sandbox environment for development and testing. It returns realistic mock responses without affecting live data or incurring charges.

Environment	Base URL	Notes
Production	`https://api.vacalion.com/v2`	Live data. Billed per request.
Sandbox	`https://sandbox.api.vacalion.com/v2`	Safe for testing. No charges.

Sandbox API keys are prefixed fg_test_. Production keys are prefixed fg_live_. Never use production keys in development environments.

curl -X POST https://sandbox.api.vacalion.com/v2/fraud/analyze \
  -H "Authorization: Bearer fg_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transactionId":"txn_test_001","amount":100,"currency":"USD","userId":"user_test"}'

Authentication

FraudGuard supports three authentication methods. API Key authentication is recommended for most use cases.

API Key Recommended

Pass your API key in the Authorization header as a Bearer token. Simple, fast, and works for all endpoints.

OAuth 2.0

Industry-standard authorization flow. Ideal for applications that need to act on behalf of a user. Supports authorization code and client credentials flows.

JWT Tokens

Short-lived signed tokens ideal for microservices and server-to-server communication. Tokens expire after 1 hour and can be refreshed using your refresh token.

# Include your API key in every request
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.vacalion.com/v2/fraud/analyze

# Exchange client credentials for a token
curl -X POST https://auth.vacalion.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# Then use the returned access_token
curl -H "Authorization: Bearer ACCESS_TOKEN" \
     https://api.vacalion.com/v2/fraud/analyze

# Generate JWT from your service account
const jwt = await client.auth.generateToken({
  serviceAccountId: "sa_abc123",
  expiresIn: 3600 // 1 hour
});

// Use the token in requests
const result = await client.fraud.analyze(txn, {
  token: jwt.accessToken
});

API Reference

POST /v2/fraud/analyze

Analyze Transaction

Submit a transaction for real-time fraud analysis. Returns a risk score between 0 and 1 along with a recommended action. Average response time is under 50ms.

transactionIdstringrequired

Unique identifier for the transaction in your system.

amountnumberrequired

Transaction amount in the smallest currency unit (e.g., cents for USD).

currencystringrequired

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

userIdstringrequired

Your internal user ID for the account making the transaction.

merchantIdstringoptional

Merchant identifier. Used for merchant-level risk scoring.

ipAddressstringoptional

IPv4 or IPv6 address of the client. Strongly recommended — improves accuracy by 18%.

deviceIdstringoptional

Unique device fingerprint or identifier. Used in device velocity checks.

locationobjectoptional

Geographic context: country, city, latitude, longitude.

200

Transaction analyzed successfully. Returns a FraudAnalysisResult object with riskScore, recommendation, and factors.

400

Invalid request body. Check that all required fields are present and properly formatted.

401

Authentication failed. Verify your API key is valid and not expired.

429

Rate limit exceeded. Back off and retry using exponential backoff.

500

Internal server error. Retry after a brief delay. Check our status page if the issue persists.

curl -X POST https://api.vacalion.com/v2/fraud/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_abc123",
    "amount": 125000,
    "currency": "USD",
    "userId": "user_xyz789",
    "merchantId": "merch_001",
    "ipAddress": "203.0.113.42",
    "deviceId": "dev_a1b2c3",
    "location": {
      "country": "US",
      "city": "New York",
      "latitude": 40.7128,
      "longitude": -74.0060
    }
  }'

const result = await client.fraud.analyze({
  transactionId: "txn_abc123",
  amount:        125000,
  currency:      "USD",
  userId:        "user_xyz789",
  merchantId:    "merch_001",
  ipAddress:     "203.0.113.42",
  deviceId:      "dev_a1b2c3",
  location: {
    country:   "US",
    city:      "New York",
    latitude:  40.7128,
    longitude: -74.0060
  }
});

result = client.fraud.analyze(
  transaction_id="txn_abc123",
  amount=125000,
  currency="USD",
  user_id="user_xyz789",
  merchant_id="merch_001",
  ip_address="203.0.113.42",
  device_id="dev_a1b2c3",
  location={
    "country":   "US",
    "city":      "New York",
    "latitude":  40.7128,
    "longitude": -74.0060
  }
)

Response 200

{
  "transactionId": "txn_abc123",
  "riskScore": 0.87,
  "recommendation": "BLOCK",
  "confidence": 0.94,
  "processingTimeMs": 42,
  "factors": [
    {
      "type": "VELOCITY_ANOMALY",
      "severity": "HIGH",
      "description": "3 transactions in 2 min"
    },
    {
      "type": "GEO_ANOMALY",
      "severity": "MEDIUM",
      "description": "Unusual location for user"
    }
  ],
  "metadata": {
    "modelVersion": "v2.1.0",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

API Reference

GET /v2/transactions/{id}

Get Transaction

Retrieve the fraud analysis results and full audit trail for a previously analyzed transaction.

idstringrequired

The transaction ID returned from the analyze endpoint, or your own transaction ID if you submitted it in the original request.

200

Transaction found. Returns the full Transaction object including fraud analysis, status, and audit events.

404

Transaction not found. Verify the ID is correct and belongs to your account.

curl https://api.vacalion.com/v2/transactions/txn_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

const txn = await client.transactions.get("txn_abc123");
console.log(txn.status, txn.riskScore);

Response 200

{
  "id": "txn_abc123",
  "status": "BLOCKED",
  "riskScore": 0.87,
  "amount": 125000,
  "currency": "USD",
  "createdAt": "2024-01-15T10:30:00Z",
  "auditTrail": [
    { "event": "ANALYZED", "ts": "2024-01-15T10:30:00Z" },
    { "event": "BLOCKED",  "ts": "2024-01-15T10:30:00Z" }
  ]
}

API Reference

GET /v2/analytics/fraud-trends

Fraud Trends

Retrieve aggregated fraud analytics and trend data for your account. Use this to power dashboards and build business intelligence on your fraud landscape.

startDatestringrequired

ISO 8601 date string for the start of the analysis window, e.g. 2024-01-01.

endDatestringrequired

ISO 8601 date string for the end of the analysis window.

granularitystringoptional

Aggregation interval: hourly, daily (default), or weekly.

merchantIdstringoptional

Filter trends to a specific merchant.

200

Returns an array of trend data points with fraud counts, amounts, and risk distributions.

400

Invalid date range. Ensure endDate is after startDate and the range is 365 days or less.

curl "https://api.vacalion.com/v2/analytics/fraud-trends?startDate=2024-01-01&endDate=2024-01-31&granularity=daily" \
  -H "Authorization: Bearer YOUR_API_KEY"

const trends = await client.analytics.fraudTrends({
  startDate:   "2024-01-01",
  endDate:     "2024-01-31",
  granularity: "daily"
});

API Reference

POST /v2/webhooks

Create Webhook

Register a HTTPS endpoint to receive real-time event notifications. FraudGuard will POST a signed JSON payload to your endpoint whenever a subscribed event occurs.

urlstringrequired

The HTTPS URL to send event payloads to. Must be a publicly accessible HTTPS endpoint.

eventsarrayrequired

List of event types to subscribe to. See the Webhook Events reference for available types.

descriptionstringoptional

Human-readable label for this webhook endpoint.

secretstringoptional

Secret key used to sign payloads via HMAC-SHA256. If omitted, a secret is auto-generated and returned in the response.

201

Webhook created. Returns the full Webhook object including the signing secret.

400

Invalid request. Ensure the URL is HTTPS and all specified event types are valid.

curl -X POST https://api.vacalion.com/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourdomain.com/webhooks/fraud",
    "events": ["fraud.detected", "transaction.blocked"],
    "description": "Fraud alert handler"
  }'

const wh = await client.webhooks.create({
  url:         "https://yourdomain.com/webhooks/fraud",
  events:      ["fraud.detected", "transaction.blocked"],
  description: "Fraud alert handler"
});
console.log(wh.secret); // Save this secret!

API Reference

GET /v2/users/{id}/risk-profile

Get User Risk Profile

Retrieve the computed risk profile for a specific user. Profiles are updated in real-time as transactions are processed and reflect the user's current risk standing.

idstringrequired

Your internal user ID. Must match the userId used when submitting transactions.

200

Returns a RiskProfile object with risk tier, behavioral signals, and historical patterns.

404

User not found. The user may not have any analyzed transactions yet.

curl https://api.vacalion.com/v2/users/user_xyz789/risk-profile \
  -H "Authorization: Bearer YOUR_API_KEY"

const profile = await client.users.riskProfile("user_xyz789");

Response 200

{
  "userId": "user_xyz789",
  "riskTier": "HIGH",
  "riskScore": 0.82,
  "transactionCount": 142,
  "flaggedCount": 7,
  "signals": [
    "HIGH_VELOCITY",
    "GEO_MISMATCH",
    "DEVICE_CHANGE"
  ],
  "lastUpdated": "2024-01-15T10:30:00Z"
}

API Reference

PUT /v2/fraud/rules/{id}

Update Fraud Rule

Modify an existing custom fraud prevention rule. Rules let you define domain-specific thresholds and logic that are applied on top of Vacalion's ML models.

idstringrequired

The rule ID to update. Obtain rule IDs from the Developer Dashboard or the rules list endpoint.

thresholdnumberoptional

New risk score threshold (0.0–1.0) at which this rule triggers.

actionstringoptional

Action to take when triggered: BLOCK, REVIEW, or ALERT.

enabledbooleanoptional

Enable or disable the rule without deleting it.

200

Rule updated successfully. Returns the updated FraudRule object.

404

Rule not found. Verify the rule ID and that it belongs to your account.

curl -X PUT https://api.vacalion.com/v2/fraud/rules/rule_001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold": 0.75, "action": "REVIEW", "enabled": true}'

const rule = await client.fraud.rules.update("rule_001", {
  threshold: 0.75,
  action:    "REVIEW",
  enabled:   true
});

SDKs & Libraries

Official SDKs

Install our official client libraries for the best developer experience. All SDKs provide full TypeScript types, automatic retries, and built-in error handling.

Node.js

JavaScript / TypeScript

v2.4.1

Python

Python 3.8+

v1.9.3

Ruby

Ruby 2.7+

v1.5.2

Java

Java 11+

v3.1.0

All SDKs are open source. Find examples, changelogs, and contribution guides on GitHub.

Reference

Webhook Events

Subscribe to the events relevant to your workflow. All payloads are signed with HMAC-SHA256 using your webhook secret. Verify signatures before processing.

fraud.detectedA transaction exceeded the fraud risk threshold and was flagged.

transaction.blockedA transaction was automatically blocked based on a rule or risk score.

transaction.approvedA transaction was analyzed and approved with low risk.

transaction.review_requiredA transaction requires manual review before processing.

risk_profile.updatedA user's risk profile changed tier (e.g., LOW → MEDIUM).

rule.triggeredA custom fraud rule was triggered during transaction analysis.

{
  "id": "evt_9f8e7d6c",
  "type": "fraud.detected",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "transactionId": "txn_abc123",
    "riskScore": 0.87,
    "recommendation": "BLOCK",
    "userId": "user_xyz789",
    "amount": 125000,
    "currency": "USD"
  }
}

import crypto from 'crypto';

function verifyWebhook(payload, sig, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig)
  );
}

Reference

Rate Limits

Rate limits vary by plan. Limit headers are included in every response. Implement exponential backoff when you receive a 429 response.

Plan	Monthly	Per-Minute Burst	Concurrent
Starter	5,000	100 req/min	10
Growth	500,000	1,000 req/min	50
Enterprise	Unlimited	Custom	Custom

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1705315800
Content-Type: application/json

Reference

Error Codes

All errors follow a consistent structure. The code field contains a machine-readable error identifier. Use it to handle errors programmatically.

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Request body is malformed or missing required fields.
401	UNAUTHORIZED	Missing or invalid API key. Check your Authorization header.
403	FORBIDDEN	Your plan does not have access to this endpoint or feature.
404	NOT_FOUND	The requested resource does not exist or has been deleted.
409	CONFLICT	A resource with this identifier already exists.
422	UNPROCESSABLE	Request body is valid JSON but contains semantic errors.
429	RATE_LIMITED	Too many requests. Back off and retry using the Reset header.
500	INTERNAL_ERROR	Unexpected server error. Retry after a short delay.
503	SERVICE_UNAVAILABLE	API is temporarily unavailable. Check status.vacalion.com.

Error response format: {"error": {"code": "RATE_LIMITED", "message": "...", "requestId": "req_xxx"}}

FraudGuard API

Base URL

Quick Start

Get Your API Key

Install the SDK

Make Your First Request

Configure Webhooks

Environments

Authentication

Analyze Transaction

Get Transaction

Fraud Trends

Create Webhook

Get User Risk Profile

Update Fraud Rule

Official SDKs

Webhook Events

Rate Limits

Error Codes