README

A comprehensive PHP SDK for integrating with the Monnify Payment Gateway. This SDK provides a clean, object-oriented interface for all Monnify API operations including payment initiation, verification, refunds, and webhook handling.

Features

🚀 Easy Integration: Simple and intuitive API
🔒 Secure: Built-in security features and validation
📦 Complete Coverage: All Monnify API endpoints supported
🧪 Well Tested: Comprehensive test suite
📚 Well Documented: Clear documentation and examples
🔄 Webhook Support: Built-in webhook verification and handling
💰 Multiple Payment Methods: Card, Bank Transfer, USSD, etc.

Installation

composer require praisedare/monnify-sdk

Quick Start

1. Initialize the SDK

use PraiseDare\Monnify\Monnify;

$monnify = new Monnify([
    'secret_key' => 'your_secret_key',
    'api_key' => 'your_api_key',
    'contract_code' => 'your_contract_code',
    'environment' => 'sandbox', // or 'live'
]);

2. Initialize a Payment

$paymentData = [
    'amount' => 1000.00,
    'customerName' => 'John Doe',
    'customerEmail' => 'john@example.com',
    'paymentReference' => 'TXN-' . uniqid(),
    'paymentDescription' => 'Payment for services',
    'currencyCode' => 'NGN',
    'contractCode' => 'your_contract_code',
    'redirectUrl' => 'https://yourwebsite.com/callback',
    'paymentMethods' => ['CARD', 'ACCOUNT_TRANSFER', 'USSD']
];

$response = $monnify->payment()->initialize($paymentData);

3. Verify Payment

$transactionReference = 'MNFY|20240101|123456789';
$response = $monnify->payment()->verify($transactionReference);

4. Handle Webhooks

$webhookData = $request->getContent();
$signature = $request->header('MNFY-SIGNATURE');

if ($monnify->webhook()->verify($webhookData, $signature)) {
    $payload = json_decode($webhookData, true);
    // Process the webhook data
}

Configuration

Environment Variables

MONNIFY_SECRET_KEY=your_secret_key
MONNIFY_API_KEY=your_api_key
MONNIFY_CONTRACT_CODE=your_contract_code
MONNIFY_ENVIRONMENT=sandbox

Configuration Array

$config = [
    'secret_key' => env('MONNIFY_SECRET_KEY'),
    'api_key' => env('MONNIFY_API_KEY'),
    'contract_code' => env('MONNIFY_CONTRACT_CODE'),
    'environment' => env('MONNIFY_ENVIRONMENT', 'sandbox'),
    'timeout' => 30, // HTTP timeout in seconds
    'verify_ssl' => true, // SSL verification
];

API Reference

Payment Methods

Initialize Payment

$response = $monnify->payment()->initialize([
    'amount' => 1000.00,
    'customerName' => 'John Doe',
    'customerEmail' => 'john@example.com',
    'paymentReference' => 'TXN-' . uniqid(),
    'paymentDescription' => 'Payment for services',
    'currencyCode' => 'NGN',
    'contractCode' => 'your_contract_code',
    'redirectUrl' => 'https://yourwebsite.com/callback',
    'paymentMethods' => ['CARD', 'ACCOUNT_TRANSFER', 'USSD']
]);

Verify Payment

$response = $monnify->payment()->verify('MNFY|20240101|123456789');

Get Transaction Status

$response = $monnify->payment()->getStatus('MNFY|20240101|123456789');

Refund Methods

Initiate Refund

$response = $monnify->refund()->initiate([
    'transactionReference' => 'MNFY|20240101|123456789',
    'refundAmount' => 500.00,
    'refundReason' => 'Customer request',
    'refundReference' => 'REF-' . uniqid()
]);

Get Refund Status

$response = $monnify->refund()->getStatus('REF-' . uniqid());

Settlement Methods

Get Settlement Accounts

$response = $monnify->settlement()->getAccounts();

Get Settlement Transactions

$response = $monnify->settlement()->getTransactions([
    'page' => 1,
    'size' => 20,
    'fromDate' => '2024-01-01',
    'toDate' => '2024-01-31'
]);

Webhook Methods

Verify Webhook

$isValid = $monnify->webhook()->verify($webhookData, $signature);

Parse Webhook

$payload = $monnify->webhook()->parse($webhookData);

Error Handling

try {
    $response = $monnify->payment()->initialize($paymentData);
} catch (PraiseDare\Monnify\Exceptions\MonnifyException $e) {
    // Handle Monnify-specific errors
    echo "Error: " . $e->getMessage();
    echo "Code: " . $e->getCode();
} catch (Exception $e) {
    // Handle general errors
    echo "General Error: " . $e->getMessage();
}

Response Format

All API responses follow a consistent format:

[
    'success' => true,
    'data' => [
        // Response data
    ],
    'message' => 'Operation successful',
    'code' => 'SUCCESS'
]

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer phpstan

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please contact:

Email: praisedare27@gmail.com
Documentation: Monnify API Docs

Changelog

v1.0.0

Initial release
Payment initialization and verification
Refund functionality
Settlement management
Webhook handling
Comprehensive error handling

praisedare / monnify-sdk

Maintainers

Details