> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartcomply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Transaction for Monitoring

> Submit a transaction for real-time fraud assessment. The payload shape depends on the transaction_type — pick your type below.

The Submit Transaction endpoint processes a transaction in real-time against your configured thresholds and limits and returns an activity code indicating whether the transaction is clean, suspicious, or high-risk.

The payload shape depends on the `transaction_type` value: **Transfer**, **USSD**, and **Web** use originating and destination account details, while **Card** uses card and merchant details. Pick your type below.

## Endpoint

```
POST /api/v1/monitoring/transaction_monitoring/
```

## Request

### Headers

| Header | Value | Required |
| - | - | - |
| `x-access-token` | Your API secret key | Yes |
| `Content-Type` | `application/json` | Yes |

### Common Body Parameters

These fields are required for every `transaction_type`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `transaction_id` | string | Yes | Unique identifier for the transaction |
| `amount` | number | Yes | Transaction amount (e.g. `99.13` or `14000000`) |
| `currency` | string | Yes | Currency code (e.g. `NGN`, `USD`) |
| `transaction_type` | string | Yes | One of: `transfer`, `ussd`, `web`, `card` |
| `account_type` | string | Yes | `individual` or `corporate` |
| `customer_details` | object | Yes | Details of the customer initiating the transaction |
| `customer_details.customer_name` | string | Yes | Customer's full name |
| `customer_details.customer_email` | string | Yes | Customer's email address |
| `customer_details.customer_phone` | string | No | Customer's phone number (e.g. `+2347012345678`) |
| `customer_details.identifier` | string | No | Customer's identifier value — BVN for Nigeria, national ID for Kenya, Ghana card for Ghana, etc. |
| `customer_details.identifier_type` | string | No | Key of the identifier type (`bvn`, `national_id`, `ghana_card`, etc.). Required when `identifier` is provided |
| `additional_info` | object | Yes | Additional context for fraud evaluation |
| `additional_info.ip_address` | string | Yes | IP address during the transaction |
| `additional_info.location` | string | Yes | Location string or lat/lon (e.g. `"Lagos, Nigeria"` or `"lat=-30.66,lon=-65.77"`) |
| `additional_info.transaction_description` | string | No | Optional description of the transaction |

### Type-Specific Parameters

> [tab] Transfer
>
> Account-to-account transfer. In addition to the common fields above, you must include origin and destination accounts.
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `origin_account` | object | Yes | Originating account details |
> | `origin_account.account_number` | string | Yes | Account number of the sender |
> | `origin_account.bank_code` | string | Yes | Bank code of the sender |
> | `destination_account` | object | Yes | Destination account details |
> | `destination_account.account_number` | string | Yes | Account number of the recipient |
> | `destination_account.bank_code` | string | Yes | Bank code of the recipient |
> | `run_kyc` | boolean | No | Run a KYC check on the customer. Defaults to `false` |
>
> #### Example
>
> ```bash cURL theme={null}
> curl -X POST "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/" \
>   -H "x-access-token: YOUR_SECRET_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "transaction_id": "12345678",
>     "amount": 14000000,
>     "currency": "NGN",
>     "transaction_type": "transfer",
>     "account_type": "individual",
>     "origin_account": {
>       "account_number": "9876543219",
>       "bank_code": "001"
>     },
>     "destination_account": {
>       "account_number": "123456789",
>       "bank_code": "002"
>     },
>     "customer_details": {
>       "customer_name": "Muhammad Ibrahim Isah",
>       "customer_email": "user@example.com",
>       "identifier": "22430372151",
>       "identifier_type": "bvn"
>     },
>     "additional_info": {
>       "ip_address": "192.168.1.1",
>       "location": "Lagos, Nigeria",
>       "transaction_description": "Payment for order #789"
>     },
>     "run_kyc": false
>   }'
> ```
>
> ```javascript Node.js theme={null}
> const response = await fetch(
>   "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/",
>   {
>     method: "POST",
>     headers: {
>       "x-access-token": "YOUR_SECRET_KEY",
>       "Content-Type": "application/json",
>     },
>     body: JSON.stringify({
>       transaction_id: "12345678",
>       amount: 14000000,
>       currency: "NGN",
>       transaction_type: "transfer",
>       account_type: "individual",
>       origin_account: {
>         account_number: "9876543219",
>         bank_code: "001",
>       },
>       destination_account: {
>         account_number: "123456789",
>         bank_code: "002",
>       },
>       customer_details: {
>         customer_name: "Muhammad Ibrahim Isah",
>         customer_email: "user@example.com",
>         identifier: "22430372151",
>         identifier_type: "bvn",
>       },
>       additional_info: {
>         ip_address: "192.168.1.1",
>         location: "Lagos, Nigeria",
>         transaction_description: "Payment for order #789",
>       },
>       run_kyc: false,
>     }),
>   }
> );
> const data = await response.json();
> ```
>
> ```python Python theme={null}
> import requests
>
> response = requests.post(
>     "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/",
>     headers={
>         "x-access-token": "YOUR_SECRET_KEY",
>         "Content-Type": "application/json",
>     },
>     json={
>         "transaction_id": "12345678",
>         "amount": 14000000,
>         "currency": "NGN",
>         "transaction_type": "transfer",
>         "account_type": "individual",
>         "origin_account": {
>             "account_number": "9876543219",
>             "bank_code": "001",
>         },
>         "destination_account": {
>             "account_number": "123456789",
>             "bank_code": "002",
>         },
>         "customer_details": {
>             "customer_name": "Muhammad Ibrahim Isah",
>             "customer_email": "user@example.com",
>             "identifier": "22430372151",
>             "identifier_type": "bvn",
>         },
>         "additional_info": {
>             "ip_address": "192.168.1.1",
>             "location": "Lagos, Nigeria",
>             "transaction_description": "Payment for order #789",
>         },
>         "run_kyc": False,
>     },
> )
> data = response.json()
> ```

