Viscount Payment APIs

Getting Started

To integrate Viscount Payment APIs, you must complete a simple onboarding process to ensure compliance and secure access. This process involves creating a corporate account and completing Know Your Customer (KYC) verification before API credentials are issued.

API Environments

Viscount provides two distinct environments to support a robust development lifecycle. This separation ensures your integration is stable and thoroughly tested before processing real financial transactions in production.

Security & Authentication

The Viscount Payment API employs a multi-layered authentication and validation framework designed to ensure the security, integrity, and reliability of all transactions. Every API request must satisfy all three security layers before it is processed.

Request Key Generation

The Request Key is a unique identifier included in every API request to enable idempotency control. It is constructed by concatenating five segments, producing a 99-character string that is virtually impossible to duplicate across requests.

Key Structure

Each Request Key must be unique. Reusing a key triggers the idempotency mechanism and returns the cached response from the original request.

Implementation — PHP

Copyfunction generateRequestKey(): string
{
     = date('YmdHis');
     = [];
     = 1000;
    for ( = 0;  < 6; ++) {
         = min( - (6 - ), 9999);
         = rand(1, );
        [] = ;
         -= ;
    }
    [] = ;
     = implode('', array_map(
        fn() => str_pad(, 4, '0', STR_PAD_LEFT), 
    ));
     = '';
    for ( = 0;  < 7; ++)  .= chr(rand(65, 90));
     = '';
    for ( = 0;  < 30; ++)  .= rand(0, 9);
     = '';
    for ( = 0;  < 20; ++)  .= chr(rand(65, 90));
    return  .  .  .  . ;
}

Implementation — JavaScript

Copyfunction generateRequestKey() {
    const now = new Date();
    const pad = (n, l = 2) => String(n).padStart(l, '0');
    const date = now.getFullYear()
        + pad(now.getMonth() + 1) + pad(now.getDate())
        + pad(now.getHours()) + pad(now.getMinutes())
        + pad(now.getSeconds());
    const numbers = [];
    let remaining = 1000;
    for (let i = 0; i < 6; i++) {
        const max = Math.min(remaining - (6 - i), 9999);
        const n = Math.floor(Math.random() * max) + 1;
        numbers.push(n);
        remaining -= n;
    }
    numbers.push(remaining);
    const numBlock = numbers.map(n => String(n).padStart(4, '0')).join('');
    const randChar = () => String.fromCharCode(65 + Math.floor(Math.random() * 26));
    const alpha1 = Array.from({ length: 7 }, randChar).join('');
    const digits = Array.from({ length: 30 }, () => Math.floor(Math.random() * 10)).join('');
    const alpha2 = Array.from({ length: 20 }, randChar).join('');
    return date + numBlock + alpha1 + digits + alpha2;
}

Collecting Payment

Viscount enables you to collect payments through two primary channels: Bank Transfers (via virtual accounts) and Direct Debits. Both channels are accessible through the API, with real-time transaction notifications delivered via webhooks.

Making Payments

The Viscount Payment API enables you to send money to any bank account in Nigeria — whether to another Viscount account (internal transfer) or to any other commercial bank (external transfer via NIBSS).

Single Transfers allow you to initiate individual payments in real time. Each transfer is processed instantly and assigned a unique reference for tracking. You can optionally flag a transfer as requiring approval before processing, enabling a maker-checker workflow.

Bulk Transfers allow you to send payments to multiple recipients in a single API call by creating a transfer batch. Ideal for salary disbursements, vendor payments, and commission payouts. Each transfer within a batch is tracked individually, and you can approve or cancel an entire batch before processing. All transfers support full verification, real-time status tracking, and webhook notifications upon completion.

Response Format

The Viscount Payment API returns consistent, predictable JSON responses. There are two possible HTTP status codes, each with a defined structure.

{
  "status": "success",
  "message": "Successful",
  "data": {
    "reference": "VST20260411143200",
    "transaction_id": "TXN_0012345",
    "amount": 50000
  }
}

{
  "status": "error",
  "message": "Invalid source account number."
}

Webhooks

Webhooks allow Viscount to notify your application in real time when events occur on your account. Rather than polling the API for status updates, your server receives an immediate POST notification.

