Skip to main content

​
Name Enquiry Implementation Guide

This guide shows you how to implement bank account validation for Nigerian Naira (NGN) payouts using Mavapay’s Name Enquiry API.
Name enquiry is currently supported for Nigerian Naira (NGN) accounts only.

API Reference

View the complete API documentation for the Name Enquiry endpoint
 Follow this flow to collect and validate beneficiary bank details:

​
1. Fetch List of Supported Banks

Get all Nigerian banks with their NIP bank codes using the Get Bank Codes endpoint. 
GET /api/v1/bank/bankcode?country=NG
Response: 
{
  "status": "ok",
  "message": "All bank codes",
  "data": [
    { "bankName": "ACCESS BANK", "nipBankCode": "000014" },
    { "bankName": "GUARANTY TRUST BANK", "nipBankCode": "000013" },
    { "bankName": "FIRST BANK OF NIGERIA", "nipBankCode": "000016" },
    { "bankName": "ZENITH BANK", "nipBankCode": "000015" },
    { "bankName": "UNITED BANK FOR AFRICA", "nipBankCode": "000004" },
    { "bankName": "KUDA MICROFINANCE BANK", "nipBankCode": "090267" },
    ...
  ]
}

​
2. Let User Select Their Bank

Present the list of banks to your user and let them select their bank. Store the bank name and NIP bank code. 
// Example: Display banks in a dropdown
const banks = response.data.sort((a, b) => 
  a.bankName.localeCompare(b.bankName)
);

// User selects: GUARANTY TRUST BANK (000013)
const selectedBank = {
  name: "GUARANTY TRUST BANK",
  code: "000013"
};

​
3. Collect Account Number

Ask the user to enter their 10-digit Nigerian bank account number. 
const accountNumber = "0123456789"; // User input

​
4. Verify Account Details

Call the Name Enquiry endpoint to get the account name. 
GET /api/v1/bank/name-enquiry?accountNumber=0123456789&bankCode=000013
Response: 
{
  "status": "ok",
  "message": "Account name retrieved successfully",
  "data": {
    "accountName": "OLADEJI OLAOLU",
    "accountNumber": "0123456789",
    "bankCode": "000013"
  }
}

​
5. Display for Confirmation

Show the retrieved account name to the user for confirmation. 
// Display to user:
"Please confirm the account details:
 Bank: GUARANTY TRUST BANK
 Account Number: 0123456789
 Account Name: OLADEJI OLAOLU
 
 Is this correct? [Yes] [No]"

​
6. Create Quote with Validated Details

Once confirmed, use the validated details to create a quote. 
{
  "amount": "1000000",
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "NGNKOBO",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "NGNKOBO",
  "autopayout": true,
  "beneficiary": {
    "bankAccountName": "OLADEJI OLAOLU",
    "bankCode": "000013",
    "bankName": "GUARANTY TRUST BANK",
    "bankAccountNumber": "0123456789"
  }
}

​
Complete Implementation Example

​
React/Next.js Example

import { useState } from 'react';

interface Bank {
  bankName: string;
  nipBankCode: string;
}

