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) :

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

Devises supportées

Opérateurs supportés

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

License

MIT © DEXCHANGE GROUP