PHPackages                             nubanstack/nubanstack - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. nubanstack/nubanstack

ActiveLibrary[API Development](/categories/api)

nubanstack/nubanstack
=====================

A PHP package for fetching Nigerian banks and validating account numbers via Paystack API

32PHP

Since Nov 29Pushed 5mo agoCompare

[ Source](https://github.com/thechiddx3/nubanstack)[ Packagist](https://packagist.org/packages/nubanstack/nubanstack)[ RSS](/packages/nubanstack-nubanstack/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Nubanstack
==========

[](#nubanstack)

A simple and elegant PHP package for fetching Nigerian banks and validating account numbers using the Paystack API.

Features
--------

[](#features)

- 🏦 Fetch all Nigerian banks
- ✅ Validate Nigerian bank account numbers (online via Paystack)
- 🔍 **Offline NUBAN validation** - Validate account numbers without API calls
- 🎯 **Bank prediction** - Predict possible banks for any account number
- 🌍 Filter banks by country
- 🚀 Easy to use with simple API
- 🔒 Type-safe with DTO support
- ⚡ Built on Guzzle HTTP client

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- Composer

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require nubanstack/nubanstack
```

Configuration
-------------

[](#configuration)

You'll need a Paystack test secret key to use this package. You can get one for free on your [Paystack Dashboard](https://dashboard.paystack.com/#/settings/developer).

### Option 1: Environment Variable

[](#option-1-environment-variable)

Set your Paystack secret key as an environment variable:

```
export PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here
```

### Option 2: Pass Directly to Constructor

[](#option-2-pass-directly-to-constructor)

```
use Nubanstack\Nubanstack;

$nubanstack = new Nubanstack('sk_test_your_secret_key_here');
```

Usage
-----

[](#usage)

### Fetch All Nigerian Banks

[](#fetch-all-nigerian-banks)

```
use Nubanstack\Nubanstack;

$nubanstack = new Nubanstack();

try {
    $banks = $nubanstack->getBanks();

    foreach ($banks as $bank) {
        echo $bank['name'] . ' - ' . $bank['code'] . PHP_EOL;
    }
} catch (\Nubanstack\Exceptions\NubanstackException $e) {
    echo "Error: " . $e->getMessage();
}
```

### Validate Account Number

[](#validate-account-number)

```
use Nubanstack\Nubanstack;

$nubanstack = new Nubanstack();

try {
    $accountDetails = $nubanstack->validateAccount('0123456789', '057');

    echo "Account Name: " . $accountDetails['account_name'] . PHP_EOL;
    echo "Account Number: " . $accountDetails['account_number'] . PHP_EOL;
} catch (\Nubanstack\Exceptions\NubanstackException $e) {
    echo "Error: " . $e->getMessage();
}
```

### Predict Possible Banks for an Account Number

[](#predict-possible-banks-for-an-account-number)

Find all banks where an account number could be valid:

```
use Nubanstack\Nubanstack;

$nubanstack = new Nubanstack();

try {
    $possibleBanks = $nubanstack->predictBanks('0123456789');

    echo "This account number could belong to:" . PHP_EOL;
    foreach ($possibleBanks as $bank) {
        echo "  - {$bank['name']} (Code: {$bank['code']})" . PHP_EOL;
    }
} catch (\Nubanstack\Exceptions\NubanstackException $e) {
    echo "Error: " . $e->getMessage();
}
```

### Search for Banks

[](#search-for-banks)

```
use Nubanstack\Nubanstack;

$nubanstack = new Nubanstack();

// Search by name
$banks = $nubanstack->searchBanksByName('Access');
foreach ($banks as $bank) {
    echo $bank['name'] . ' - ' . $bank['code'] . PHP_EOL;
}

// Find by code
$bank = $nubanstack->findBankByCode('057');
if ($bank) {
    echo "Found: " . $bank['name'] . PHP_EOL;
}
```

API Reference
-------------

[](#api-reference)

### Online Validation (Requires API Key)

[](#online-validation-requires-api-key)

#### `getBanks(): array`

[](#getbanks-array)

Fetches all Nigerian banks from Paystack.

**Returns:** Array of bank data

**Throws:** `NubanstackException` on error

#### `validateAccount(string $accountNumber, string $bankCode): array`

[](#validateaccountstring-accountnumber-string-bankcode-array)

Validates a Nigerian bank account number using Paystack API (online validation).

**Parameters:**

- `$accountNumber` - The 10-digit account number
- `$bankCode` - The bank code (e.g., '057' for Zenith Bank)

**Returns:** Array containing account details (account\_number, account\_name, bank\_id)

**Throws:** `NubanstackException` on error

#### `setSecretKey(string $secretKey): self`

[](#setsecretkeystring-secretkey-self)

Updates the Paystack secret key after initialization.

**Parameters:**

- `$secretKey` - Your Paystack secret key

**Returns:** Self for method chaining

### Offline Validation (No API Key Required)

[](#offline-validation-no-api-key-required)

#### `validateAccountOffline(string $accountNumber, string $bankCode): bool`

[](#validateaccountofflinestring-accountnumber-string-bankcode-bool)

Validates account number using NUBAN algorithm without API calls.

**Parameters:**

- `$accountNumber` - The 10-digit account number
- `$bankCode` - The bank code (3, 5, or 6 digits)

**Returns:** `true` if valid, `false` otherwise

**Throws:** `NubanstackException` on invalid input

#### `predictBanks(string $accountNumber): array`

[](#predictbanksstring-accountnumber-array)

Predicts all possible banks for a given account number.

**Parameters:**

- `$accountNumber` - The 10-digit account number

**Returns:** Array of possible banks with 'name' and 'code' keys

**Throws:** `NubanstackException` on invalid account number

#### `getOfflineBankList(): array`

[](#getofflinebanklist-array)

Gets the built-in list of Nigerian banks for offline validation.

**Returns:** Array of banks

#### `findBankByCode(string $code): ?array`

[](#findbankbycodestring-code-array)

Finds a bank by its code.

**Parameters:**

- `$code` - Bank code

**Returns:** Bank details array or `null` if not found

#### `searchBanksByName(string $name): array`

[](#searchbanksbynamestring-name-array)

Searches for banks by name (case-insensitive partial match).

**Parameters:**

- `$name` - Search term

**Returns:** Array of matching banks

Response Formats
----------------

[](#response-formats)

### Bank Response

[](#bank-response)

```
[
    'id' => 879,
    'name' => '78 Finance Company Ltd',
    'slug' => '78-finance-company-ltd-ng',
    'code' => '40195',
    'longcode' => '110072',
    'gateway' => null,
    'pay_with_bank' => false,
    'supports_transfer' => true,
    'available_for_direct_debit' => false,
    'active' => true,
    'country' => 'Nigeria',
    'currency' => 'NGN',
    'type' => 'nuban',
    'is_deleted' => false,
    'createdAt' => '2025-11-21T12:32:33.000Z',
    'updatedAt' => '2025-11-21T12:32:33.000Z'
]
```

### Account Validation Response

[](#account-validation-response)

```
[
    'account_number' => '0123456789',
    'account_name' => 'JOHN DOE',
    'bank_id' => 9
]
```

How NUBAN Validation Works
--------------------------

[](#how-nuban-validation-works)

The NUBAN (Nigeria Uniform Bank Account Number) validation uses the algorithm specified by the Central Bank of Nigeria (CBN). The package validates account numbers using:

1. **Check Digit Computation**: Each account number has a check digit (last digit) computed using the bank code and serial number
2. **Weight Arrays**: Specific weights are applied to bank codes and serial numbers
3. **Modulo Calculation**: The algorithm uses modulo 10 arithmetic to verify validity

This allows you to:

- Validate account numbers **instantly offline** without API calls
- Predict which bank(s) an account number could belong to
- Verify account numbers before making online validation requests

**Note:** Offline validation only checks if the account number is mathematically valid for a bank. For verification that the account actually exists and to get the account holder's name, use the online `validateAccount()` method.

Error Handling
--------------

[](#error-handling)

The package throws `NubanstackException` for all errors. Always wrap your calls in try-catch blocks:

```
try {
    $banks = $nubanstack->getBanks();
} catch (\Nubanstack\Exceptions\NubanstackException $e) {
    // Handle error
    echo "Error: " . $e->getMessage();
}
```

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Credits
-------

[](#credits)

- Built with [Guzzle HTTP Client](https://github.com/guzzle/guzzle)
- Powered by [Paystack API](https://paystack.com/)
- NUBAN validation algorithm adapted from [nuban-bank-prediction-algorithm](https://github.com/03balogun/nuban-bank-prediction-algorithm) by [@03balogun](https://github.com/03balogun)

Support
-------

[](#support)

If you encounter any issues or have questions, please [open an issue](https://github.com/thechiddx3/nubanstack/issues) on GitHub.

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance48

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a3f0bb4716067ed55a4d1013094bab7e55ff9c7c4f62272b1da0b5f850eecc3?d=identicon)[thechidd](/maintainers/thechidd)

---

Top Contributors

[![thechiddx3](https://avatars.githubusercontent.com/u/55422013?v=4)](https://github.com/thechiddx3 "thechiddx3 (1 commits)")

### Embed Badge

![Health badge](/badges/nubanstack-nubanstack/health.svg)

```
[![Health](https://phpackages.com/badges/nubanstack-nubanstack/health.svg)](https://phpackages.com/packages/nubanstack-nubanstack)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk

PHP SDK for Facebook Business

90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

265103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)