⚡ NDAPI v1.0
Accept NGN Payments
via Nolubz Infrastructure
NDAPI gives any business access to Nolubz's payment rails — collect NGN via virtual accounts, verify bank details, and initiate transfers instantly.
1.5%
Deposit fee
0%
Setup cost
Real-time
Webhook delivery
Onboarding
Getting started with NDAPI takes less than 24 hours.
1
Contact Nolubz
Reach out to our team at admin@nolubz.com or via your account manager to initiate onboarding.
2
Sign the Agreement
Review and sign the NDAPI Service Level Agreement outlining fees, obligations and usage terms.
3
Receive Credentials
We provision your Test and Live API keys, webhook secret and dedicated Nomba sub-account within 24 hours.
4
Build & Test
Integrate using your Test key — no real money moves. Once satisfied, switch to your Live key.
5
Go Live
We verify your integration and activate your Live key. You're ready to accept real NGN payments.
Credentials
Each operator receives a unique set of credentials upon onboarding.
Your Credentials — provided upon onboarding
Test API Key
NDAPI-TEST-••••••••••••••••••••••••••••••••
Live API Key
NDAPI-LIVE-•••••••••••••••••••••••••••••••• (after go-live)
Webhook Secret
NDAPI-WH-••••••••••••••••••••••••••••••••••••••••••
Base URL (Test)
https://sandbox.ndapi.nolubz.com
Base URL (Live)
https://ndapi.nolubz.com/v1
Documentation
https://ndapi.nolubz.com/docs
⚠️ Never expose your API keys in client-side code, mobile apps or public repositories.
Authentication
Pass your API key in the Authorization header on every request.
HTTP Header
Authorization: Bearer YOUR_NDAPI_KEY
ℹ️ Keys starting with
NDAPI-TEST- run in test mode. Keys starting with NDAPI-LIVE- process real transactions.
Fee Structure
Transparent pricing — fees are deducted automatically from each transaction.
Deposit Fees
| Transaction Type | Fee | Who Pays |
|---|---|---|
| NGN Virtual Account Deposit | 1.5% | Deducted from received amount |
Withdrawal Fees
Withdrawal fees are negotiated per operator based on monthly volume.
| Monthly Volume | Fee Range |
|---|---|
| Standard | 0.075% – 0.25% |
| Contact your account manager for volume-based pricing | |
✅ Internal Nolubz-to-Nolubz transfers are free of charge.
Error Handling
All errors return a consistent JSON structure.
{
"error": "Insufficient balance. Available: ₦4,500"
}
| HTTP Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request — check your parameters |
| 401 | Unauthorized — invalid or missing API key |
| 409 | Conflict — duplicate reference |
| 500 | Server error — contact support |
Virtual Accounts
Generate a dynamic NGN virtual account for your user to pay into. The account is tied to your unique reference.
POST
/v1/virtual-accounts
Create virtual account
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | Required | Your unique transaction reference |
| amount | number | Optional | Expected NGN amount |
| description | string | Optional | Transaction description |
| expires_in_mins | number | Optional | VA expiry in minutes (default: 30) |
cURL
curl -X POST https://sandbox.ndapi.nolubz.com/v1/virtual-accounts \
-H "Authorization: Bearer YOUR_NDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "ORDER-12345",
"amount": 5000,
"description": "Payment for order #12345",
"expires_in_mins": 30
}'
Response
{
"success": true,
"mode": "live",
"data": {
"account_number": "7834921056",
"account_name": "NOLUBZ/YOUR BUSINESS NAME",
"bank_name": "Nomba MFB",
"currency": "NGN",
"reference": "ORDER-12345",
"expires_at": "2026-09-10T04:00:00.000Z",
"amount_expected": 5000,
"instructions": "Transfer ₦5,000 to this account. Funds credited instantly."
}
}
200 OK
400 Bad Request
401 Unauthorized
Balance
Check your current NGN balance and account statistics.
GET
/v1/balance
Get account balance
cURL
curl -X GET https://sandbox.ndapi.nolubz.com/v1/balance \
-H "Authorization: Bearer YOUR_NDAPI_KEY"
Response
{
"success": true,
"data": {
"operator_name": "Your Business Name",
"balance": {
"available_ngn": 245000,
"total_deposits_ngn": 500000,
"total_withdrawals_ngn": 255000
},
"account": {
"nomba_account_number": "XXXXXXXXXX",
"deposit_fee_pct": 1.5,
"withdrawal_fee_range": "0.075% - 0.25%"
},
"timestamp": "2026-09-10T01:00:00.000Z"
}
}
Transfers
Initiate NGN bank transfers to any Nigerian bank account.
ℹ️ Use a unique
reference per transfer. Reuse the same reference to safely retry without duplicate payouts.
POST
/v1/transfers
Initiate bank transfer
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount_ngn | number | Required | Amount in NGN to transfer |
| account_number | string | Required | Recipient bank account number |
| bank_code | string | Required | Bank code (e.g. "058" for GTB) |
| reference | string | Required | Unique idempotency reference |
| account_name | string | Optional | Recipient account name |
| bank_name | string | Optional | Recipient bank name |
| narration | string | Optional | Transfer description |
cURL
curl -X POST https://sandbox.ndapi.nolubz.com/v1/transfers \
-H "Authorization: Bearer YOUR_NDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_ngn": 5000,
"account_number": "0040883309",
"bank_code": "058",
"account_name": "John Doe",
"bank_name": "Guaranty Trust Bank",
"reference": "PAYOUT-001",
"narration": "Payout for order #12345"
}'
Response
{
"success": true,
"mode": "live",
"data": {
"reference": "PAYOUT-001",
"amount_ngn": 5000,
"fee_ngn": 8.125,
"net_amount_ngn": 4991.875,
"status": "SUCCESS",
"transaction_id": 42
}
}
200 OK
400 Insufficient Balance
401 Unauthorized
Transactions
Retrieve your full transaction history with daily, weekly and monthly filters.
GET
/v1/transactions
List transactions
| Query Param | Type | Options | Description |
|---|---|---|---|
| period | string | day, week, month | Filter by time period (default: month) |
| type | string | deposit, withdrawal | Filter by transaction type |
| page | number | 1, 2, 3... | Page number (default: 1) |
| limit | number | 1–100 | Results per page (default: 50) |
cURL
curl -X GET "https://sandbox.ndapi.nolubz.com/v1/transactions?period=day&type=deposit&page=1" \
-H "Authorization: Bearer YOUR_NDAPI_KEY"
Response
{
"success": true,
"data": {
"period": "day",
"summary": {
"total_deposits_ngn": 125000,
"total_withdrawals_ngn": 80000,
"total_fees_ngn": 1875,
"transaction_count": 8
},
"transactions": [ ... ],
"pagination": {
"page": 1, "limit": 50,
"total": 8, "total_pages": 1
}
}
}
Webhooks
Receive real-time POST notifications to your endpoint when events occur.
Setup
Provide your webhook URL during onboarding or contact your account manager to update it. We sign every request with your webhook secret.
Events
| Event | Trigger |
|---|---|
| payment.received | A deposit was received and credited to your balance |
| transfer.success | A withdrawal completed successfully |
| transfer.failed | A withdrawal failed — balance automatically restored |
Verification
Verify every webhook using HMAC-SHA256 with your webhook secret. Always verify before processing.
Node.js
const crypto = require('crypto')
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('base64')
return crypto.timingSafeEqual(
Buffer.from(expected), Buffer.from(signature)
)
}
app.post('/webhook', express.json(), (req, res) => {
const sig = req.headers['x-ndapi-signature']
const secret = process.env.NDAPI_WEBHOOK_SECRET
if (!verifyWebhook(req.body, sig, secret)) {
return res.status(401).json({ error: 'Invalid signature' })
}
const { event, data } = req.body
switch(event) {
case 'payment.received':
// Credit user in your system
console.log(`₦${data.net_amount_ngn} received for ${data.reference}`)
break
case 'transfer.failed':
// Balance restored — notify your user
break
}
res.json({ received: true })
})
Webhook Payload — payment.received
{
"event": "payment.received",
"data": {
"reference": "ORDER-12345",
"amount_ngn": 5000,
"fee_ngn": 75,
"net_amount_ngn": 4925,
"account_number": "7834921056",
"transaction_id": 42,
"timestamp": "2026-09-10T01:23:45.000Z"
}
}
Test Mode
Build and verify your integration without moving real money.
| Feature | Test Mode | Live Mode |
|---|---|---|
| API calls | ✅ Full support | ✅ Full support |
| Virtual accounts | Simulated numbers | Real partner bank accounts |
| Deposits | No real money | Real NGN |
| Transfers | Simulated success | Real bank transfers |
| Webhooks | ✅ Delivered | ✅ Delivered |
| Fees | Shown, not charged | Charged per transaction |
Support
Our team is available to help with your integration.
Technical Support
For integration help, API issues or account questions.
admin@nolubz.com
Become an Operator
Want to integrate NDAPI into your platform? Get in touch.
hello@nolubz.com