README

A comprehensive Laravel package for integrating with the Monnify payment gateway. This package provides a clean, fluent interface for handling transactions, invoices, subaccounts, and webhooks.

Features

✅ Complete Monnify API coverage (Transactions, Invoices, Subaccounts)
✅ Automatic token management with caching
✅ Webhook handling with signature verification
✅ Laravel Events for transaction status changes
✅ Database migrations for storing transactions/invoices locally
✅ Type-safe DTOs for all API responses
✅ Facade support for clean, expressive API
✅ Comprehensive exception handling
✅ Full test coverage structure

Requirements

PHP >= 8.1
Laravel >= 10.0 or >= 11.0
Guzzle HTTP Client

Installation

Install the package via Composer:

composer require scwar/laravel-monnify-sdk

Publish Configuration

Publish the configuration file:

php artisan vendor:publish --tag=monnify-config

This will create a config/monnify.php file in your application.

Publish Migrations

Publish the database migrations:

php artisan vendor:publish --tag=monnify-migrations

Run the migrations:

php artisan migrate

Environment Variables

Add the following environment variables to your .env file:

MONNIFY_API_KEY=your_api_key
MONNIFY_SECRET_KEY=your_secret_key
MONNIFY_CONTRACT_CODE=your_contract_code
MONNIFY_WEBHOOK_SECRET=your_webhook_secret
MONNIFY_BASE_URL=https://api.monnify.com
MONNIFY_REDIRECT_URL=https://your-app.com/payment/callback

For sandbox/testing, use:

MONNIFY_BASE_URL=https://sandbox.monnify.com

Configuration

The configuration file is located at config/monnify.php. You can customize:

API credentials
Base URL (sandbox/production)
Webhook secret key
Cache configuration
Database table names
Route prefix and middleware
Default transaction/invoice settings

Usage

Using the Facade

The package provides a facade for easy access:

use Scwar\Monnify\Facades\Monnify;

Transactions

Initialize a Transaction

use Scwar\Monnify\Facades\Monnify;

$transaction = Monnify::transaction()->initialize([
    'amount' => 1000.00,
    'customerName' => 'John Doe',
    'customerEmail' => 'john@example.com',
    'paymentReference' => 'unique-payment-reference',
    'paymentDescription' => 'Payment for order #123',
    'currencyCode' => 'NGN',
    'redirectUrl' => 'https://your-app.com/payment/callback',
    'metadata' => [
        'order_id' => 123,
        'user_id' => 456,
    ],
]);

// Get the checkout URL
$checkoutUrl = $transaction->checkoutUrl;

// Redirect user to checkout
return redirect($checkoutUrl);

Get Transaction Status

$transaction = Monnify::transaction()->getStatus('transaction-reference');

if ($transaction->status === 'PAID') {
    // Transaction is successful
}

Verify Transaction

$transaction = Monnify::transaction()->verify('transaction-reference');

Refund Transaction

$refund = Monnify::transaction()->refund(
    transactionReference: 'transaction-reference',
    amount: 1000.00,
    refundReason: 'Customer requested refund',
    customerNote: 'Refund processed'
);

Query Transaction History

$transactions = Monnify::transaction()->queryHistory([
    'page' => 0,
    'size' => 20,
    'fromDate' => '2024-01-01',
    'toDate' => '2024-01-31',
]);

Invoices

Create an Invoice

$invoice = Monnify::invoice()->create([
    'amount' => 5000.00,
    'invoiceReference' => 'unique-invoice-reference',
    'description' => 'Invoice for services',
    'currencyCode' => 'NGN',
    'contractCode' => config('monnify.contract_code'),
    'customerEmail' => 'customer@example.com',
    'customerName' => 'Jane Doe',
    'expiryDate' => now()->addDays(7)->toIso8601String(),
    'lineItems' => [
        [
            'lineItemId' => 'item-1',
            'name' => 'Service Fee',
            'quantity' => 1,
            'unitPrice' => 5000.00,
        ],
    ],
]);

// Get the checkout URL
$checkoutUrl = $invoice->checkoutUrl;

Get Invoice Details

$invoice = Monnify::invoice()->getDetails('invoice-reference');

Cancel Invoice

Monnify::invoice()->cancel('invoice-reference');

List Invoices

$invoices = Monnify::invoice()->list([
    'page' => 0,
    'size' => 20,
]);

