Nigerian Naira (NGN) Payouts

This guide explains how to integrate Mavapay’s payout functionality for sending money to Nigerian bank accounts.

To pay an NGN payout from your USDT wallet, set sourceCurrency to USDTCENT, sourceWallet to USDT, and settlementCurrency to USDT. Then accept the quote. See Prefunded Quote.

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

Collections

Stablecoins

Crypto Swaps

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