README

SDK officiel PHP pour l'API DEXPAY - Paiements Mobile Money pour l'Afrique de l'Ouest.

Compatible Laravel, Symfony, WordPress et tout projet PHP 8.1+.
Aucune dépendance externe — utilise cURL natif.

Installation

composer require dexchangepay/dexpay-php

Démarrage rapide

use DexchangePay\DexPay;

$dexpay = new DexPay(
    apiKey:    'pk_test_xxx',   // Votre clé publique
    apiSecret: 'sk_test_xxx',  // Votre clé secrète
);

// Créer une session de paiement
$session = $dexpay->checkoutSessions->create([
    'reference'   => 'ORDER_123',
    'item_name'   => 'Premium Plan',
    'amount'      => 10000, // 10 000 XOF
    'currency'    => 'XOF',
    'success_url' => 'https://example.com/success',
    'failure_url' => 'https://example.com/cancel',
    'webhook_url' => 'https://example.com/webhook',
]);

// Rediriger le client vers la page de paiement
header('Location: ' . $session['data']['payment_url']);

Checkout Sessions

Créer une session

$session = $dexpay->checkoutSessions->create([
    'reference'          => 'ORDER_123',
    'item_name'          => 'Abonnement Premium',
    'amount'             => 10000,
    'currency'           => 'XOF',
    'success_url'        => 'https://example.com/success',
    'failure_url'        => 'https://example.com/cancel',
    'webhook_url'        => 'https://example.com/webhook',
    'metadata'           => ['user_id' => '123'],
    'expires_at'         => '2025-12-31T23:59:59Z', // Optionnel
    'client_support_fee' => true,                    // Optionnel
]);

Récupérer une session

// Par ID
$session = $dexpay->checkoutSessions->retrieve('session_id');

// Par référence
$session = $dexpay->checkoutSessions->retrieveByReference('ORDER_123');

Lister les sessions

$sessions = $dexpay->checkoutSessions->list(['page' => 1, 'limit' => 10]);

Créer une tentative de paiement Mobile Money

$attempt = $dexpay->checkoutSessions->createPaymentAttempt('ORDER_123', [
    'payment_method' => 'MOBILE_MONEY',
    'operator'       => 'wave',  // wave, orange_money, mtn, moov
    'countryISO'     => 'SN',    // SN, CI, ML, BF, etc.
    'customer'       => [
        'name'  => 'Jean Dupont',
        'phone' => '+221771234567',
        'email' => 'jean@example.com',
    ],
]);

echo $attempt['data']['payment_url'];

Rembourser une session

$refund = $dexpay->checkoutSessions->refund('ORDER_123');
echo $refund['status']; // success

Payouts (Retraits)

$payout = $dexpay->payouts->create([
    'amount'              => 10000,
    'currency'            => 'XOF',
    'destination_phone'   => '+221771234567',
    'destination_details' => [
        'operator'       => 'wave',
        'countryISO'     => 'SN',
        'recipient_name' => 'Jean Dupont',
    ],
    'metadata' => ['invoice_id' => 'INV_123'],
]);

// Récupérer, lister
$dexpay->payouts->retrieve('payout_id');
$dexpay->payouts->list(['page' => 1, 'limit' => 10, 'status' => 'COMPLETED']);

Balances

$res = $dexpay->balances->list();
echo $res['data'][0]['balance'] . ' ' . $res['data'][0]['currency'];

Providers

// Providers de collecte (paiement)
$payment = $dexpay->paymentProviders->list(['provider_country' => 'SN']);

// Providers de retrait (payout)
$payout = $dexpay->payoutProviders->list();

Products

// Produit ponctuel
$product = $dexpay->products->create([
    'name'     => 'T-Shirt',
    'price'    => 5000,
    'currency' => 'XOF',
    'type'     => 'ONE_TIME',
]);

// Produit récurrent
$plan = $dexpay->products->create([
    'name'           => 'Premium Plan',
    'price'          => 10000,
    'currency'       => 'XOF',
    'type'           => 'RECURRING',
    'billing_period' => 'MONTHLY',
]);

$dexpay->products->list(['type' => 'RECURRING', 'is_active' => true]);
$dexpay->products->update('prod_123', ['price' => 15000]);
$dexpay->products->delete('prod_123');

Customers

$customer = $dexpay->customers->create([
    'name'    => 'Jean Dupont',
    'email'   => 'jean@example.com',
    'phone'   => '+221771234567',
    'country' => 'SN',
]);

// Rechercher
$dexpay->customers->list(['email' => 'jean@example.com']);
$dexpay->customers->list(['phone' => '+221771234567']);
$dexpay->customers->update('cus_123', ['country' => 'CI']);

Subscriptions

$sub = $dexpay->subscriptions->create([
    'customer_id' => 'cus_123',
    'product_id'  => 'prod_456',
]);

