The comprehensive payment gateway for Bow Framework. Built to make integrating African mobile money payment providers seamless, secure, and reliable.
This package helps developers easily integrate local mobile payment APIs such as Orange Money, Moov Money (commonly called Flooz), MTN Mobile Money, Wave, and Djamo with advanced features like retry logic, rate limiting, transaction logging, and webhook handling.
- ✅ Orange Money (Ivory Coast) - Fully implemented
- ✅ MTN Mobile Money (Ivory Coast) - Fully implemented
- 📦 Moov Money (Flooz) - Gateway ready, pending API documentation
- 📦 Wave - Gateway ready, pending API documentation
- 📦 Djamo - Gateway ready, pending API documentation
Install the package using composer, the PHP package manager:
composer require bowphp/paymentConfigure your payment providers in your config/payment.php:
use Bow\Payment\Payment;
return [
'default' => [
'gateway' => Payment::ORANGE,
'country' => 'ci',
],
'ivory_coast' => [
'orange' => [
'client_key' => env('ORANGE_CLIENT_KEY'),
'client_secret' => env('ORANGE_CLIENT_SECRET'),
'webhook_secret' => env('ORANGE_WEBHOOK_SECRET'),
],
'mtn' => [
'subscription_key' => env('MTN_SUBSCRIPTION_KEY'),
'api_user' => env('MTN_API_USER'),
'api_key' => env('MTN_API_KEY'),
'environment' => 'sandbox', // or 'production'
'webhook_secret' => env('MTN_WEBHOOK_SECRET'),
],
// Other providers...
],
];use Bow\Payment\Payment;
// Configure the payment gateway
Payment::configure($config);
// Make a payment
Payment::payment([
'amount' => 1000,
'reference' => 'ORDER-123',
'notif_url' => 'https://your-app.com/webhook',
'return_url' => 'https://your-app.com/success',
'cancel_url' => 'https://your-app.com/cancel',
]);
// Verify a transaction
$status = Payment::verify([
'amount' => 1000,
'order_id' => 'ORDER-123',
'pay_token' => 'TOKEN',
]);
if ($status->isSuccess()) {
// Payment successful
}Add the UserPayment trait to your User model:
use Bow\Payment\UserPayment;
class User extends Model
{
use UserPayment;
}
// Now you can use payment methods on your user model
$user->payment(1000, 'ORDER-123');
$user->transfer(5000, 'TRANSFER-456');Automatically retry failed API calls with exponential backoff:
use Bow\Payment\Support\RetryHandler;
$retry = new RetryHandler(
maxAttempts: 3,
retryDelay: 1000,
exponentialBackoff: true
);
$result = $retry->execute(function() use ($payment) {
return $payment->pay($amount);
});Protect your application from exceeding API rate limits:
use Bow\Payment\Support\RateLimiter;
$limiter = new RateLimiter(
maxRequests: 60,
timeWindow: 60
);
if ($limiter->isAllowed('orange')) {
$limiter->hit('orange');
// Make API call
}Comprehensive audit trail for all payment operations:
use Bow\Payment\Support\TransactionLogger;
$logger = new TransactionLogger('/path/to/logs');
// Logs are automatically created with detailed context
$logger->logPaymentRequest('mtn', [
'amount' => 1000,
'reference' => 'ORDER-123'
]);
$logger->logPaymentResponse('mtn', true, $response);Secure webhook processing with signature validation:
use Bow\Payment\Webhook\WebhookHandler;
$handler = new WebhookHandler('orange', $config['webhook_secret']);
$request = WebhookHandler::parseRequest();
$event = $handler->handle($request['payload'], $request['signature']);
if ($event->isPaymentSuccess()) {
$transactionId = $event->getTransactionId();
$amount = $event->getAmount();
// Update order status
}Comprehensive custom exceptions for better error handling:
use Bow\Payment\Exceptions\PaymentRequestException;
use Bow\Payment\Exceptions\RateLimitException;
use Bow\Payment\Exceptions\TokenGenerationException;
try {
Payment::payment($data);
} catch (RateLimitException $e) {
// Rate limit exceeded
$retryAfter = $e->getCode();
} catch (PaymentRequestException $e) {
// Payment request failed
Log::error($e->getMessage());
} catch (TokenGenerationException $e) {
// Token generation failed
}Payment::configure([
'default' => [
'gateway' => Payment::ORANGE,
'country' => 'ci',
],
'ivory_coast' => [
'orange' => [
'client_key' => 'YOUR_CLIENT_KEY',
'client_secret' => 'YOUR_CLIENT_SECRET',
],
],
]);
$result = Payment::payment([
'amount' => 1000,
'reference' => 'ORDER-123',
'notif_url' => 'https://your-app.com/webhook',
'return_url' => 'https://your-app.com/success',
'cancel_url' => 'https://your-app.com/cancel',
]);Payment::configure([
'default' => [
'gateway' => Payment::MTN,
'country' => 'ci',
],
'ivory_coast' => [
'mtn' => [
'subscription_key' => 'YOUR_SUBSCRIPTION_KEY',
'api_user' => 'YOUR_API_USER',
'api_key' => 'YOUR_API_KEY',
'environment' => 'sandbox',
],
],
]);
$result = Payment::payment([
'amount' => 1000,
'phone' => '0707070707',
'reference' => 'ORDER-123',
]);
// Verify transaction
$status = Payment::verify(['reference_id' => $result['reference_id']]);
// Check balance
$balance = Payment::balance();// Start with Orange Money
Payment::configure($config);
// Switch to MTN for a specific transaction
Payment::withProvider('ci', Payment::MTN);
Payment::payment($data);- ✅ Simple, fluent API
- ✅ Multiple payment provider support (Orange Money, MTN Mobile Money)
- ✅ Dynamic provider switching
- ✅ Transaction status verification
- ✅ User model integration via traits
- ✅ Webhook handling with signature validation
- ✅ Transfer support
- ✅ Balance inquiry
- ✅ Automatic retry logic with exponential backoff
- ✅ Rate limiting protection
- ✅ Transaction audit logging
- ✅ Comprehensive exception handling
- ✅ Sandbox and production environment support
- PHP >= 7.4 (PHP 8.0+ recommended)
- Bow Framework >= 4.0
- GuzzleHTTP >= 6.5
Run the test suite:
composer testThe package includes comprehensive tests for:
- Transaction logging
- Retry logic
- Rate limiting
- Webhook handling
- Payment configuration
Contributions are welcome! Please feel free to submit a Pull Request.
- Follow PSR-12 coding standards
- Add tests for new features
- Update documentation
- Ensure all tests pass before submitting PR
See UPGRADE_SUMMARY.md for recent changes and improvements.
The Bow Payment package is open-sourced software licensed under the MIT license.
If you find this project helpful, consider supporting its development:
- Franck DAKIA - Lead Developer
- All Contributors