README

PHP SDK for integrating with the ElgioPay API. Optimized for mobile money payments in Cameroon and West Africa.

Features

🇨🇲 Cameroon-First: Optimized for XAF currency and Cameroon phone formats
📱 Mobile Money: MTN Mobile Money and Orange Money support
🔄 Auto-Retry: Built-in payment retry mechanism with exponential backoff
✅ Phone Validation: Automatic phone number normalization for Cameroon
🛡️ Error Handling: Comprehensive error handling with detailed messages
🔗 Webhooks: Easy webhook integration for payment status updates
💰 Multi-Currency: Support for XAF, XOF, and EUR currencies

Installation

composer require elgiosoft/elgiopay-php-sdk

Requirements

PHP 8.0 or higher
Guzzle HTTP client

Features
Installation
Quick Start for Cameroon
Usage
Supported Payment Methods
Configuration
Error Handling
Webhooks
Testing
Support

Usage

Basic Setup

Using Environment Variables (Recommended)

Create a .env file in your project root:

ELGIOPAY_API_KEY=pk_test_your_api_key
ELGIOPAY_ENV=sandbox

use ElgioPay\SDK\ElgioPayClient;

// Automatically reads from ELGIOPAY_API_KEY and ELGIOPAY_ENV
$client = new ElgioPayClient();

Manual Configuration

Constructor signature: new ElgioPayClient(?string $environment = null, ?string $apiKey = null). Both fall back to ELGIOPAY_ENV / ELGIOPAY_API_KEY env vars when omitted.

use ElgioPay\SDK\ElgioPayClient;

// For testing (sandbox)
$client = new ElgioPayClient('sandbox', 'pk_test_your_api_key');

// For production (live)
$client = new ElgioPayClient('prod', 'pk_live_your_api_key');

Creating a payment

Every payment — MTN, Orange, current markets and any we add later — goes through a single method: initiatePayment(). Pick the payment_method you need and pass the payload.

// Signature
$client->initiatePayment(array $paymentData): array

// Payload shape
// [
//     'amount'          => float,
//     'currency'        => string,   // 'XAF' | 'XOF' | 'EUR' | 'USD'
//     'payment_method'  => string,   // 'mtn_mobile_money' | 'orange_money'
//     'customer_phone'  => string,   // E.164, e.g. '+237677123456'
//     'customer_name'   => string,   // optional
//     'customer_email'  => string,   // optional
//     'reference'       => string,   // optional
//     'metadata'        => array,    // optional
//     'surcharge'       => float,    // optional — SURCHARGE wallet add-on
// ]

MTN Mobile Money (Cameroon)

try {
    $result = $client->initiatePayment([
        'amount'         => 1000.00,
        'currency'       => 'XAF',
        'payment_method' => 'mtn_mobile_money',
        'customer_phone' => '+237677123456',
        'customer_name'  => 'John Doe',
        'customer_email' => 'john@example.com',
        'reference'      => 'ORDER-123',
        'metadata'       => [
            'order_id' => 123,
            'product'  => 'Premium Plan',
        ],
    ]);

    echo "Transaction ID: " . $result['transaction_id'];
    echo "Status: " . $result['status'];
} catch (\ElgioPay\SDK\ElgioPayException $e) {
    echo "Payment failed: " . $e->getMessage();
}

Orange Money (Cameroon)

try {
    $result = $client->initiatePayment([
        'amount'         => 5000.00,
        'currency'       => 'XAF',
        'payment_method' => 'orange_money',
        'customer_phone' => '+237677123456',
        'customer_name'  => 'Jane Doe',
        'reference'      => 'INV-456',
    ]);

    echo "Payment URL: " . $result['payment_url'];
} catch (\ElgioPay\SDK\ElgioPayException $e) {
    echo "Payment failed: " . $e->getMessage();
}

Normalising Cameroon phone numbers

If your customer input arrives in mixed formats (677…, 237…, +237…), pipe it through normalizeCameroonPhone() before calling initiatePayment().

$phone = $client->normalizeCameroonPhone('677123456'); // → +237677123456

$result = $client->initiatePayment([
    'amount'         => 1000.00,
    'currency'       => 'XAF',
    'payment_method' => 'mtn_mobile_money',
    'customer_phone' => $phone,
]);

Check Payment Status

try {
    $status = $client->getPaymentStatus('txn_abc123');
    
    echo "Status: " . $status['status'];
    echo "Amount: " . $status['amount'];
} catch (\ElgioPay\SDK\ElgioPayException $e) {
    echo "Status check failed: " . $e->getMessage();
}

Verify Payment

try {
    $verification = $client->verifyPayment('txn_abc123');
    
    if ($verification['verified']) {
        echo "Payment verified successfully!";
    } else {
        echo "Payment verification failed.";
    }
} catch (\ElgioPay\SDK\ElgioPayException $e) {
    echo "Verification failed: " . $e->getMessage();
}