Configure your webhook URL through the Corporate Internet Banking portal. When an event occurs, Viscount sends a POST request with a JSON body containing the event type, associated data, and a timestamp.

Supported Events

Example Payloads

Successful Credit

{
  "event_type": "transaction-new",
  "data": {
    "transaction_id": "TXN_0012345",
    "account_number": "82791089010",
    "reference": "de92ui22",
    "transaction_type": "CREDIT"
  },
  "timestamp": "2026-04-11T14:23:45+00:00"
}

Successful Transfer

{
  "event_type": "transfer-successful",
  "data": { "reference": "de92ui22" },
  "timestamp": "2026-04-11T14:23:45+00:00"
}

Webhook Security

Set a secret hash stored as an environment variable. Viscount signs each payload with HMAC-SHA256 using this hash. The signature is included in the X-Viscount-Signature header. Compute the hash of the raw body and compare.

Verification — Python (Flask)

Copyimport hmac, hashlib, os

secret = os.environ['VISCOUNT_WEBHOOK_SECRET']
payload = request.get_data()
signature = request.headers.get('X-Viscount-Signature', '')
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, signature):
    abort(401)

event = request.get_json()

Verification — Node.js (Express)

Copyconst crypto = require('crypto');
const secret = process.env.VISCOUNT_WEBHOOK_SECRET;
const signature = req.headers['x-viscount-signature'];
const expected = crypto.createHmac('sha256', secret)
    .update(req.rawBody).digest('hex');

if (signature !== expected)
    return res.status(401).send('Invalid signature');

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

Virtual Accounts

Create, update, and query virtual accounts for payment collection. All requests are POST to /virtual-accounts.

{ "action": "CREATE_ACCOUNT", "parent_account_number": "1000211487", "account_name": "ADEDEJI AWOLOLA", "account_type_code": "VIRTUAL_ACCOUNT" }

{ "action": "UPDATE_ACCOUNT_NUMBER", "account_number": "1000211576", "status": "INACTIVE" }

{ "action": "ACCOUNT_ENQUIRY", "account_number": "1000211576", "start_date": "2026-01-01", "end_date": "2026-01-31" }

Transactions

Verify the status and details of any transaction. Essential for confirming payments, resolving disputes, and maintaining records.

{ "action": "VERIFY_TRANSACTION", "account_number": "1000211576", "transaction_id": "20260402195705CDLCCWDWKJ", "reference": "000966444324566658283981389895" }

Money Transfer

Name lookups, single transfers, batch payments, and transfer status tracking. All requests are POST to /money-transfer.

{ "action": "NAME_ENQUIRY", "account_number": "1000211487", "account_type": "VISCOUNT", "bank_code": "00057" }

{ "action": "SEND_MONEY", "account_number": "1000211521", "account_type": "VISCOUNT", "amount": 1000, "subject_to_approval": "NO", "from_account_number": "1000211487", "reference": "678986568909MMKLOdPP", "narration": "Vendor payment" }

{ "action": "CREATE_TRANSFER_BATCH", "from_account_number": "1000211487", "batch_title": "SALARY PAYMENT", "transfers": [{ "account_number": "1000211497", "type": "VISCOUNT", "amount": 8000, "narration": "SALARY", "bank_code": "" }] }

{ "action": "APPROVE_TRANSFER_BATCH", "batch_id": "051126260411202537782393912540" }

{ "action": "CANCEL_TRANSFER_BATCH", "batch_id": "051126260411202537782393912540" }

{ "action": "GET_TRANSFER_BATCH", "batch_id": "051126260411205427287611731074" }

{ "action": "TRANSFER_STATUS", "reference": "051126260411205427515805070443" }

Direct Debits

Create mandates, execute debits, and manage mandate lifecycle. All requests are POST to /direct-debit.

{ "action": "INITIATE", "account_number": "1000211487", "narration": "Monthly subscription", "amount": 5000, "account_type": "VISCOUNT", "settlement_account_number": "1000211545", "bank_code": "", "type": "ONE_TIME", "start_date": "", "end_date": "" }

{ "action": "DEBIT_MANDATE", "mandate_id": "1000211487", "amount": 5000 }

{ "action": "CANCEL_MANDATE", "mandate_id": "1000211487" }