> [tab] USSD
>
> Same payload as **Transfer** but with `"transaction_type": "ussd"`. The body still requires `origin_account` and `destination_account`.
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `origin_account` | object | Yes | Originating account details |
> | `origin_account.account_number` | string | Yes | Account number of the sender |
> | `origin_account.bank_code` | string | Yes | Bank code of the sender |
> | `destination_account` | object | Yes | Destination account details |
> | `destination_account.account_number` | string | Yes | Account number of the recipient |
> | `destination_account.bank_code` | string | Yes | Bank code of the recipient |
> | `run_kyc` | boolean | No | Run a KYC check on the customer. Defaults to `false` |
>
> #### Example
>
> ```bash cURL theme={null}
> curl -X POST "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/" \
>   -H "x-access-token: YOUR_SECRET_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "transaction_id": "USSD-90001",
>     "amount": 5000,
>     "currency": "NGN",
>     "transaction_type": "ussd",
>     "account_type": "individual",
>     "origin_account": {
>       "account_number": "9876543219",
>       "bank_code": "001"
>     },
>     "destination_account": {
>       "account_number": "123456789",
>       "bank_code": "002"
>     },
>     "customer_details": {
>       "customer_name": "Aisha Bello",
>       "customer_email": "aisha@example.com",
>       "identifier": "22430372151",
>       "identifier_type": "bvn"
>     },
>     "additional_info": {
>       "ip_address": "192.168.1.1",
>       "location": "Lagos, Nigeria",
>       "transaction_description": "USSD airtime top-up"
>     },
>     "run_kyc": false
>   }'
> ```

> [tab] Web
>
> Same payload as **Transfer** but with `"transaction_type": "web"`. The body still requires `origin_account` and `destination_account`.
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `origin_account` | object | Yes | Originating account details |
> | `origin_account.account_number` | string | Yes | Account number of the sender |
> | `origin_account.bank_code` | string | Yes | Bank code of the sender |
> | `destination_account` | object | Yes | Destination account details |
> | `destination_account.account_number` | string | Yes | Account number of the recipient |
> | `destination_account.bank_code` | string | Yes | Bank code of the recipient |
> | `run_kyc` | boolean | No | Run a KYC check on the customer. Defaults to `false` |
>
> #### Example
>
> ```bash cURL theme={null}
> curl -X POST "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/" \
>   -H "x-access-token: YOUR_SECRET_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "transaction_id": "WEB-77410",
>     "amount": 250000,
>     "currency": "NGN",
>     "transaction_type": "web",
>     "account_type": "individual",
>     "origin_account": {
>       "account_number": "9876543219",
>       "bank_code": "001"
>     },
>     "destination_account": {
>       "account_number": "123456789",
>       "bank_code": "002"
>     },
>     "customer_details": {
>       "customer_name": "Tunde Bakare",
>       "customer_email": "tunde@example.com",
>       "identifier": "22430372151",
>       "identifier_type": "bvn"
>     },
>     "additional_info": {
>       "ip_address": "192.168.1.1",
>       "location": "Lagos, Nigeria",
>       "transaction_description": "Web checkout payment"
>     },
>     "run_kyc": false
>   }'
> ```