Payment with Retry

try {
    $result = $client->createPaymentWithRetry([
        'amount' => 2000.00,
        'payment_method' => 'mtn_mobile_money',
        'customer_phone' => '+237677123456',
        'currency' => 'XAF'
    ], maxRetries: 3);
    
    echo "Payment created: " . $result['transaction_id'];
} catch (\ElgioPay\SDK\ElgioPayException $e) {
    echo "Payment failed after retries: " . $e->getMessage();
}

Supported Payment Methods

MTN Mobile Money: Available in Cameroon, Côte d'Ivoire, Burkina Faso, Ghana
Orange Money: Available in Cameroon, Côte d'Ivoire, Burkina Faso, Mali, Senegal

Supported Currencies

XAF (Central African CFA Franc) - Primary currency for Cameroon
XOF (West African CFA Franc) - For other West African countries
EUR (Euro) - For international transactions

Phone Number Formats

Cameroon: +237 6XX XXX XXX or +237 7XX XXX XXX

Examples: +237677123456, 237677123456, 677123456

Quick Start for Cameroon

use ElgioPay\SDK\ElgioPayClient;

$client = new ElgioPayClient('sandbox', 'pk_test_your_api_key');

// Simple MTN payment in XAF
$result = $client->initiatePayment([
    'amount'         => 5000.00, // 5000 XAF
    'currency'       => 'XAF',
    'payment_method' => 'mtn_mobile_money',
    'customer_phone' => $client->normalizeCameroonPhone('677123456'),
    'customer_name'  => 'Jean Dupont',
    'reference'      => 'FACTURE-001',
]);

// Simple Orange payment in XAF
$result = $client->initiatePayment([
    'amount'         => 2500.00, // 2500 XAF
    'currency'       => 'XAF',
    'payment_method' => 'orange_money',
    'customer_phone' => '+237677123456',
    'reference'      => 'CMD-002',
]);

Configuration

API Keys

You only need two things to get started:

API Key: Get your API key from the ElgioPay dashboard
Environment: Choose between sandbox (testing) or live (production)

// Sandbox environment (for testing)
$client = new ElgioPayClient('sandbox', 'pk_test_your_sandbox_api_key');

// Live environment (for production) 
$client = new ElgioPayClient('prod', 'pk_live_your_live_api_key');

Environment Variables (Recommended)

# For testing
ELGIOPAY_API_KEY=pk_test_your_sandbox_api_key
ELGIOPAY_ENV=sandbox

# For production
ELGIOPAY_API_KEY=pk_live_your_live_api_key
ELGIOPAY_ENV=prod

Then in your code — both are picked up automatically:

$client = new ElgioPayClient();

Error Handling

The SDK throws ElgioPayException for all API-related errors:

try {
    $result = $client->initiatePayment($paymentData);
} catch (\ElgioPay\SDK\ElgioPayException $e) {
    $errorMessage = $e->getMessage();
    $errorCode = $e->getCode();
    $responseData = $e->getResponse(); // API response if available
    
    // Handle error appropriately
}

Webhook Handling

Set up webhooks in your application to receive payment status updates:

// In your webhook endpoint
$data = json_decode(file_get_contents('php://input'), true);

if ($data['status'] === 'completed') {
    // Payment successful
    $transactionId = $data['transaction_id'];
    // Update your order status
} elseif ($data['status'] === 'failed') {
    // Payment failed
    $reason = $data['failure_reason'];
    // Handle failed payment
}

Testing

Sandbox Environment

Use sandbox API keys (starting with pk_test_) for testing. All sandbox transactions are simulated and no real money is processed.

// Testing setup
$client = new ElgioPayClient('sandbox', 'pk_test_your_sandbox_key');

// Test payment
$result = $client->initiatePayment([
    'amount'         => 1000.00,
    'currency'       => 'XAF',
    'payment_method' => 'mtn_mobile_money',
    'customer_phone' => '+237677123456',
]);

Getting API Keys

Sign up at sandbox.elgiopay.com
Create a new application
Copy your API keys:
- pk_test_... for testing
- pk_live_... for production

Test Phone Numbers

For sandbox testing, use these test phone numbers:

MTN: 677123456, 677123457, 677123458
Orange: 677123456, 677123457, 677123458

All sandbox payments will automatically succeed after a few seconds.

Support

📖 Documentation: https://docs.elgiopay.com
🐛 Issues: GitHub Issues
💬 Support: developers@elgiosoft.com
🌐 Website: https://elgiopay.com

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

About Elgiosoft

ElgioPay PHP SDK is developed by Elgiosoft Ltd, a leading fintech company specializing in mobile money solutions for Africa.

elgiosoft / elgiopay-php-sdk

Package info

Security

Statistics