Documentation Index
Fetch the complete documentation index at: https://docs.verifow.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Transactions module is the entry point for all AML/CFT screening. Every financial transaction your institution processes should be submitted to the /screen endpoint. The platform returns a verdict in under 200ms with a risk score, outcome, and triggered rules.
Common Workflows
Real-time screening: Your core banking system calls /screen on every outgoing transfer → The API returns an outcome → Your system routes the transaction based on APPROVE, REVIEW, ESCALATE, or BLOCK.
Post-hoc review: A compliance officer queries the transaction list to review recent screenings, drill into a specific transaction, and view the full verdict breakdown.
Permissions
| Action | Who Can Do It |
|---|
| Screen transaction | All authenticated users |
| List transactions | All authenticated users |
| Get transaction detail | All authenticated users |
Endpoints
| Method | Endpoint | Description |
|---|
POST | /api/v1/transactions/screen | Submit a transaction for screening |
GET | /api/v1/transactions | List screened transactions |
GET | /api/v1/transactions/:id | Retrieve a specific transaction |
Screen Transaction
Submit a single transaction for real-time screening. The response includes the final outcome, risk breakdown per engine, triggered rules, and recommended actions.
Request Body
| Field | Type | Required | Description |
|---|
externalId | string | ✅ | Your unique transaction reference |
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. Enables identity risk scoring |
senderName | string | ✅ | Sender’s full name. Screened against sanctions |
receiverAccountNumber | string | | Receiver’s account number |
receiverName | string | | Receiver’s full name. Also screened |
receiverBankCode | string | | Receiver’s bank CBN code (e.g. "058") |
receiverCountry | string | | ISO 3166-1 alpha-2. Triggers FTR if ≠ NG |
narration | string | | Transaction description |
deviceId | string | | Device fingerprint for behavioral analysis |
ipAddress | string | | Client IP for geo-anomaly detection |
timestamp | string | ✅ | ISO 8601 timestamp |
curl -X POST /v1/transactions/screen \
-H "Authorization: Bearer <access_token>" \
-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-16T12:00:00Z"
}'
{
"success": true,
"data": {
"transactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
"externalId": "TXN-0791-389803",
"outcome": "REVIEW",
"riskLevel": "MEDIUM",
"aggregateScore": 32,
"actions": ["NOTIFY_OFFICER"],
"riskBreakdown": [
{
"category": "Regulatory Compliance",
"score": 0,
"outcome": "APPROVE",
"rulesTriggered": 0,
"latencyMs": 3
},
{
"category": "Sanctions & PEP Screening",
"score": 0,
"outcome": "APPROVE",
"rulesTriggered": 0,
"latencyMs": 3020
},
{
"category": "KYC Verification",
"score": 40,
"outcome": "REVIEW",
"rulesTriggered": 1,
"latencyMs": 0
},
{
"category": "Custom Rules",
"score": 0,
"outcome": "APPROVE",
"rulesTriggered": 0,
"latencyMs": 10074
},
{
"category": "Decision Engine",
"score": 0,
"outcome": "APPROVE",
"rulesTriggered": 0,
"latencyMs": 48
},
{
"category": "Behavioral Analysis",
"score": 0,
"outcome": "APPROVE",
"rulesTriggered": 1,
"latencyMs": 206
}
],
"triggeredRules": [
{
"name": "No KYC Application Found",
"category": "KYC Verification",
"riskScore": 40,
"details": "No KYC record found for sender (BVN: 22075678966)",
"createdBy": null
}
],
"totalLatencyMs": 13447
}
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{ "field": "amount", "message": "amount must be a positive number" }
]
}
}
{
"success": false,
"error": {
"code": "DUPLICATE_EXTERNAL_ID",
"message": "This externalId has already been processed",
"data": {
"transactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
"outcome": "REVIEW",
"riskLevel": "MEDIUM",
"aggregateScore": 32
}
}
}
Idempotency: Sending the same externalId twice returns the cached
verdict without re-screening. This makes retries safe.
List Transactions
Retrieve a paginated list of all screened transactions in your tenant.
Query Parameters
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number |
limit | integer | 20 | Items per page (max 100) |
outcome | string | — | Filter by APPROVE, REVIEW, ESCALATE, BLOCK |
type | string | — | Filter by transaction type |
from | string | — | ISO 8601 start date |
to | string | — | ISO 8601 end date |
curl -X GET "/v1/transactions?outcome=BLOCK&page=1&limit=10" \
-H "Authorization: Bearer <access_token>"
{
"success": true,
"data": {
"items": [
{
"id": "fae50ecb-d997-4700-bae7-49650678bb06",
"externalId": "TXN-0791-389803",
"type": "TRANSFER",
"channel": "MOBILE_APP",
"amount": "5000000",
"currency": "NGN",
"senderAccountNumber": "0123456789",
"senderName": "John Doe",
"receiverName": "Jane Smith",
"receiverCountry": "NG",
"transactionTimestamp": "2026-05-16T12:00:00Z",
"verdict": {
"outcome": "BLOCK",
"riskLevel": "CRITICAL",
"aggregateScore": 95,
"totalLatencyMs": 145
},
"createdAt": "2026-05-16T12:00:00Z"
}
],
"total": 3,
"page": 1,
"limit": 10,
"totalPages": 1
}
}
Get Transaction Detail
Retrieve the full screening result for a single transaction, including the complete verdict with engine breakdowns.
Path Parameters
| Parameter | Type | Description |
|---|
id | string | Transaction UUID |
curl -X GET /v1/transactions/fae50ecb-d997-4700-bae7-49650678bb06 \
-H "Authorization: Bearer <access_token>"
{
"success": true,
"data": {
"id": "fae50ecb-d997-4700-bae7-49650678bb06",
"tenantId": "660e8400-e29b-41d4-a716-446655440001",
"externalId": "TXN-0791-389803",
"type": "TRANSFER",
"channel": "MOBILE_APP",
"amount": "5000000",
"currency": "NGN",
"senderAccountNumber": "0123456789",
"senderBvn": "22012345678",
"senderName": "John Doe",
"senderBankCode": null,
"receiverAccountNumber": "9876543210",
"receiverBvn": null,
"receiverName": "Jane Smith",
"receiverBankCode": null,
"receiverCountry": "NG",
"narration": "Payment for goods",
"deviceId": null,
"ipAddress": null,
"latitude": null,
"longitude": null,
"transactionTimestamp": "2026-05-16T12:00:00Z",
"metadata": null,
"createdAt": "2026-05-16T12:00:00Z",
"verdict": {
"id": "vtx_001",
"transactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
"outcome": "REVIEW",
"riskLevel": "MEDIUM",
"aggregateScore": 32,
"engineVerdicts": [
{
"category": "KYC Verification",
"score": 40,
"outcome": "REVIEW",
"rulesTriggered": 1,
"latencyMs": 0
}
],
"actions": ["NOTIFY_OFFICER"],
"totalLatencyMs": 13447,
"processedAt": "2026-05-16T12:00:01Z"
}
}
}
Transaction data is immutable once screened. If you need to re-evaluate,
submit a new transaction with a different externalId.