> [tab] Card
>
> In addition to the common fields above, you must include `card_details`. `merchant_details` is optional but recommended. `origin_account` and `destination_account` are not required.
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `timestamp` | string | No | ISO 8601 transaction timestamp (e.g. `2025-08-23T14:30:00Z`) |
> | `card_details` | object | Yes | Card-specific information |
> | `card_details.bin` | integer | Yes | First six digits of the card number (BIN) |
> | `card_details.last4` | integer | Yes | Last four digits of the card number |
> | `merchant_details` | object | No | Merchant information |
> | `merchant_details.merchant_name` | string | No | Name of the merchant |
> | `merchant_details.merchant_location` | string | No | Location of the merchant |
> | `merchant_details.merchant_mcc` | string | No | Merchant category code (MCC) |
> | `run_kyc` | boolean | No | Run a KYC check on the customer. Defaults to `false` |
>
> #### Example
>
> ```bash cURL theme={null}
> curl -X POST "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/" \
>   -H "x-access-token: YOUR_SECRET_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "transaction_id": "TXN-CARD-12345678",
>     "amount": 99.13,
>     "currency": "NGN",
>     "transaction_type": "card",
>     "account_type": "corporate",
>     "timestamp": "2025-08-23T14:30:00Z",
>     "card_details": {
>       "bin": 345676,
>       "last4": 9809
>     },
>     "merchant_details": {
>       "merchant_name": "ABC Stores",
>       "merchant_location": "Lagos, Nigeria",
>       "merchant_mcc": "5813"
>     },
>     "customer_details": {
>       "customer_name": "Imagine Dragons",
>       "customer_email": "imaginedragons@gmail.com",
>       "customer_phone": "+2347012345678",
>       "identifier": "98765432109",
>       "identifier_type": "bvn"
>     },
>     "additional_info": {
>       "ip_address": "102.89.1.1",
>       "location": "Lagos, Nigeria",
>       "transaction_description": "Online purchase"
>     },
>     "run_kyc": false
>   }'
> ```
>
> ```javascript Node.js theme={null}
> const response = await fetch(
>   "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/",
>   {
>     method: "POST",
>     headers: {
>       "x-access-token": "YOUR_SECRET_KEY",
>       "Content-Type": "application/json",
>     },
>     body: JSON.stringify({
>       transaction_id: "TXN-CARD-12345678",
>       amount: 99.13,
>       currency: "NGN",
>       transaction_type: "card",
>       account_type: "corporate",
>       timestamp: "2025-08-23T14:30:00Z",
>       card_details: {
>         bin: 345676,
>         last4: 9809,
>       },
>       merchant_details: {
>         merchant_name: "ABC Stores",
>         merchant_location: "Lagos, Nigeria",
>         merchant_mcc: "5813",
>       },
>       customer_details: {
>         customer_name: "Imagine Dragons",
>         customer_email: "imaginedragons@gmail.com",
>         customer_phone: "+2347012345678",
>         identifier: "98765432109",
>         identifier_type: "bvn",
>       },
>       additional_info: {
>         ip_address: "102.89.1.1",
>         location: "Lagos, Nigeria",
>         transaction_description: "Online purchase",
>       },
>       run_kyc: false,
>     }),
>   }
> );
> const data = await response.json();
> ```
>
> ```python Python theme={null}
> import requests
>
> response = requests.post(
>     "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/",
>     headers={
>         "x-access-token": "YOUR_SECRET_KEY",
>         "Content-Type": "application/json",
>     },
>     json={
>         "transaction_id": "TXN-CARD-12345678",
>         "amount": 99.13,
>         "currency": "NGN",
>         "transaction_type": "card",
>         "account_type": "corporate",
>         "timestamp": "2025-08-23T15:30:00Z",
>         "card_details": {
>             "bin": 345676,
>             "last4": 9809,
>         },
>         "merchant_details": {
>             "merchant_name": "ABC Stores",
>             "merchant_location": "Lagos, Nigeria",
>             "merchant_mcc": "5813",
>         },
>         "customer_details": {
>             "customer_name": "Imagine Dragons",
>             "customer_email": "imaginedragons@gmail.com",
>             "customer_phone": "+2347012345678",
>             "identifier": "98765432109",
>             "identifier_type": "bvn",
>         },
>         "additional_info": {
>             "ip_address": "102.89.1.1",
>             "location": "Lagos, Nigeria",
>             "transaction_description": "Online purchase",
>         },
>         "run_kyc": False,
>     },
> )
> data = response.json()
> ```

