Specification v1.1

Introduction

This document serves as the technical reference for integrating the NABRoll Payment Gateway. It is designed to assist developers in collecting payments, processing transactions, and handling automated revenue splits.

Base URL (Demo)

https://demo.nabroll.com.ng/api/v1

Authentication

Security is handled via a hashing mechanism. Every request that modifies state or requests sensitive data requires a Hash field.

const crypto = require('crypto');

const CONFIG = {
    publicApiKey: "PK_TEST_...",
    secretApiKey: "SK_TEST_..."
};

function generateHash(dataString) {
    return crypto.createHmac('sha256', CONFIG.secretApiKey)
                 .update(dataString)
                 .digest('hex');
}

<?php
$publicApiKey = "PK_TEST_...";
$secretApiKey = "SK_TEST_...";

function generateHash($dataString, $secretKey) {
    return hash_hmac('sha256', $dataString, $secretKey);
}
?>

import hmac
import hashlib

config = {
    "public_key": "PK_TEST_...",
    "secret_key": "SK_TEST_..."
}

def generate_hash(data_string):
    # Secret key must be bytes
    key_bytes = config["secret_key"].encode('utf-8')
    data_bytes = data_string.encode('utf-8')
    
    return hmac.new(key_bytes, data_bytes, hashlib.sha256).hexdigest()

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class NabRollSecurity {
    private static final String SECRET_KEY = "SK_TEST_...";

    public static String generateHash(String data) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                SECRET_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA256"
            );
            mac.init(secretKeySpec);
            byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            
            StringBuilder sb = new StringBuilder();
            for (byte b : hmacBytes) {
                sb.append(String.format("%02x", b));
            }
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException("Failed to calculate HMAC", e);
        }
    }
}

Hash Generator Playground

Interactive

Payer Ref No

Amount

Public Key

Secret Key (Test Only)

// 1. String to Hash

"0000001200.00PK_TEST_DEMO_KEY"

// 2. Generated HMAC-SHA256

Calculating...

// 3. Payload Preview

...

Initiate Transaction

POST

Generates a unique Transaction Reference (NTR) and a payment code.

/transactions/initiate

Hashing Logic

hashString = payerRefNo + amount + publicApiKey

Concatenate these values in order, then hash.

Key Parameters

PayerRefNo Your unique order ID.
Amount Transaction amount (e.g., "200.00").
ResponseUrl (Optional) Redirect URL after payment.
MetaData (Optional) Extra data or split config.

Example Request

async function initiateTransaction(payerData) {
    const { payerRefNo, amount } = payerData;

    // 1. Generate Hash
    const str = `${payerRefNo}${amount}${CONFIG.publicApiKey}`;
    const hash = generateHash(str);

    // 2. Payload
    const payload = {
        ApiKey: CONFIG.publicApiKey,
        Hash: hash,
        Amount: amount,
        PayerRefNo: payerRefNo,
        PayerName: payerData.name,
        // ... other fields
    };

    // 3. Send
    const res = await fetch(`${CONFIG.baseUrl}/transactions/initiate`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload)
    });
    return await res.json();
}

<?php
$url = "https://demo.nabroll.com.ng/api/v1/transactions/initiate";
$payerRefNo = "0000001";
$amount = "200.00";

// 1. Generate Hash
$hashStr = $payerRefNo . $amount . $publicApiKey;
$hash = hash_hmac('sha256', $hashStr, $secretApiKey);

// 2. Prepare Data
$data = [
    "ApiKey" => $publicApiKey,
    "Hash" => $hash,
    "Amount" => $amount,
    "PayerRefNo" => $payerRefNo,
    "PayerName" => "Sani Bello",
    // ...
];

// 3. Send using CURL
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

import requests
import json

url = "https://demo.nabroll.com.ng/api/v1/transactions/initiate"
payer_ref = "0000001"
amount = "200.00"

# 1. Generate Hash
hash_str = f"{payer_ref}{amount}{config['public_key']}"
hash_val = generate_hash(hash_str)

# 2. Payload
payload = {
    "ApiKey": config["public_key"],
    "Hash": hash_val,
    "Amount": amount,
    "PayerRefNo": payer_ref,
    "PayerName": "Sani Bello",
    # ...
}

# 3. Send Request
response = requests.post(url, json=payload)
print(response.json())

// Uses java.net.http.HttpClient (Java 11+)
String payerRef = "0000001";
String amount = "200.00";

// 1. Generate Hash
String hashStr = payerRef + amount + PUBLIC_KEY;
String hash = generateHash(hashStr);

// 2. Create JSON Payload (Using simple String concatenation for demo)
String jsonInputString = String.format(
    "{\"ApiKey\": \"%s\", \"Hash\": \"%s\", \"Amount\": \"%s\", \"PayerRefNo\": \"%s\"}",
    PUBLIC_KEY, hash, amount, payerRef
);

// 3. Send Request
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://demo.nabroll.com.ng/api/v1/transactions/initiate"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonInputString))
    .build();

HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Verify Transaction

POST

Confirm the status of a transaction before giving value to the user.

/transactions/verify

Hashing Logic

hashString = payerRefNo + amount + transactionRef + publicApiKey

async function verifyTransaction(payerRefNo, amount, transactionRef) {
    const str = `${payerRefNo}${amount}${transactionRef}${CONFIG.publicApiKey}`;
    const hash = generateHash(str);

    const payload = {
        ApiKey: CONFIG.publicApiKey,
        Hash: hash,
        "Transaction Ref": transactionRef // Note the space in the key
    };

    const res = await fetch(`${CONFIG.baseUrl}/transactions/verify`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload)
    });
    
    return await res.json();
}

