This guide explains how to integrate Mavapay’s payout functionality for sending money to Nigerian bank accounts.
Overview
The NGN payout process involves the following steps:
- Get the list of supported Nigerian banks
- Validate the recipient’s bank account details
- Create a quote for the amount you want to pay out
- Pay the generated lightning invoice
- Receive webhook notifications for payment status
Prerequisites
Before you begin, ensure you have:
- Created a Mavapay account
- Obtained your API key
- Set up your webhook endpoint
- Verified your business account
Authentication
All API requests must include your API key in the header:
X-API-KEY: your_api_key_here
Getting Bank List
First, retrieve the list of supported Nigerian banks:
curl --location 'https://staging.api.mavapay.co/api/v1/bank/bankcode?country=NG' \
--header 'x-api-key: your_api_key_here'
Sample response:
{
"status": "ok",
"message": "all bank codes retrieved successfully",
"data": [
{
"bankName": "KUDA MICROFINANCE BANK",
"nipBankCode": "090267"
}
]
}
Validating Bank Account
Before creating a quote, validate the recipient’s bank account details:
curl --request GET \
--url 'https://staging.api.mavapay.co/api/v1/bank/name-enquiry?accountNumber=0123456789&bankCode=090267' \
--header 'X-API-KEY: your_api_key_here'
Sample response:
{
"status": "ok",
"message": "Bank account name verified successfully",
"data": {
"accountName": "Oladeji Olaolu",
"accountNumber": "0123456789",
"kycLevel": "3",
"nameInquiryReference": "123456789",
"channelCode": "123456789"
}
}
Creating a Quote
Important Notes:
- All amounts are in Kobo (1 NGN = 100 Kobo)
- Minimum payout amount is 2000 NGN
- To send 3000 NGN, use amount = 300000 Kobo
curl --request POST \
--url https://staging.api.mavapay.co/api/v1/quote \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your_api_key_here' \
--data '{
"amount": 300000,
"sourceCurrency": "BTCSAT",
"targetCurrency": "NGNKOBO",
"paymentMethod": "LIGHTNING",
"paymentCurrency": "NGNKOBO",
"autopayout": true,
"beneficiary": {
"bankAccountNumber": "0149203789",
"bankAccountName": "olaolu olajide",
"bankCode": "000013",
"bankName": "GTBANK PLC"
}
}'
Sample response:
{
"status": "success",
"data": {
"id": "d1614a76-9c7f-4111-98a7-43199f307e5b",
"exchangeRate": 5000000.23,
"usdToTargetCurrencyRate": 1500.65,
"sourceCurrency": "BTCSAT",
"targetCurrency": "NGNKOBO",
"transactionFeesInSourceCurrency": 13.23,
"transactionFeesInTargetCurrency": "3750.00",
"amountInSourceCurrency": 1499,
"amountInTargetCurrency": "50000.00",
"paymentMethod": "LIGHTNING",
"expiry": "2021-07-01T12:00:00Z",
"isValid": true,
"invoice": "lntbs36020n1pnehfzcpp5zc8g9tfpwnmaevh62ak2vu6zjqyt5cpph3gjm4zfyqz9srjjdsaqdz5296k7ar98gsy6ctkvys9qcteyqmnyenr8yunswfdvyer2v3dx33kxe3dvymnsefdv5mnjcm9x5mrydm9vccqcqzpuxqzfvsp5utd7hdfmjp7vw3lc6hal8psqruwcnu89hxfukyzugxh40jhv8xcq9qxpqysgq2lry5dgzu2g04s74tpvctwe37rkprs3k579jw6yt7ncrsg62p29yalw8gf5fawfvpydqv4jjve0nsysfhsxa35dtwug9e6gzxkq0h5gp636wc3",
"hash": "189727ef2e0f35921af7858b96e27cbad960b0ec2bb2a4ab73b6a231f9ce8727",
"totalAmountInSourceCurrency": 1499,
"customerInternalFee": 0,
"createdAt": "2021-07-01T12:00:00Z",
"updatedAt": "2021-07-01T12:00:00Z"
}
}
Understanding the Quote Response
usdToTargetCurrencyRate
: Price of 1 USD in NGN
exchangeRate
: Price of 1 BTC in NGN
amountInSourceCurrency
: Total amount in SATS to be paid (including fees)
amountInTargetCurrency
: Total amount in Kobo to be sent to recipient
transactionFeesInSourceCurrency
: Fees in SATS (included in amountInSourceCurrency)
transactionFeesInTargetCurrency
: Fees in Kobo
expiry
: Invoice validity (5 minutes)
customerInternalFee
: Optional extra fee you can charge (in SATS)
Webhook Events
You’ll receive two webhook events:
payment.received
- When the lightning payment is received
payment.sent
- When the money is sent to the recipient’s bank account
payment.received Event
{
"event": "payment.received",
"data": {
"id": "0b234e32-d5ba-4c2a-8f71-0b820a477f01",
"walletId": "b7e7b823-b572-41d3-86a6-a6872f35c274",
"ref": "f05432ecab06ca0357596af0366de",
"hash": "001f7fb879bb3874eb057dcce06437d45d4020d7f348a36cd583b658e98e07d6",
"amount": 300000,
"fees": 2500,
"currency": "NGN",
"type": "DEPOSIT",
"status": "SUCCESS",
"autopayout": true,
"createdAt": "2025-01-17T13:20:20.575Z",
"updatedAt": "2025-01-17T13:20:20.575Z",
"transactionMetadata": {
"id": "570cba51-d9fd-402a-8b10-5c43e23077d8",
"orderId": "82958-2591",
"bankCode": "09026",
"bankName": "KUDA MICROFINANCE BANK",
"bankAccountName": "OLADEJI OLAOLU",
"bankAccountNumber": "0123456789",
"customerInternalFee": 0,
"createdAt": "2025-02-03T14:18:20.737Z",
"updatedAt": "2025-02-03T14:18:22.777Z"
}
}
}
payment.sent Event
{
"event": "payment.sent",
"data": {
"id": "e6291848-a632-44c8-8398-bf318bbc17de",
"walletId": "b7e7b823-b572-41d3-86a6-a6872f35c274",
"ref": "06679ad012a143407d1685561dd27",
"hash": "001f7fb879bb3874eb057dcce06437d45d4020d7f348a36cd583b658e98e07d6",
"amount": 300000,
"fees": 0,
"currency": "NGN",
"type": "WITHDRAWAL",
"status": "SUCCESS",
"autopayout": true,
"createdAt": "2025-01-17T13:20:21.126Z",
"updatedAt": "2025-01-17T13:20:23.476Z",
"transactionMetadata": {
"id": "570cba51-d9fd-402a-8b10-5c43e23077d8",
"orderId": "82958-2591",
"bankCode": "09026",
"bankName": "KUDA MICROFINANCE BANK",
"bankAccountName": "OLADEJI OLAOLU",
"bankAccountNumber": "0123456789",
"customerInternalFee": 0,
"createdAt": "2025-02-03T14:18:20.737Z",
"updatedAt": "2025-02-03T14:18:22.777Z"
}
}
}
Checking Transaction Status
You can query transactions using the payment hash, orderId, or transaction ID:
# Using hash
curl --location 'https://staging.api.mavapay.co/api/v1/transaction?hash=08f7198fd7dd73c087b4754a20d6f63f5b87bb8fcdc10e4d5cacd27650fce2ba' \
--header 'x-api-key: your_api_key_here'
# Using transaction ID
curl --location 'https://staging.api.mavapay.co/api/v1/transaction?id=7bac35f1-2efc-448b-8a71-0d071da43315' \
--header 'x-api-key: your_api_key_here'
Getting Price Rates
To get current NGN rates:
curl --location 'https://staging.api.mavapay.co/api/v1/price?currency=NGN'
Sample response:
{
"status": "ok",
"data": {
"currency": "NGN",
"timestamp": 1738258609,
"btcPriceInUnitCurrency": 167792701.75015488,
"unitPricePerSat": {
"amount": 1.6779270175015488,
"currencyUnit": "NGNSAT"
},
"unitPricePerUsd": {
"amount": 1596.29641,
"currencyUnit": "NGNUSD"
}
}
}
Testing
Use our staging environment for testing:
https://staging.api.mavapay.co/api/v1
Test bank account details:
- Account Number:
0149200000
- Bank: GTBANK PLC
- Bank Code:
000013
Note: All test environment invoices are signet invoices.
Support
If you need help with integration: