PHPackages                             gbxnga/payaza-laravel-sdk - 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. gbxnga/payaza-laravel-sdk

ActiveLibrary[API Development](/categories/api)

gbxnga/payaza-laravel-sdk
=========================

Type-safe Laravel SDK for the Payaza API

v1.0.52(11mo ago)07MITPHPPHP ^8.2CI passing

Since Jul 20Pushed 11mo agoCompare

[ Source](https://github.com/gbxnga/payaza-laravel-sdk)[ Packagist](https://packagist.org/packages/gbxnga/payaza-laravel-sdk)[ RSS](/packages/gbxnga-payaza-laravel-sdk/feed)WikiDiscussions main Synced today

READMEChangelog (6)Dependencies (7)Versions (9)Used By (0)

Payaza PHP SDK
==============

[](#payaza-php-sdk)

[![Latest Version on Packagist](https://camo.githubusercontent.com/3040f68c068690efc129ac0189504ecc4e35259e00db801747caa0e8d4725cfd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6762786e67612f706179617a612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gbxnga/payaza-laravel-sdk)[![GitHub Tests Action Status](https://camo.githubusercontent.com/f02f9acffaca8e96268d5c966477f6dbc5263c8b9b87bba21cb5650bff54ddb0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6762786e67612f706179617a612d6c61726176656c2d73646b2f63692d63642e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/gbxnga/payaza-laravel-sdk/actions?query=workflow%3Aci-cd+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/f72949d8e56acdae3cc8470d3907df408a834571c37c4d01dccd3a9a7709b593/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6762786e67612f706179617a612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gbxnga/payaza-laravel-sdk)[![PHP Version Require](https://camo.githubusercontent.com/392cc61ee30fbb91c7209eba371cdf9e9618485636d9f57d14f6270014f37851/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6762786e67612f706179617a612d6c61726176656c2d73646b2f7068703f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gbxnga/payaza-laravel-sdk)

A production-ready Laravel PHP SDK that wraps the entire Payaza REST API behind an expressive, type-safe façade. Everything is namespaced, strictly typed (declare(strict\_types=1)), PSR-12 compliant, and fully unit-tested with PHPUnit.

Features
--------

[](#features)

- 🔒 **Type-safe**: Built with PHP 8.2+ features including enums, readonly classes, and strict typing
- 🚀 **Laravel Integration**: Auto-discovery, service provider, facade, and configuration publishing
- 🧪 **Fully Tested**: Comprehensive unit and integration tests with HTTP mocking
- 📦 **PSR Compliant**: Follows PSR-12 coding standards and PSR-4 autoloading
- 🛡️ **Error Handling**: Centralized exception handling with meaningful error messages
- 🔧 **Configurable**: Environment-based configuration with sensible defaults
- 📖 **Well Documented**: Extensive PHPDoc annotations and usage examples

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

[](#installation)

You can install the package via composer:

```
composer require gbxnga/payaza-laravel-sdk
```

Publish the configuration file:

```
php artisan vendor:publish --tag=payaza-config
```

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

[](#configuration)

### Environment-Based URL Resolution

[](#environment-based-url-resolution)

The SDK automatically handles test/live environment switching with configurable URLs. URLs can contain a `{tenant}` placeholder that gets replaced with `test` or `live` based on your `PAYAZA_ENV` setting.

### Setup

[](#setup)

Add your Payaza credentials to your `.env` file:

```
PAYAZA_PUBLIC_KEY=your_base64_encoded_public_key
PAYAZA_PREMIUM_PUBLIC_KEY=your_premium_public_key
PAYAZA_DEFAULT_ACCOUNT=primary # Default account to use
PAYAZA_TRANSACTION_PIN=your_transaction_pin # Required for payouts
PAYAZA_ENV=test # or 'live' for production
PAYAZA_BASE_URL=https://api.payaza.africa

# Optional: Override specific API URLs if Payaza changes them
# Use {tenant} placeholder for automatic live/test path injection
PAYAZA_CARD_STATUS_URL=https://api.payaza.africa/{tenant}/card/card_charge/transaction_status
PAYAZA_PAYOUT_URL=https://api.payaza.africa/{tenant}/payout-receptor/payout
PAYAZA_ACCOUNT_ENQUIRY_URL=https://api.payaza.africa/{tenant}/payaza-account/api/v1/mainaccounts/merchant/provider/enquiry
# ... other URLs as needed
```

### How Tenant Resolution Works

[](#how-tenant-resolution-works)

When you set `PAYAZA_ENV=live`, URLs like:

- `https://api.payaza.africa/{tenant}/payout-receptor/payout`
- Become: `https://api.payaza.africa/live/payout-receptor/payout`

When you set `PAYAZA_ENV=test`, they become:

- `https://api.payaza.africa/test/payout-receptor/payout`

This ensures proper environment isolation while maintaining URL flexibility.

Usage
-----

[](#usage)

### Multiple Account Support

[](#multiple-account-support)

The SDK supports multiple Payaza accounts with easy switching:

```
use PayazaSdk\Payaza;

// Use default account (configured in PAYAZA_DEFAULT_ACCOUNT)
$balance = Payaza::accounts()->balance();

// Switch to a specific account
$premiumBalance = Payaza::account('premium')->accounts()->balance();
$primaryCharge = Payaza::account('primary')->cards()->charge($amount, $card, $ref);
```

### Card Charges

[](#card-charges)

```
use PayazaSdk\Payaza;
use PayazaSdk\Data\Card;
use PayazaSdk\Enums\Currency;

// Charge a card with custom callback URL
$status = Payaza::cards()->charge(
    amount: 150.00,
    card: new Card('4242424242424242', 7, 2026, '123'),
    transactionRef: 'ORDER-123',
    currency: Currency::USD,
    accountName: 'John Doe',
    authType: '3DS', // or '2DS'
    callbackUrl: 'https://yoursite.com/webhooks/payaza' // Custom callback
);

// Charge with default callback URL
$status = Payaza::cards()->charge(
    amount: 150.00,
    card: new Card('4242424242424242', 7, 2026, '123'),
    transactionRef: 'ORDER-123',
    currency: Currency::USD,
    accountName: 'John Doe'
);

// Check transaction status
$transactionStatus = Payaza::cards()->status('ORDER-123');

if ($transactionStatus->state === TransactionState::SUCCESSFUL) {
    // Payment was successful
    echo "Payment completed: {$transactionStatus->transactionId}";
}

// Process refund
$refundSuccess = Payaza::cards()->refund('ORDER-123', 50.00);

// Check refund status
$refundStatus = Payaza::cards()->refundStatus('REFUND-123');
```

### Payouts

[](#payouts)

#### NGN Bank Transfer

[](#ngn-bank-transfer)

```
use PayazaSdk\Payaza;
use PayazaSdk\Data\PayoutBeneficiary;
use PayazaSdk\Enums\Currency;

// Create a payout
$beneficiary = new PayoutBeneficiary(
    accountName: 'Jane Smith',
    accountNumber: '0123456789',
    bankCode: '044', // Access Bank
    amount: 500.00,
    currency: Currency::NGN,
    narration: 'Salary payment'
);

$status = Payaza::payouts()->send($beneficiary, 'PAYOUT-456');

// Check payout status
$payoutStatus = Payaza::payouts()->status('PAYOUT-456');
```

#### GHS Bank Transfer

[](#ghs-bank-transfer)

```
// GHS bank transfer
$status = Payaza::payouts()->sendGHSBankTransfer(
    amount: 100.00,
    accountNumber: '1234567890',
    accountName: 'John Doe',
    bankCode: 'GCB',
    transactionRef: 'GHS-PAYOUT-123',
    narration: 'GHS Payment'
);
```

#### Mobile Money Payouts

[](#mobile-money-payouts)

Support for mobile money across African currencies:

```
use PayazaSdk\Enums\Currency;

// KES Mobile Money (Kenya)
$status = Payaza::payouts()->sendMobileMoney(
    currency: Currency::KES,
    amount: 1000.00,
    phoneNumber: '254700123456',
    accountName: 'John Doe',
    bankCode: 'MPESA',
    transactionRef: 'KES-MOMO-123'
);

// GHS Mobile Money (Ghana)
$status = Payaza::payouts()->sendMobileMoney(
    currency: Currency::GHS,
    amount: 50.00,
    phoneNumber: '233241234567',
    accountName: 'Jane Doe',
    bankCode: 'MTN',
    transactionRef: 'GHS-MOMO-123'
);

// UGX Mobile Money (Uganda)
$status = Payaza::payouts()->sendMobileMoney(
    currency: Currency::UGX,
    amount: 50000.00,
    phoneNumber: '256701234567',
    accountName: 'Bob Smith',
    bankCode: 'AIRTEL',
    transactionRef: 'UGX-MOMO-123'
);

// TZS Mobile Money (Tanzania)
$status = Payaza::payouts()->sendMobileMoney(
    currency: Currency::TZS,
    amount: 25000.00,
    phoneNumber: '255621234567',
    accountName: 'Alice Johnson',
    bankCode: 'VODACOM',
    transactionRef: 'TZS-MOMO-123'
);

// XOF Mobile Money (West Africa - requires country)
$status = Payaza::payouts()->sendMobileMoney(
    currency: Currency::XOF,
    amount: 10000.00,
    phoneNumber: '221701234567',
    accountName: 'Marie Diallo',
    bankCode: 'ORANGE',
    transactionRef: 'XOF-MOMO-123',
    country: 'SEN' // Senegal country code
);
```

### Account Information

[](#account-information)

```
use PayazaSdk\Payaza;
use PayazaSdk\Enums\Currency;

// Get balance for a specific currency (NEW!)
$ngnBalance = Payaza::accounts()->currency(Currency::NGN)->balance();
echo "NGN Balance: {$ngnBalance['available_balance']} {$ngnBalance['currency']}";

$ghsBalance = Payaza::accounts()->currency(Currency::GHS)->balance();
echo "GHS Balance: {$ghsBalance['available_balance']} {$ghsBalance['currency']}";

// Get all account balances
$allBalances = Payaza::accounts()->balance();
foreach ($allBalances as $account) {
    echo "Currency: {$account['currency']}, Balance: {$account['balance']}";
}

// Verify account name before payout (Account Name Enquiry)
$accountInfo = Payaza::accounts()->getAccountNameEnquiry(
    accountNumber: '0123456789',
    bankCode: '044',
    currency: Currency::NGN
);

// Check if account is valid before proceeding
if ($accountInfo['account_status'] === 'INVALID') {
    echo "Invalid account number: {$accountInfo['error_message']}";
} elseif ($accountInfo['account_status'] === 'ACTIVE') {
    echo "Account Name: {$accountInfo['account_name']}";
    echo "Account Status: {$accountInfo['account_status']}";
    // Proceed with payout...
} else {
    echo "Account Status: {$accountInfo['account_status']}";
}

// Get Payaza account information
$payazaAccounts = Payaza::accounts()->getPayazaAccountsInfo();
foreach ($payazaAccounts as $account) {
    echo "Currency: {$account['currency']}, Balance: {$account['balance']}";
}
```

Data Objects
------------

[](#data-objects)

The SDK uses readonly data objects for type safety:

### Card

[](#card)

```
use PayazaSdk\Data\Card;

$card = new Card(
    number: '4242424242424242',
    expiryMonth: 12,
    expiryYear: 2027,
    cvc: '123'
);
```

### PayoutBeneficiary

[](#payoutbeneficiary)

```
use PayazaSdk\Data\PayoutBeneficiary;
use PayazaSdk\Enums\Currency;

$beneficiary = new PayoutBeneficiary(
    accountName: 'John Doe',
    accountNumber: '0123456789',
    bankCode: '044',
    amount: 1000.00,
    currency: Currency::NGN,
    narration: 'Monthly stipend' // optional
);
```

### TransactionStatus

[](#transactionstatus)

```
use PayazaSdk\Data\TransactionStatus;
use PayazaSdk\Enums\TransactionState;

// Returned from charge, status, and other operations
$status = new TransactionStatus(
    transactionId: 'TXN-123',
    state: TransactionState::SUCCESSFUL,
    raw: [] // Full API response
);
```

Enums
-----

[](#enums)

### Currency

[](#currency)

```
use PayazaSdk\Enums\Currency;

Currency::USD; // US Dollar
Currency::NGN; // Nigerian Naira
Currency::GHS; // Ghanaian Cedi
Currency::XOF; // West African CFA Franc
Currency::KES; // Kenyan Shilling
Currency::UGX; // Ugandan Shilling
Currency::TZS; // Tanzanian Shilling
```

### TransactionState

[](#transactionstate)

```
use PayazaSdk\Enums\TransactionState;

TransactionState::PENDING;     // Transaction initiated
TransactionState::PROCESSING;  // Transaction in progress
TransactionState::SUCCESSFUL;  // Transaction completed
TransactionState::FAILED;      // Transaction failed
```

### Environment

[](#environment)

```
use PayazaSdk\Enums\Environment;

Environment::TEST; // Test/sandbox environment
Environment::LIVE; // Production environment
```

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

[](#error-handling)

The SDK throws `PayazaException` for API errors:

```
use PayazaSdk\Exceptions\PayazaException;

try {
    $status = Payaza::cards()->charge($amount, $card, $ref);
} catch (PayazaException $e) {
    echo "Payaza error: {$e->getMessage()} (Code: {$e->getCode()})";
}
```

Testing
-------

[](#testing)

### Running Unit Tests

[](#running-unit-tests)

This SDK uses [PestPHP](https://pestphp.com) for testing:

```
composer test
```

### Integration Tests

[](#integration-tests)

Set up integration testing with live API calls:

```
# Set environment variable
export PAYAZA_INTEGRATION=1

# Run tests
composer test
```

**Note**: Integration tests require valid API credentials and will make actual API calls.

### Test Structure

[](#test-structure)

- **Unit Tests**: Located in `tests/Unit/` - Mock HTTP responses for isolated testing
- **Feature Tests**: Located in `tests/Feature/` - Optional integration tests with live API

Advanced Usage
--------------

[](#advanced-usage)

### Complete Payout Workflow with Account Verification

[](#complete-payout-workflow-with-account-verification)

```
use PayazaSdk\Payaza;
use PayazaSdk\Data\PayoutBeneficiary;
use PayazaSdk\Enums\Currency;
use PayazaSdk\Exceptions\PayazaException;

try {
    // Step 1: Verify recipient account details
    $accountInfo = Payaza::accounts()->getAccountNameEnquiry(
        accountNumber: '0123456789',
        bankCode: '044',
        currency: Currency::NGN
    );

    if ($accountInfo['account_status'] !== 'ACTIVE') {
        throw new Exception('Recipient account is not active');
    }

    // Step 2: Create and send payout
    $beneficiary = new PayoutBeneficiary(
        accountName: $accountInfo['account_name'], // Use verified name
        accountNumber: $accountInfo['account_number'],
        bankCode: '044',
        amount: 1000.00,
        currency: Currency::NGN,
        narration: 'Salary payment'
    );

    $status = Payaza::payouts()->send($beneficiary, 'PAYOUT-' . uniqid());

    // Step 3: Monitor payout status
    do {
        sleep(5);
        $payoutStatus = Payaza::payouts()->status($status->transactionId);
        echo "Status: {$payoutStatus->state->value}\n";
    } while ($payoutStatus->state === TransactionState::PROCESSING);

    if ($payoutStatus->state === TransactionState::SUCCESSFUL) {
        echo "Payout completed successfully!";
    }

} catch (PayazaException $e) {
    echo "Payout failed: {$e->getMessage()}";
}
```

### Custom HTTP Client

[](#custom-http-client)

```
use Illuminate\Http\Client\Factory;
use PayazaSdk\PayazaClient;
use PayazaSdk\Enums\Environment;

$httpClient = new Factory();
$httpClient->timeout(30); // Custom timeout

$client = new PayazaClient(
    token: base64_encode('your-api-key'),
    env: Environment::TEST,
    http: $httpClient
);

$cards = $client->cards();
```

### Direct Client Usage

[](#direct-client-usage)

```
use PayazaSdk\PayazaClient;
use PayazaSdk\Enums\Environment;

// Without facade
$client = new PayazaClient(
    base64_encode(config('payaza.primary_public_key')),
    Environment::TEST
);

$status = $client->cards()->charge($amount, $card, $ref);
```

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

[](#configuration-1)

The `config/payaza.php` file contains:

```
return [
    // Multiple Accounts Configuration
    'accounts' => [
        'primary' => [
            'key' => env('PAYAZA_PUBLIC_KEY'),
        ],
        'premium' => [
            'key' => env('PAYAZA_PREMIUM_PUBLIC_KEY'),
        ],
    ],

    // Default Account
    'default_account' => env('PAYAZA_DEFAULT_ACCOUNT', 'primary'),

    // Transaction PIN
    'transaction_pin' => env('PAYAZA_TRANSACTION_PIN'),

    // Configurable API URLs with tenant support
    // Use {tenant} placeholder for automatic live/test path injection
    'urls' => [
        'card_charge_3ds' => env('PAYAZA_CARD_3DS_URL', 'https://cards-live.78financials.com/card_charge/'),
        'card_charge_2ds' => env('PAYAZA_CARD_2DS_URL', 'https://cards-live.78financials.com/cards/mpgs/v1/2ds/card_charge'),
        'card_status' => env('PAYAZA_CARD_STATUS_URL', 'https://api.payaza.africa/{tenant}/card/card_charge/transaction_status'),
        'payout_send' => env('PAYAZA_PAYOUT_URL', 'https://api.payaza.africa/{tenant}/payout-receptor/payout'),
        'account_enquiry' => env('PAYAZA_ACCOUNT_ENQUIRY_URL', 'https://api.payaza.africa/{tenant}/payaza-account/api/v1/mainaccounts/merchant/provider/enquiry'),
        // ... other endpoints
    ],

    // Environment and URLs
    'environment' => env('PAYAZA_ENV', 'test'), // 'test' or 'live'
    'base_url'    => env('PAYAZA_BASE_URL', 'https://api.payaza.africa'),

    // HTTP timeout in seconds
    'timeout' => 24,
];
```

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

[](#requirements)

- PHP 8.2 or higher
- Laravel 10.0, 11.0, or 12.0
- Guzzle HTTP 7.8+

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

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you discover any security-related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Gbenga Oni](https://github.com/gbxnga)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

---

API Coverage
------------

[](#api-coverage)

This SDK provides complete coverage of the Payaza API:

### Cards

[](#cards)

- ✅ Card charging (3DS/2DS authentication)
- ✅ Transaction status checking
- ✅ Refunds processing
- ✅ Refund status tracking
- ✅ Multiple currency support (USD, NGN, GHS, KES, UGX, TZS, XOF)

### Payouts

[](#payouts-1)

- ✅ NGN bank transfers (NUBAN)
- ✅ GHS bank transfers (GHIPPS)
- ✅ Mobile money payouts (GHS, KES, UGX, TZS, XOF)
- ✅ Multi-country support (XOF with country parameter)
- ✅ Payout status checking
- ✅ Bank list retrieval
- ✅ Automatic account reference resolution

### Account Management

[](#account-management)

- ✅ Account balance checking
- ✅ Transaction history retrieval
- ✅ Single transaction lookup
- ✅ Account name enquiry/verification
- ✅ Payaza account information
- ✅ Multi-account support with easy switching

### Additional Features

[](#additional-features)

- ✅ Multiple Payaza account management
- ✅ Environment-based configuration (test/live)
- ✅ Type-safe enums and data objects
- ✅ Comprehensive error handling
- ✅ Laravel service provider integration
- ✅ Facade support with account switching

Support
-------

[](#support)

For support, email  or join our Slack channel.

Roadmap
-------

[](#roadmap)

- Webhook signature verification
- Bulk operations
- Rate limiting helpers
- Laravel Notification channel
- Artisan commands for common operations

###  Health Score

31

—

LowBetter than 66% of packages

Maintenance51

Moderate activity, may be stable

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~0 days

Total

8

Last Release

349d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/30432941?v=4)[Gbenga Oni](/maintainers/gbxnga)[@gbxnga](https://github.com/gbxnga)

---

Top Contributors

[![gbxnga](https://avatars.githubusercontent.com/u/30432941?v=4)](https://github.com/gbxnga "gbxnga (16 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/gbxnga-payaza-laravel-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/gbxnga-payaza-laravel-sdk/health.svg)](https://phpackages.com/packages/gbxnga-payaza-laravel-sdk)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.0k](/packages/simplestats-io-laravel-client)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816333.8k3](/packages/defstudio-telegraph)[jasara/php-amzn-selling-partner-api

A fluent interface for Amazon's Selling Partner API in PHP

1348.7k1](/packages/jasara-php-amzn-selling-partner-api)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1235.9k20](/packages/fleetbase-core-api)

PHPackages © 2026

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