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

Recommended Flow

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:

Get Bank Codes endpoint - Fetch list of Nigerian banks
Name Enquiry endpoint - Validate bank account details

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

Error	Cause	Solution
Invalid account number	Account doesn’t exist or wrong number	Ask user to verify their account number
Invalid bank code	Bank code doesn’t match any Nigerian bank	Ensure you’re using the NIP bank code from the bank list
Account verification failed	Temporary issue with bank API	Retry after a short delay
Rate limit exceeded	Too many requests	Implement rate limiting in your application

Example Error Response

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

Best Practices

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

Security Considerations

API Key Protection: Never expose your API key in frontend code
Backend Validation: Always verify account details on your backend
Rate Limiting: Implement rate limiting to prevent abuse
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

View beneficiary formats for all currencies
Learn how to create quotes
Explore quote examples for different currency pairs
Set up webhook notifications for payment tracking

Get Started

Payouts

Stablecoins

Webhooks

Guides

Name Enquiry Guide

Name Enquiry Implementation Guide

API Reference

Recommended Flow

1. Fetch List of Supported Banks

2. Let User Select Their Bank

3. Collect Account Number

4. Verify Account Details

5. Display for Confirmation

6. Create Quote with Validated Details

Complete Implementation Example

React/Next.js Example

Node.js/Express Example

API Endpoints Reference

Quick Reference

Error Handling

Common Errors

Example Error Response

Best Practices

Security Considerations

Limitations

Name Enquiry API

Get Bank Codes API

Beneficiary Formats

Create Quote

Next Steps

​Name Enquiry Implementation Guide

API Reference

​Recommended Flow

​1. Fetch List of Supported Banks

​2. Let User Select Their Bank

​3. Collect Account Number

​4. Verify Account Details

​5. Display for Confirmation

​6. Create Quote with Validated Details

​Complete Implementation Example

​React/Next.js Example

​Node.js/Express Example

​API Endpoints Reference

​Quick Reference

​Error Handling

​Common Errors

​Example Error Response

​Best Practices

​Security Considerations

​Limitations

​Related Documentation

Name Enquiry API

Get Bank Codes API

Beneficiary Formats

Create Quote

​Next Steps

Name Enquiry Implementation Guide

Recommended Flow

1. Fetch List of Supported Banks

2. Let User Select Their Bank

3. Collect Account Number

4. Verify Account Details

5. Display for Confirmation

6. Create Quote with Validated Details

Complete Implementation Example

React/Next.js Example

Node.js/Express Example

API Endpoints Reference

Quick Reference

Error Handling

Common Errors

Example Error Response

Best Practices

Security Considerations

Limitations

Related Documentation

Next Steps