Complete Guide: Orange Money and Wave API Integration in PHP

1Why Integrate Orange Money and Wave into Your Application

Orange Money and Wave dominate the mobile payment market in French-speaking Africa. Orange Money has over 30 million active users in Ivory Coast, Cameroon, Senegal, and Mali. Wave, with its reduced fees of only 1%, has revolutionized the market and captures a growing share of transactions. For an e-commerce business, not offering these payment methods means losing the majority of your potential customers. API integration allows you to fully automate the payment process, from collection to refund, while providing a smooth user experience.

2Prerequisites for API Integration

Before starting the integration, make sure you have:

1. An ElyonPay merchant account (free registration at elyonpay.com/register)
2. Your API keys (API Key and Secret available in your dashboard)
3. PHP 7.4 or higher installed on your server
4. Composer for dependency management
5. A valid SSL certificate (required to receive confirmation webhooks)

Once your account is created, access your merchant dashboard to retrieve your sandbox API keys — you can test without real charges.

3Installing the ElyonPay PHP SDK

Installation is done simply via Composer:

composer require elyonpay/elyonpay-php

Then initialize the client in your code:

$client = new ElyonPay\Client('YOUR_API_KEY');

For testing, the SDK automatically uses the sandbox environment. In production, add the parameter:

$client = new ElyonPay\Client('YOUR_API_KEY', [
    'environment' => 'production'
]);

The SDK automatically handles authentication, retries on network errors, and response serialization.

4Your First Request - Connection Verification

Before initiating payments, verify that your integration works correctly:

$balance = $client->account->balance();
echo 'Available balance: ' . $balance->available . ' ' . $balance->currency;

If you receive a valid response with your balance (0 FCFA in sandbox), your configuration is correct and you can proceed to the next step.

5Initiating an Orange Money Payment - Complete Code

To initiate an Orange Money payment, create a request with the required parameters:

$payment = $client->payments->create([
    'amount'       => 5000,
    'currency'     => 'XOF',
    'provider'     => 'orange_money',
    'phone'        => '+2250701234567',
    'description'  => 'Order #12345',
    'callback_url' => 'https://yoursite.com/webhook'
]);

The customer will immediately receive a push notification on their phone to confirm the payment with their PIN code. Once confirmed, your webhook will receive the success notification.

6Initiating a Wave Payment - Complete Code

The Wave integration is similar but uses the wave provider. Wave generates a payment link that you can redirect the customer to or display as a QR code:

$payment = $client->payments->create([
    'amount'      => 5000,
    'currency'    => 'XOF',
    'provider'    => 'wave',
    'phone'       => '+2250701234567',
    'description' => 'Order #12345'
]);

The response includes a payment_url that you can use to redirect the customer to the Wave app. The process is particularly suited to in-person payments via QR code.

7Implementing Webhooks and Callbacks

Webhooks are essential for receiving payment confirmations in real time. Configure your webhook URL in the ElyonPay dashboard under Settings > Webhooks. Your endpoint must:

1. Verify the webhook signature with the X-ElyonPay-Signature header
2. Handle the events payment.success, payment.failed and payment.refunded
3. Return an HTTP 200 code to confirm receipt

8Error Handling and Edge Cases

Mobile Money payments can fail for various reasons:

• Insufficient balance (INSUFFICIENT_BALANCE)
• Invalid number (INVALID_PHONE)
• Network timeout (TIMEOUT)
• User cancellation (USER_CANCELLED)

Implement robust error handling with clear user messages. Plan a retry mechanism for temporary errors (maximum 3 attempts with exponential backoff). Store the state of each transaction in your database to facilitate reconciliation.

9Sandbox vs Production Mode

Sandbox mode lets you test your integration without real charges. Use the test numbers provided in the documentation:

Before going to production, verify:

1. All error cases are handled
2. Webhooks work correctly
3. Logs are adequate for debugging
4. Reconciliation is automated

Contact ElyonPay support to activate your production account.

10Security Best Practices

Secure your integration by following these rules:

1. Never commit your API keys in your source code - use environment variables
2. Validate all user inputs before sending them to the API
3. Use HTTPS exclusively for all communications
4. Implement signature verification on all webhooks
5. Limit payment attempts per IP to prevent abuse
6. Keep the SDK updated to benefit from security patches