> [!NOTE]
>
> **Recommended for all new integrations**: pass `identifier` and `identifier_type` inside `customer_details`. This single field pair supports BVN (Nigeria), national ID (Kenya), Ghana card, and other country ID types.
>
> **Backward compatible**: integrations that previously sent a `bvn` field can continue to do so. See the [legacy example](#legacy-passing-bvn-directly) below.

### Legacy: passing `bvn` directly

> [!WARNING]
>
> The top-level `bvn` field is legacy and only supports BVN (Nigeria). New integrations, both in Nigeria and outside Nigeria, should use `customer_details.identifier` + `customer_details.identifier_type` instead. The legacy field is kept active for backward compatibility and will be removed in a future release.

The following payload uses the legacy `bvn` field instead of the new `identifier` pair. It still works.

```bash cURL theme={null}
curl -X POST "https://adhere-api.smartcomply.com/api/v1/monitoring/transaction_monitoring/" \
  -H "x-access-token: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "LEGACY-001",
    "amount": 50000,
    "currency": "NGN",
    "transaction_type": "transfer",
    "account_type": "individual",
    "origin_account": {
      "account_number": "9876543219",
      "bank_code": "001"
    },
    "destination_account": {
      "account_number": "123456789",
      "bank_code": "002"
    },
    "customer_details": {
      "customer_name": "Legacy Customer",
      "customer_email": "legacy@example.com",
      "bvn": "22430372151",
    },
    "additional_info": {
      "ip_address": "192.168.1.1",
      "location": "Lagos, Nigeria"
    }
  }'
```

## Response

The response is identical across all `transaction_type` values.

### Activity Codes

**Suspicious (flag for review):**

| Code | Description |
| - | - |
| `450` | Suspicious Transaction Detected — Requires Manual Review |
| `451` | High-Risk Transaction — Potential Fraud |
| `452` | Unusual Transaction Behavior — Pattern Anomaly |
| `453` | Velocity Check Failed — Too Many Transactions in Short Time |
| `454` | Geographic Inconsistency — Unusual Location |
| `455` | Transaction Amount Too High — Above Threshold |
| `456` | Blacklisted Account or Entity |
| `457` | Repeated Failed Transactions — Possible Fraud Attempt |

**Safe:**

| Code | Description |
| - | - |
| `200` | Transaction Approved — No Issues |
| `201` | Transaction Successfully Processed |
| `202` | Transaction Pending Review — Routine Check |
| `210` | Trusted Transaction — Verified and Safe |
| `211` | Low-Risk Transaction — No Anomalies Detected |
| `212` | Recurring Transaction Approved — Previously Authorized Pattern |
| `220` | Whitelisted Entity — Pre-approved Account or Business |
| `221` | Known Customer — Transaction Aligns with User History |

### 201 Created

```json theme={null}
{
  "status": "Success",
  "data": {
    "activity_code": "450",
    "status": "suspicious",
    "comment": ["4 rule(s) triggered"]
  },
  "message": "Transaction was successfully processed"
}
```

### 400 Bad Request

```json theme={null}
{
  "status": "failed",
  "data": [],
  "message": "Sorry, your check cannot be processed at the moment. Please try again in a few minutes"
}
```

### 401 Unauthorized

```json theme={null}
{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.