Nigerian Naira (NGN) Payouts

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": "ok",
  "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:

Email: info@mavapay.co
Documentation: https://docs.mavapay.co
API Reference: https://docs.mavapay.co/api-reference

Get Started

Payouts

Webhooks

Guides

Nigerian Naira (NGN) Payouts

Overview

Prerequisites

Authentication

Getting Bank List

Validating Bank Account

Creating a Quote

Understanding the Quote Response

Webhook Events

payment.received Event

payment.sent Event

Checking Transaction Status

Getting Price Rates

Testing

Support

​Overview

​Prerequisites

​Authentication

​Getting Bank List

​Validating Bank Account

​Creating a Quote

​Understanding the Quote Response

​Webhook Events

​payment.received Event

​payment.sent Event

​Checking Transaction Status

​Getting Price Rates

​Testing

​Support

Overview

Prerequisites

Authentication

Getting Bank List

Validating Bank Account

Creating a Quote

Understanding the Quote Response

Webhook Events

payment.received Event

payment.sent Event

Checking Transaction Status

Getting Price Rates

Testing

Support