API Reference

Introduction

Ratel Security is an enterprise-grade Anti-Money Laundering (AML) and Combating the Financing of Terrorism (CFT) platform built for African financial institutions. Our API enables you to screen every transaction through a 6-layer compliance pipeline in under 200ms. This guide covers everything you need to integrate Ratel Security into your backend systems:

Authentication — How to authenticate your API requests
Quick Start — Screen your first transaction in under 5 minutes
API Reference — Full endpoint documentation
How Screening Works — Understand the pipeline behind the verdict
Webhooks — Receive real-time case resolution notifications
Error Handling — Status codes and troubleshooting

Authentication

All API requests require an X-API-Key header. Generate your API key from the Admin → API Keys page of your Ratel Dashboard.

X-API-Key: rk_live_a1b2c3d4e5f6g7h8i9j0

Keep your API key secret. Your key carries full screening privileges for your workspace. Never expose it in client-side code (mobile apps, browser JavaScript). All API calls must originate from your backend servers.

Quick Start

Screen your first transaction in 3 steps: Step 1: Generate an API key from your Dashboard. Step 2: Send a screening request:

curl -X POST https://api.ratelsecurity.com/v1/transactions/screen \
  -H "X-API-Key: rk_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "TXN-2026-001",
    "type": "TRANSFER",
    "channel": "MOBILE_APP",
    "amount": 5000000,
    "currency": "NGN",
    "senderAccountNumber": "0123456789",
    "senderBvn": "22012345678",
    "senderName": "John Doe",
    "receiverAccountNumber": "9876543210",
    "receiverName": "Jane Smith",
    "receiverCountry": "NG",
    "narration": "Payment for goods",
    "timestamp": "2026-05-08T12:00:00Z"
  }'

Step 3: Handle the response. Route your transaction based on the outcome field:

Outcome	Risk Level	Score Range	Your Action
`APPROVE`	`LOW`	0–29	✅ Process the transaction immediately.
`REVIEW`	`MEDIUM`	30–59	⚠️ Process it, but flag for compliance review.
`ESCALATE`	`HIGH`	60–79	🔶 Hold the transaction pending manual approval.
`BLOCK`	`CRITICAL`	80–100	🚫 Reject the transaction and freeze the account.

Screen Transaction

Request

POST /api/v1/transactions/screen

Field	Type	Required	Description
`externalId`	`string`	✅	Your unique transaction reference. Used for idempotency — sending the same ID twice returns the cached verdict.
`type`	`string`	✅	`TRANSFER`, `CASH_DEPOSIT`, `CASH_WITHDRAWAL`, `INTERNATIONAL_TRANSFER`, `BILL_PAYMENT`
`channel`	`string`	✅	`MOBILE_APP`, `INTERNET_BANKING`, `USSD`, `ATM`, `POS`, `BRANCH`
`amount`	`number`	✅	Amount in base currency unit (e.g. `5000000` = ₦5M).
`currency`	`string`		ISO 4217 code. Defaults to `NGN`.
`senderAccountNumber`	`string`	✅	Sender’s bank account number (NUBAN, 10 digits).
`senderBvn`	`string`		Sender’s BVN. Strongly recommended — enables Identity Risk scoring.
`senderName`	`string`	✅	Sender’s full name. Screened against global sanctions & PEP lists.
`receiverAccountNumber`	`string`		Receiver’s bank account number.
`receiverName`	`string`		Receiver’s full name. Also screened if provided.
`receiverBankCode`	`string`		Receiver’s bank CBN code (e.g. `"058"` for GTBank).
`receiverCountry`	`string`		ISO 3166-1 alpha-2 code (e.g. `"NG"`, `"US"`). Triggers FTR if ≠ `NG`.
`narration`	`string`		Transaction description. Scanned for high-risk keywords.
`deviceId`	`string`		Device fingerprint. Enables behavioral anomaly detection.
`ipAddress`	`string`		Client IP address. Enables geo-anomaly detection.
`timestamp`	`string`	✅	ISO 8601 (e.g. `"2026-05-08T12:00:00Z"`).

Response

{
  "success": true,
  "data": {
    "verdict": {
      "outcome": "ESCALATE",
      "riskLevel": "HIGH",
      "score": 75,
      "triggeredRules": [
        {
          "ruleId": "AML-003",
          "name": "Structuring Detection",
          "severity": "HIGH",
          "category": "REGULATORY"
        }
      ]
    },
    "caseId": "case_12345abcde",
    "status": "PROCESSED"
  }
}