<?php
$url = "https://demo.nabroll.com.ng/api/v1/transactions/verify";
$txnRef = "862698572355";

// Hash: payerRefNo + amount + txnRef + publicKey
$str = $payerRefNo . $amount . $txnRef . $publicApiKey;
$hash = hash_hmac('sha256', $str, $secretApiKey);

$data = [
    "ApiKey" => $publicApiKey,
    "Hash" => $hash,
    "Transaction Ref" => $txnRef
];

// Execute CURL request...
?>

url = "https://demo.nabroll.com.ng/api/v1/transactions/verify"
txn_ref = "862698572355"

# Hash: payer_ref + amount + txn_ref + public_key
hash_str = f"{payer_ref}{amount}{txn_ref}{config['public_key']}"
hash_val = generate_hash(hash_str)

payload = {
    "ApiKey": config["public_key"],
    "Hash": hash_val,
    "Transaction Ref": txn_ref
}

response = requests.post(url, json=payload)

// Hash: payerRef + amount + txnRef + publicKey
String txnRef = "862698572355";
String hashStr = payerRef + amount + txnRef + PUBLIC_KEY;
String hash = generateHash(hashStr);

String jsonPayload = String.format(
    "{\"ApiKey\": \"%s\", \"Hash\": \"%s\", \"Transaction Ref\": \"%s\"}",
    PUBLIC_KEY, hash, txnRef
);

// Build and send HttpRequest similar to Initiate...

Re-Generate Reference

POST

Use this endpoint if you need to re-issue a reference for an existing order/payerRefNo.

/transactions/inittransactionref

The implementation is identical to Initiate Transaction, using the same hash logic (payerRefNo + amount + publicApiKey).

Web Checkout Flow

Upon successful initiation, redirect the user to:

https://demo.nabroll.com.ng/web/checkout/[PAYMENT_CODE]

Handling the Return

The user is redirected back to your ResponseUrl with these query parameters:

token
Transaction Ref
Msg

Token Validation

You must validate the returned token to ensure the request is genuine.

const str = payerRefNo + paymentCode + amount;
const calculated = md5(str);

if (calculated === token) { /* Valid */ }

$str = $payerRefNo . $paymentCode . $amount;
$token = md5($str);

if ($token === $_GET['token']) { /* Valid */ }

str_val = f"{payer_ref}{payment_code}{amount}"
calculated = hashlib.md5(str_val.encode()).hexdigest()

if calculated == token: # Valid

String str = payerRef + paymentCode + amount;
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] hashInBytes = md.digest(str.getBytes(StandardCharsets.UTF_8));
// Convert bytes to hex string...

Transaction Split

NABRoll allows you to programmatically split settlements between different bank accounts or wallets. This is configured by passing a JSON string in the MetaData field during initiation.

Structure

Split Types

bank_account: Requires Bank Code & Account No.
wallet: Requires Wallet ID.

Deduction Types

Fixed: Exact amount (e.g., "50.00").
Percentage: Rate without symbol (e.g., "5.0").

Implementation Code

const splitConfig = {
    "transaction_split": [
        {
            "split_type": "bank_account",
            "deduction_type": "Fixed",
            "rate": "250.40",
            "bank_code": "058", // GTBank
            "account_no": "0011223344",
            "account_name": "Developer One"
        }
    ]
};

// Add to Initiate Payload
payload.MetaData = JSON.stringify(splitConfig);

Split JSON Generator

Generated JSON String (Copy this to MetaData)

{}

Webhooks & Callbacks

NABRoll pushes payment notifications to your server in real-time.

Retry Policy

The system will retry the notification 4 times within an hour if your server does not respond with HTTP 200.

Response Dictionary

Standard fields returned in API responses.

Field	Type	Description
status	String	Transaction status (e.g., "SUCCESSFUL")
code	String	Response code ("00" for success)
TransactionRef	String	Unique NABRoll reference ID
PaymentCode	String	Unique code for web checkout identification
amount	String	The amount processed (formatted as decimal)
paymentDate	String	Timestamp (YYYY-MM-DD HH:mm:ss)

Troubleshooting

Common response codes and errors you might encounter.

Status Code	Description	Solution
00	Transaction Successful	Proceed to update your database.
401	Unauthorized / Invalid Hash	Check your API Key and ensure Hash generation is correct.
400	Bad Request	Check if all mandatory fields (PayerRefNo, Amount, Mobile) are present.

Code	Bank Name	Code	Bank Name
044	Access Bank	082	Keystone Bank
023	Citi Bank	014	Mainstreet Bank
050	Ecobank	100004	OPAY
070	Fidelity Bank	076	Polaris Bank
011	First Bank	221	Stanbic IBTC
214	FCMB	232	Sterling Bank
058	GTBank	033	UBA
030	Heritage Bank	057	Zenith Bank

Introduction

Authentication

Hash Generator Playground

Initiate Transaction

Hashing Logic

Key Parameters

Example Request

Verify Transaction

Hashing Logic

Re-Generate Reference

Web Checkout Flow

Handling the Return

Token Validation

Transaction Split

Structure

Split Types

Deduction Types

Implementation Code

Split JSON Generator

Webhooks & Callbacks

Retry Policy

Response Dictionary

Troubleshooting

Appendix: CBN Bank Codes