export function BankAccountForm() {
  const [banks, setBanks] = useState<Bank[]>([]);
  const [selectedBank, setSelectedBank] = useState<Bank | null>(null);
  const [accountNumber, setAccountNumber] = useState('');
  const [accountName, setAccountName] = useState('');
  const [loading, setLoading] = useState(false);

  // Step 1: Fetch banks
  const fetchBanks = async () => {
    const response = await fetch(
      'https://api.mavapay.co/api/v1/bank/bankcode?country=NG',
      {
        headers: { 'X-API-KEY': process.env.MAVAPAY_API_KEY }
      }
    );
    const data = await response.json();
    setBanks(data.data.sort((a, b) => 
      a.bankName.localeCompare(b.bankName)
    ));
  };

  // Step 4: Verify account
  const verifyAccount = async () => {
    if (!selectedBank || accountNumber.length !== 10) {
      alert('Please select a bank and enter a valid account number');
      return;
    }

    setLoading(true);
    try {
      const response = await fetch(
        `https://api.mavapay.co/api/v1/bank/name-enquiry?accountNumber=${accountNumber}&bankCode=${selectedBank.nipBankCode}`,
        {
          headers: { 'X-API-KEY': process.env.MAVAPAY_API_KEY }
        }
      );
      const data = await response.json();
      
      if (data.status === 'ok') {
        setAccountName(data.data.accountName);
      } else {
        alert('Failed to verify account. Please check the details.');
      }
    } catch (error) {
      alert('Error verifying account');
    } finally {
      setLoading(false);
    }
  };

  // Step 6: Create quote
  const createQuote = async () => {
    const response = await fetch(
      'https://api.mavapay.co/api/v1/quote',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-KEY': process.env.MAVAPAY_API_KEY
        },
        body: JSON.stringify({
          amount: "1000000",
          sourceCurrency: "BTCSAT",
          targetCurrency: "NGNKOBO",
          paymentMethod: "LIGHTNING",
          paymentCurrency: "NGNKOBO",
          autopayout: true,
          beneficiary: {
            bankAccountName: accountName,
            bankCode: selectedBank.nipBankCode,
            bankName: selectedBank.bankName,
            bankAccountNumber: accountNumber
          }
        })
      }
    );
    const data = await response.json();
    // Handle quote response...
  };

  return (
    <div>
      <select onChange={(e) => {
        const bank = banks.find(b => b.nipBankCode === e.target.value);
        setSelectedBank(bank || null);
      }}>
        <option value="">Select Bank</option>
        {banks.map(bank => (
          <key={bank.nipBankCode} value={bank.nipBankCode}>
            {bank.bankName}
          </option>
        ))}
      </select>

      <input
        type="text"
        placeholder="Account Number"
        value={accountNumber}
        onChange={(e) => setAccountNumber(e.target.value)}
        maxLength={10}
      />

      <button onClick={verifyAccount} disabled={loading}>
        {loading ? 'Verifying...' : 'Verify Account'}
      </button>

      {accountName && (
        <div>
          <p>Account Name: {accountName}</p>
          <button onClick={createQuote}>Proceed to Payment</button>
        </div>
      )}
    </div>
  );
}

​
Node.js/Express Example

const express = require('express');
const router = express.Router();

// Step 1: Get banks
router.get('/banks', async (req, res) => {
  const response = await fetch(
    'https://api.mavapay.co/api/v1/bank/bankcode?country=NG',
    {
      headers: { 'X-API-KEY': process.env.MAVAPAY_API_KEY }
    }
  );
  const data = await response.json();
  res.json(data);
});

// Step 4: Verify account
router.post('/verify-account', async (req, res) => {
  const { accountNumber, bankCode } = req.body;

  if (!accountNumber || accountNumber.length !== 10) {
    return res.status(400).json({ error: 'Invalid account number' });
  }

  try {
    const response = await fetch(
      `https://api.mavapay.co/api/v1/bank/name-enquiry?accountNumber=${accountNumber}&bankCode=${bankCode}`,
      {
        headers: { 'X-API-KEY': process.env.MAVAPAY_API_KEY }
      }
    );
    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: 'Verification failed' });
  }
});

module.exports = router;

​
API Endpoints Reference

For complete API documentation, see:

​
Quick Reference

Get Bank Codes: 
GET /api/v1/bank/bankcode?country=NG
Name Enquiry: 
GET /api/v1/bank/name-enquiry?accountNumber={accountNumber}&bankCode={bankCode}

​
Error Handling

​
Common Errors

ErrorCauseSolution
Invalid account numberAccount doesn’t exist or wrong numberAsk user to verify their account number
Invalid bank codeBank code doesn’t match any Nigerian bankEnsure you’re using the NIP bank code from the bank list
Account verification failedTemporary issue with bank APIRetry after a short delay
Rate limit exceededToo many requestsImplement rate limiting in your application

​
Example Error Response

{
  "status": "error",
  "message": "Invalid account number or bank code"
}

​
Best Practices

  1. Cache Bank List: Fetch and cache the bank list instead of fetching on every page load
  2. Validate Before Enquiry: Check account number is exactly 10 digits before calling API
  3. Show Loading State: Display loading indicator during verification
  4. Handle Errors Gracefully: Provide clear error messages to users
  5. Confirm Before Proceeding: Always show retrieved name for user confirmation
  6. Store Validated Data: Save validated beneficiary details for future use

​
Security Considerations

  1. API Key Protection: Never expose your API key in frontend code
  2. Backend Validation: Always verify account details on your backend
  3. Rate Limiting: Implement rate limiting to prevent abuse
  4. Input Validation: Validate all user inputs before making API calls

​
Limitations

  • Only available for Nigerian (NGN) bank accounts
  • Not available for South African Rand (ZAR) or Kenyan Shilling (KES)
  • Requires valid NIP bank code
  • Account must be active and valid

Name Enquiry API

Complete API reference for the Name Enquiry endpoint

Get Bank Codes API

API reference for fetching Nigerian bank codes

Beneficiary Formats

Required formats for all supported currencies

Create Quote

Learn how to create quotes with validated details

​
Next Steps