Idempotency: If you send the same externalId twice, the API returns the previously cached verdict without re-screening. Use this to safely retry failed requests.

How Screening Works

Every transaction passes through 6 screening layers in sequence. The entire pipeline completes in 80–200ms (p95).

The Pipeline

Stage	Engine	Latency	What It Does
1	Validation	~5ms	Schema validation, idempotency check, persist transaction
2	Context Enrichment	~15ms	Fetch sender’s recent history, account dormancy, KYC status
3	Sanctions & PEP	~25ms	Screen names against 1.8M global watchlist entities
4	Regulatory Compliance	~2ms	Execute 7 mandatory AML rules
5	Identity Risk	~1ms	Evaluate sender’s KYC verification status
6	Behavioral Analysis	~50ms	ML scoring for device, velocity, and geographic anomalies

Mandatory Regulatory Rules

These 7 rules are always active and cannot be disabled. They implement national AML/CFT Act requirements.

Rule	Trigger	Auto-Actions
AML-001 Cash Threshold	Cash ≥ ₦5,000,000	Generate CTR, Notify Officer
AML-002 Transfer Threshold	Transfer ≥ ₦10,000,000	Generate CTR, Notify Officer
AML-003 Structuring	Single txn ≥ 80% of threshold, OR 3+ txns in 24h exceeding threshold	Generate SAR, Create Case
AML-004 PEP Screening	Sender is a Politically Exposed Person	Enhanced Due Diligence
AML-005 Foreign Transfer	International transfer or receiver country ≠ NG	Generate FTR
AML-006 Dormant Account	No activity for ≥ 180 days	Create Case
AML-007 Rapid Succession	≥ 5 txns within 60 minutes from same account	Create Case

Sanctions & PEP Matching

Sender and receiver names are cross-referenced against 1.8 million entities from:

UN Security Council Consolidated List
US OFAC SDN + Consolidated Lists
EU Consolidated Financial Sanctions
UK HMT Sanctions List
Interpol Red Notices
FATF Blacklist / Greylist entities

The engine uses multi-algorithm entity resolution to catch typos, transliterations, and aliases:

Algorithm	Purpose
Exact Match	Case-normalized literal comparison
Jaro-Winkler	Fuzzy string similarity (handles typos)
Phonetic Match	Sound-alike matching (handles transliterations)
Fingerprint Levenshtein	Edit distance on normalized name tokens

Only matches with ≥ 70% composite confidence are flagged.

Identity Risk Scoring

Sender KYC Status	Risk Score	Outcome
VERIFIED	0	APPROVE
NONE (no application)	40	REVIEW
EXPIRED	50	REVIEW
REJECTED	70	ESCALATE

Behavioral Analysis

Signal	Trigger	Detects
Multiple Devices	> 3 devices on one account	Account takeover, credential sharing
Multiple IPs	> 5 IPs on one account	Proxy/VPN usage, bot activity
Multi-Country	> 2 countries on one account	Impossible travel, geographic anomalies

Scoring Algorithm

Each engine produces a risk score (0–100). Scores are aggregated using weighted severity:

Category	Weight	Rationale
Regulatory Compliance	1.5×	Core compliance — highest authority
Identity Verification	1.3×	KYC integrity is compliance-critical
Custom Rules	1.2×	Bank-specific logic elevated above generic engines
Sanctions & PEP	1.0×	Standard weight — severity via outcome escalation
Behavioral Analysis	0.8×	Supplementary evidence

Score Floor Guarantee: Final Score = MAX(weighted_average, max_engine_score × 0.8) This prevents a critical match (e.g., Sanctions hit scoring 95) from being diluted by clean engines. The highest-severity outcome from any engine becomes the final decision.

Asynchronous Side-Effects

While the API responds in under 200ms, the following actions are queued in the background:

Case Management — Auto-creates compliance cases for REVIEW, ESCALATE, or BLOCK outcomes
Regulatory Reporting — Auto-generates XML drafts for SAR, CTR, and FTR reports
Audit Logging — Immutable audit trail for regulatory inspection
Alert Dispatch — Email and dashboard notifications to Compliance Officers

Webhooks

Ratel Security sends real-time notifications to your backend when a compliance officer resolves a case linked to one of your transactions.

Setup: Configure your Webhook URL and Webhook Secret in the Developer Webhooks section of the API Keys page in your Dashboard.

Events