Subaccounts

Create Subaccount

$subaccount = Monnify::subaccount()->create([
    'subAccountCode' => 'SUB_001',
    'subAccountName' => 'Main Subaccount',
    'email' => 'subaccount@example.com',
    'splitPercentage' => 10.0,
]);

// Get the subaccount code
$subaccountCode = $subaccount['subAccountCode'];

Update Subaccount

Monnify::subaccount()->update('SUB_001', [
    'subAccountName' => 'Updated Name',
    'splitPercentage' => 15.0,
]);

Delete Subaccount

Monnify::subaccount()->delete('SUB_001');

Get Subaccount Details

$subaccount = Monnify::subaccount()->getDetails('SUB_001');

List Subaccounts

$subaccounts = Monnify::subaccount()->list([
    'page' => 0,
    'size' => 20,
]);

Webhooks

The package automatically sets up webhook routes. By default, the webhook endpoint is:

POST /api/monnify/webhook

You can customize this in the configuration file.

Webhook Events

The package automatically handles the following webhook events:

SUCCESSFUL_TRANSACTION - Fires TransactionCompleted event
FAILED_TRANSACTION - Fires TransactionFailed event
OVERPAYMENT - Fires TransactionFailed event
PARTIAL_OVERPAYMENT - Fires TransactionFailed event
INVOICE_UPDATE - Updates invoice record

Listening to Events

You can listen to the events in your EventServiceProvider:

use Scwar\Monnify\Events\TransactionCompleted;
use Scwar\Monnify\Events\TransactionFailed;
use Scwar\Monnify\Events\WebhookReceived;

protected $listen = [
    TransactionCompleted::class => [
        // Your listeners
    ],
    TransactionFailed::class => [
        // Your listeners
    ],
    WebhookReceived::class => [
        // Your listeners
    ],
];

Example listener:

use Scwar\Monnify\Events\TransactionCompleted;

class SendPaymentConfirmation
{
    public function handle(TransactionCompleted $event)
    {
        $transaction = $event->transaction;
        
        // Send confirmation email
        // Update order status
        // etc.
    }
}

Webhook Signature Verification

The package automatically verifies webhook signatures using HMAC SHA512. Make sure to set MONNIFY_WEBHOOK_SECRET in your .env file.

Models

The package provides Eloquent models for transactions and invoices:

MonnifyTransaction

use Scwar\Monnify\Models\MonnifyTransaction;

// Get all successful transactions
$transactions = MonnifyTransaction::successful()->get();

// Get transactions for a customer
$transactions = MonnifyTransaction::forCustomer('customer@example.com')->get();

// Check transaction status
$transaction = MonnifyTransaction::where('transaction_reference', 'ref-123')->first();

if ($transaction->isSuccessful()) {
    // Transaction is paid
}

MonnifyInvoice

use Scwar\Monnify\Models\MonnifyInvoice;

// Get all paid invoices
$invoices = MonnifyInvoice::paid()->get();

// Get invoices for a customer
$invoices = MonnifyInvoice::forCustomer('customer@example.com')->get();

// Check invoice status
$invoice = MonnifyInvoice::where('invoice_reference', 'inv-123')->first();

if ($invoice->isPaid()) {
    // Invoice is paid
}

if ($invoice->isExpired()) {
    // Invoice has expired
}

Exceptions

The package provides custom exceptions:

Scwar\Monnify\Exceptions\MonnifyException - Base exception
Scwar\Monnify\Exceptions\AuthenticationException - Authentication errors
Scwar\Monnify\Exceptions\RequestException - API request errors

Example:

use Scwar\Monnify\Exceptions\AuthenticationException;
use Scwar\Monnify\Exceptions\RequestException;

try {
    $transaction = Monnify::transaction()->initialize([...]);
} catch (AuthenticationException $e) {
    // Handle authentication error
} catch (RequestException $e) {
    // Handle request error
    $response = $e->getResponse();
}

Testing

Run the tests:

composer test

Or using PHPUnit directly:

vendor/bin/phpunit

API Documentation

For complete API documentation, visit the Monnify Developer Documentation.

Contributing

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

License

This package is open-sourced software licensed under the MIT license.

Support

For issues and questions, please open an issue on GitHub.

Changelog

Please see CHANGELOG for more information on what has changed recently.

scwar / laravel-monnify-sdk

Maintainers

Details