Submit Transaction for Monitoring - Adhere by Smartcomply

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

Transfer
USSD
Web
Card

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

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
  }'

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();

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()

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

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
  }'

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

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
  }'

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

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
  }'

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();

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()

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 below.

Legacy: passing `bvn` directly

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.

cURL

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

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

400 Bad Request

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

401 Unauthorized

{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}

​Endpoint

​Request

​Headers

​Common Body Parameters

​Type-Specific Parameters

​Example

​Example

​Example

​Example

​Legacy: passing bvn directly

​Response

​Activity Codes

​201 Created

​400 Bad Request

​401 Unauthorized

Endpoint

Request

Headers

Common Body Parameters

Type-Specific Parameters

Example

Example

Example

Example

Legacy: passing `bvn` directly

Response

Activity Codes

201 Created

400 Bad Request

401 Unauthorized