Event	Trigger
`case.resolved`	A compliance officer marks a case as `RESOLVED_TRUE_POSITIVE`, `RESOLVED_FALSE_POSITIVE`, or `CLOSED`

Payload

{
  "event": "case.resolved",
  "timestamp": "2026-05-08T15:00:00Z",
  "data": {
    "caseId": "case_12345abcde",
    "status": "RESOLVED_FALSE_POSITIVE",
    "resolutionNote": "Customer provided valid source of funds documentation.",
    "relatedTransactionId": "TXN-2026-001",
    "updatedAt": "2026-05-08T15:00:00Z"
  }
}

Handling the resolution in your system:

`status` Value	Meaning	Your Action
`RESOLVED_FALSE_POSITIVE`	Officer confirmed the transaction is legitimate	Unfreeze the transaction and process it
`RESOLVED_TRUE_POSITIVE`	Officer confirmed suspicious activity	Permanently block and escalate internally
`CLOSED`	Case closed after investigation	Take no further action

Delivery Guarantees

Webhook delivery is backed by a persistent message queue with automatic retries:

Property	Value
Max Attempts	5
Backoff Strategy	Exponential (5s → 10s → 20s → 40s → 80s)
Request Timeout	10 seconds per attempt
Completed Job Retention	24 hours
Failed Job Retention	7 days

Your endpoint must return a 2xx status code. Any non-2xx response will trigger automatic retries. If all 5 attempts fail, the event is retained in the dead-letter queue for 7 days.

Signature Verification

Every webhook includes an X-Ratel-Signature header — an HMAC-SHA256 hash of the raw JSON body, signed with your Webhook Secret. Always verify this server-side.

const crypto = require('crypto');

app.post('/ratel/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-ratel-signature'];
  const hash = crypto
    .createHmac('sha256', process.env.RATEL_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (`sha256=${hash}` !== signature) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  if (event.event === 'case.resolved') {
    if (event.data.status === 'RESOLVED_FALSE_POSITIVE') {
      // Unfreeze the transaction in your system
    } else if (event.data.status === 'RESOLVED_TRUE_POSITIVE') {
      // Permanently block and escalate
    }
  }

  res.status(200).send('OK');
});

Error Handling

Standard HTTP status codes indicate success or failure:

Code	Meaning	Solution
`200`	Success	Request processed successfully.
`400`	Bad Request	Check validation errors in the response body. Ensure all required fields are present.
`401`	Unauthorized	Your `X-API-Key` is missing, invalid, or revoked. Check the API Keys page in your Dashboard.
`409`	Conflict	The `externalId` was already processed. The cached verdict is returned.
`429`	Too Many Requests	You exceeded your workspace’s rate limit. Implement exponential backoff.
`500`	Internal Server Error	Unexpected server error. Retry with backoff.

Fail-Open Policy: If the Sanctions or Behavioral engines experience upstream downtime, Ratel Security implements a fail-open policy — your legitimate transactions continue processing without interruption, while partial screenings are logged for retroactive review.

Ratel Security — Enterprise-grade AML/CFT compliance for African financial institutions. For support, contact support@ratelsecurity.com.

Overview

Core Concepts

Features

Modules

API Reference

Introduction

Authentication

Quick Start

Screen Transaction

Request

Response

How Screening Works

The Pipeline

Mandatory Regulatory Rules

Sanctions & PEP Matching

Identity Risk Scoring

Behavioral Analysis

Scoring Algorithm

Asynchronous Side-Effects

Webhooks

Events

Payload

Delivery Guarantees

Signature Verification

Error Handling

Overview

Core Concepts

Features

Modules

API Reference

Documentation Index

​Introduction

​Authentication

​Quick Start

​Screen Transaction

​Request

​Response

​How Screening Works

​The Pipeline

​Mandatory Regulatory Rules

​Sanctions & PEP Matching

​Identity Risk Scoring

​Behavioral Analysis

​Scoring Algorithm

​Asynchronous Side-Effects

​Webhooks

​Events

​Payload

​Delivery Guarantees

​Signature Verification

​Error Handling

Introduction

Authentication

Quick Start

Screen Transaction

Request

Response

How Screening Works

The Pipeline

Mandatory Regulatory Rules

Sanctions & PEP Matching

Identity Risk Scoring

Behavioral Analysis

Scoring Algorithm

Asynchronous Side-Effects

Webhooks

Events

Payload

Delivery Guarantees

Signature Verification

Error Handling