$dexpay->subscriptions->update('sub_123', ['status' => 'PAUSED']);
$dexpay->subscriptions->cancel('sub_123');

Gestion des erreurs

use DexchangePay\DexPay;
use DexchangePay\Exceptions\DexPayException;

try {
    $session = $dexpay->checkoutSessions->create([...]);
} catch (DexPayException $e) {
    echo $e->getErrorCode();   // VALIDATION_ERROR
    echo $e->getMessage();     // Invalid amount
    echo $e->getStatusCode();  // 400
}

Intégration frameworks

Laravel

// config/services.php
'dexpay' => [
    'key'     => env('DEXPAY_API_KEY'),
    'secret'  => env('DEXPAY_API_SECRET'),
    'sandbox' => env('DEXPAY_SANDBOX', false),
],

// AppServiceProvider.php
use DexchangePay\DexPay;

$this->app->singleton(DexPay::class, fn() => new DexPay(
    apiKey:    config('services.dexpay.key'),
    apiSecret: config('services.dexpay.secret'),
    sandbox:   config('services.dexpay.sandbox'),
));

// PaymentController.php
public function webhook(Request $request): JsonResponse
{
    $event = $request->json()->all();

    match ($event['type']) {
        'checkout.completed' => $this->handleSuccess($event['data']),
        'checkout.failed'    => $this->handleFailure($event['data']),
        'payout.completed'   => $this->handlePayout($event['data']),
        default              => null,
    };

    return response()->json(['received' => true]);
}

Symfony

// services.yaml
DexchangePay\DexPay:
    arguments:
        $apiKey:    '%env(DEXPAY_API_KEY)%'
        $apiSecret: '%env(DEXPAY_API_SECRET)%'
        $sandbox:   '%env(bool:DEXPAY_SANDBOX)%'

// WebhookController.php
#[Route('/webhook', methods: ['POST'])]
public function webhook(Request $request): JsonResponse
{
    $event = json_decode($request->getContent(), true);
    // traiter $event['type']
    return new JsonResponse(['received' => true]);
}

WordPress

require_once plugin_dir_path(__FILE__) . 'vendor/autoload.php';

use DexchangePay\DexPay;

$dexpay = new DexPay(
    apiKey:    get_option('dexpay_api_key'),
    apiSecret: get_option('dexpay_api_secret'),
    sandbox:   (bool) get_option('dexpay_sandbox'),
);

// Webhook via WP REST API
add_action('rest_api_init', function () {
    register_rest_route('dexpay/v1', '/webhook', [
        'methods'  => 'POST',
        'callback' => function ($request) {
            $event = $request->get_json_params();
            // traiter $event['type']
            return ['received' => true];
        },
        'permission_callback' => '__return_true',
    ]);
});

Webhooks

Évènements envoyés par DEXPAY (POST JSON sur votre webhook_url) :

Évènement	Description
`checkout.completed`	Paiement réussi
`checkout.failed`	Paiement échoué
`payout.completed`	Payout réussi
`payout.failed`	Payout échoué
`subscription.created`	Abonnement créé
`subscription.cancelled`	Abonnement annulé

Configuration avancée

// Production (défaut)
$dexpay = new DexPay(apiKey: 'pk_live_xxx', apiSecret: 'sk_live_xxx');

// Sandbox (test)
$dexpay = new DexPay(
    apiKey:    'pk_test_xxx',
    apiSecret: 'sk_test_xxx',
    sandbox:   true,
);

// Personnalisée
$dexpay = new DexPay(
    apiKey:    'pk_live_xxx',
    apiSecret: 'sk_live_xxx',
    baseUrl:   'https://api.dexpay.africa/api/v1',
    timeout:   60,
);

URLs de l'API

Environnement	URL
Production	https://api.dexpay.africa/api/v1
Sandbox	https://api-sandbox.dexpay.africa/api/v1

Devises supportées

Code	Devise
XOF	Franc CFA BCEAO (Sénégal, Côte d'Ivoire, Mali, Burkina Faso, etc.)
XAF	Franc CFA BEAC (Cameroun, Gabon, Congo, etc.)
GNF	Franc Guinéen

Opérateurs supportés

Opérateur	Code	Pays
Wave	`wave`	SN, CI, ML, BF
Orange Money	`orange_money`	SN, CI, ML, BF, GN
MTN	`mtn`	CI, BF
Moov	`moov`	CI, BF

Prérequis

PHP 8.1+
Extension ext-curl
Extension ext-json

Développement

composer install
composer test       # Lance PHPUnit

Support

📧 Email : support@dexpay.africa
📖 Documentation : https://docs.dexpay.africa
🐙 GitHub : https://github.com/DEXCHANGE-GROUP/dexpay-php
🐛 Issues : https://github.com/DEXCHANGE-GROUP/dexpay-php/issues

dexchangepay / dexpay-php

Maintainers

Package info

Statistics

Security