SDK PHP

Le SDK PHP alphapay/alphapay-php enveloppe l’API REST AlphaPay (checkout, softpay, liens de paiement, clients, webhooks…) avec retry automatique, gestion d’idempotence et exceptions typées par cas d’erreur. Toutes les ressources marchand sont déjà instanciées sur le client — aucun appel HTTP manuel à écrire. Vous utilisez Laravel ? Préférez le SDK Laravel, qui enveloppe ce package avec une Facade, des Events et un trait Eloquent.

composer require alphapay/alphapay-php
export ALPHAPAY_SECRET_KEY=sk_test_votre_cle

1. Checkout (session hébergée)

Une session de checkout génère sa propre page de paiement hébergée (checkout_url) : le client choisit lui-même son réseau et saisit son numéro sur cette page. Contrairement au softpay (section 2), vous n’avez rien à construire côté frontend — juste rediriger le client vers l’URL renvoyée.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    // 1. Créer la session -- idempotencyKey évite de générer deux sessions
    // pour un double-clic ou un retry réseau côté serveur.
    $session = $alphapay->checkoutSessions->create([
        'amount' => 5000,
        'currency' => 'XOF',
        'description' => 'Commande #1234',
        'customer_email' => 'ayaba@exemple.com',
        'customer_name' => 'Ayaba Client',
        'customer_phone' => '+22900000000',
        'return_url' => 'https://votre-site.test/merci',
    ], idempotencyKey: true);

    echo "Session créée : {$session['slug']}\n";
    echo "Redirigez le client vers : {$session['checkout_url']}\n";

    // 2. Plus tard (webhook transaction.success/failed, ou poll manuel) --
    // relire l'état de la session.
    $current = $alphapay->checkoutSessions->get($session['id']);
    echo "Statut actuel : {$current['status']}\n"; // PENDING / PAID / EXPIRED / CANCELLED

    // 3. Annuler une session encore inutilisée (ex. le client a changé de panier).
    // $alphapay->checkoutSessions->cancel($session['id']);
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
    exit(1);
}

2. Softpay (encaissement direct)

Pousse directement une demande de paiement (USSD/mobile money) au numéro du client, sans page de checkout à afficher — utile pour une app mobile ou un parcours de caisse où vous gérez vous-même l’UI. customer exige les 4 champs (email, first_name, last_name, phone) : contrairement à une session de checkout, il n’y a pas de page hébergée où le client les saisirait lui-même après coup.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    $payment = $alphapay->transactions->payinInitialize([
        'amount' => 5000,
        'currency' => 'XOF',
        'country' => 'BJ',
        'network' => 'mtn_bj', // cf. section "Codes réseau" du README -- toujours en minuscules
        'customer' => [
            'email' => 'ayaba@exemple.com',
            'first_name' => 'Ayaba',
            'last_name' => 'Client',
            'phone' => '+22900000000',
        ],
        'description' => 'Commande #1234',
    ], idempotencyKey: true); // recommandé : évite un double push en cas de retry réseau

    echo "Transaction : {$payment['id']} -- statut {$payment['status']}\n";

    // Certains réseaux (Coris Bénin, Wizall Sénégal) exigent un second appel
    // avec le code reçu par SMS APRÈS ce push initial.
    if (!empty($payment['otp_required'])) {
        echo "OTP requis -- collectez le code SMS puis :\n";
        // $confirmed = $alphapay->transactions->payinConfirmOtp($payment['id'], $otpSaisiParLeClient);
    }

    // Consigne à afficher MAINTENANT (ex. "Composez #144*82#") -- vide pour
    // les réseaux qui envoient un prompt spontané (MTN, Wave...).
    if (!empty($payment['instructions'])) {
        echo 'Consigne : ' . json_encode($payment['instructions']) . "\n";
    }

    // Sondage manuel du vrai statut (l'API interroge le gateway) -- à faire
    // depuis un webhook `transaction.*` en production plutôt qu'une boucle.
    sleep(3);
    $verified = $alphapay->transactions->payinVerify($payment['id']);
    echo "Statut vérifié : {$verified['status']}\n";

    // Le numéro était erroné / le client n'a pas répondu à temps : relancer
    // SUR LA MÊME transaction (même montant/client), éventuellement avec un
    // autre gateway.
    // $retry = $alphapay->transactions->payinRetry($payment['id'], ['preferred_gateway' => 'PAYDUNIA']);
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
    if ($e->getFieldErrors() !== null) {
        fwrite(STDERR, 'Champs en erreur : ' . json_encode($e->getFieldErrors()) . "\n");
    }
    exit(1);
}

3. Lien de paiement

Un lien de paiement est réutilisable (contrairement à une session de checkout, one-shot) : sa propre page publique ne nécessite AUCUNE clé API, donc getPublic()/createPublicCheckout() sont les 2 seules méthodes de ce SDK à pouvoir tourner côté client (jamais les autres, qui portent la clé secrète).

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    // 1. Créer le lien (côté serveur, clé secrète) -- options avancées incluses.
    $link = $alphapay->paymentLinks->create([
        'name' => 'Facture #42',
        'amount_type' => 'FIXED', // ou 'FREE' pour laisser le client saisir le montant
        'amount' => 5000,
        'currency' => 'XOF',
        'require_phone' => true,
        'google_ads_id' => 'AW-123456789',
        'custom_fields' => [
            ['key' => 'reference_client', 'label' => 'Référence client', 'required' => true],
        ],
        // 'show_confirmation_page' => false, 'redirect_url' => 'https://votre-site.test/merci', // sinon page de confirmation par défaut
    ]);
    echo "Lien créé : {$link['url']} (slug: {$link['slug']})\n";

    // 2. Côté PUBLIC (page web/app du lien) -- sans clé API, seul le slug circule.
    $publicLink = $alphapay->paymentLinks->getPublic($link['slug']);
    echo "Montant affiché : {$publicLink['amount']} {$publicLink['currency']}\n";

    $checkout = $alphapay->paymentLinks->createPublicCheckout($link['slug'], [
        'customer' => [
            'email' => 'client@exemple.com',
            'first_name' => 'Client',
            'last_name' => 'Test',
            'phone' => '+22900000000', // requis car require_phone=true ci-dessus
        ],
        'custom_field_values' => ['reference_client' => 'CMD-42'],
    ]);
    echo "CheckoutSession créée : {$checkout['slug']}\n";
    echo "Redirigez le client vers : {$checkout['checkout_url']}\n";
    // A partir d'ici, même flux que la section 1 (checkoutSessions->get(), webhook, etc.)

    // 3. Gestion courante du lien.
    $alphapay->paymentLinks->update($link['id'], ['is_active' => false]); // désactive sans supprimer
    $links = $alphapay->paymentLinks->list(['is_active' => true]);
    echo 'Liens actifs : ' . count($links['results']) . "\n";
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
    exit(1);
}

4. Balance

Solde disponible par pays/devise. Lecture seule : les mouvements naissent des autres ressources (paiements, reversements, transferts). Le grand livre détaillé (ledgerEntries) est dashboard-only — inaccessible via clé API.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    $balances = $alphapay->balances->list();
    foreach ($balances['results'] as $balance) {
        echo "{$balance['country']} ({$balance['currency']}) : {$balance['available_amount']} disponible\n";
    }

    if ($balances['results'] !== []) {
        $first = $alphapay->balances->get($balances['results'][0]['id']);
        echo "Détail : " . json_encode($first) . "\n";
    }

    // Dashboard-only -- lève AlphaPayPermissionException (403, "dashboard_only")
    // via une clé API, quel que soit son scope. Gardé ici pour documenter la
    // forme réelle, pas pour un usage effectif avec ce client.
    // $alphapay->balances->ledgerEntries(['country' => 'BJ']);
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
    exit(1);
}

5. Clients (CRM)

Répertoire de clients propre au marchand (distinct de customer passé à payinInitialize/checkoutSessions->create, qui ne fait que remplir une transaction). country ici est un UUID (ForeignKey geo.Country côté API), pas un code ISO2 — contrairement à country sur les paiements/retraits/reversements. Aucune ressource countries dans ce SDK pour résoudre l’UUID : passez par le dashboard ou GET /countries/ via $alphapay->http->request('GET', '/countries/').

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    $countryUuid = 'b03ed84a-6072-442c-beb2-50fc6cd40084'; // Bénin -- relevé depuis le dashboard ou GET /countries/

    $customer = $alphapay->customers->create([
        'country' => $countryUuid,
        'full_name' => 'Ayaba Client',
        'email' => 'ayaba@exemple.com',
        'phone' => '+22900000000',
    ]);
    echo "Client créé : {$customer['id']}\n";

    $alphapay->customers->update($customer['id'], ['email' => 'nouvelle-adresse@exemple.com']);

    $history = $alphapay->customers->transactions($customer['id'], ['page_size' => 20]);
    echo 'Transactions de ce client : ' . count($history['results']) . "\n";

    // $alphapay->customers->delete($customer['id']);
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
    exit(1);
}

6. Webhooks

Créer/gérer un endpoint webhook est dashboard-only (403 via clé API) — seuls list()/get() fonctionnent. En revanche, la vérification de signature d’un webhook reçu est justement ce que ce SDK sert à faire côté serveur marchand.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;
use AlphaPay\Exceptions\AlphaPayWebhookSignatureException;
use AlphaPay\Webhook;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

// --- Consultation (fonctionne via clé API) ---
try {
    $webhooks = $alphapay->webhookEndpoints->list();
    foreach ($webhooks['results'] as $endpoint) {
        echo "{$endpoint['url']} ({$endpoint['environment']}), actif: " . ($endpoint['is_active'] ? 'oui' : 'non') . "\n";
    }

    // La création/modification se fait depuis le dashboard AlphaPay, pas via
    // ce SDK -- gardé ici pour documenter la forme réelle des paramètres.
    // $alphapay->webhookEndpoints->create([
    //     'url' => 'https://votre-site.test/webhooks/alphapay',
    //     'environment' => 'live',
    //     'payment_link' => null, // ou l'id d'un lien précis pour ne recevoir QUE ses événements
    // ]);
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
}

// --- Réception d'un webhook (à placer dans le contrôleur qui reçoit les POST AlphaPay) ---
function handleIncomingWebhook(): void
{
    $rawBody = file_get_contents('php://input'); // corps BRUT -- jamais json_decode() avant vérification
    $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
    $timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
    $secret = getenv('ALPHAPAY_WEBHOOK_SECRET'); // depuis le dashboard, visible une seule fois

    try {
        $event = Webhook::verifySignature($rawBody, $signature, $timestamp, $secret);
    } catch (AlphaPayWebhookSignatureException $e) {
        http_response_code(400);
        echo json_encode(['error' => $e->getMessage()]);
        return;
    }

    // Signature vérifiée -- $event['event'] (ex. "transaction.success") et
    // $event['data'] sont maintenant fiables.
    switch ($event['event']) {
        case 'transaction.success':
            // Créditer la commande locale correspondant à $event['data']['reference'].
            break;
        case 'transaction.failed':
            // Notifier le client, libérer le stock réservé, etc.
            break;
    }

    http_response_code(200);
    echo json_encode(['success' => true]);
}

7. Reversements et transferts wallet

settlements (reversement vers un compte bancaire/mobile money enregistré) et walletTransfers (entre wallets multi-pays d’un même marchand) sont entièrement inaccessibles via clé API, y compris en lecture (403, dashboard_only, vérifié en conditions réelles) — restriction volontaire côté API : ces mouvements ne peuvent être déclenchés/consultés que depuis un compte utilisateur connecté au dashboard. Ce SDK garde ces méthodes pour documenter la forme réelle des endpoints, pas pour un usage effectif ici.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;
use AlphaPay\Exceptions\AlphaPayPermissionException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    $alphapay->settlements->list();
} catch (AlphaPayPermissionException $e) {
    echo "Attendu : {$e->getErrorCode()} -- reversements pilotables uniquement depuis le dashboard.\n";
}

try {
    $alphapay->walletTransfers->create([
        'from_country' => 'CI',
        'to_country' => 'BJ',
        'from_amount' => 10000,
    ], idempotencyKey: true);
} catch (AlphaPayPermissionException $e) {
    echo "Attendu : {$e->getErrorCode()} -- transferts wallet pilotables uniquement depuis le dashboard.\n";
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
}

8. Clés API et whitelist IP

Comme les webhooks, créer/lister/révoquer une clé API est dashboard-only (une clé compromise ne doit pas pouvoir en créer d’autres pour elle-même). Seule la whitelist IP (requise pour les payouts) fonctionne via clé API.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    $entry = $alphapay->apiKeys->ipWhitelist->create([
        'ip_address' => '203.0.113.42',
        'label' => 'Serveur de production',
    ]);
    echo "IP autorisée : {$entry['id']}\n";

    $entries = $alphapay->apiKeys->ipWhitelist->list();
    echo 'IPs en whitelist : ' . count($entries['results']) . "\n";

    $alphapay->apiKeys->ipWhitelist->update($entry['id'], ['status' => 'INACTIVE']);
    // $alphapay->apiKeys->ipWhitelist->delete($entry['id']);
} catch (AlphaPayException $e) {
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n");
    exit(1);
}

9. Gestion des erreurs

Toute erreur API se normalise en une sous-classe d’AlphaPayException — jamais un code HTTP brut à interpréter vous-même.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use AlphaPay\AlphaPayClient;
use AlphaPay\Exceptions\AlphaPayAuthenticationException;
use AlphaPay\Exceptions\AlphaPayException;
use AlphaPay\Exceptions\AlphaPayIdempotencyException;
use AlphaPay\Exceptions\AlphaPayRateLimitException;
use AlphaPay\Exceptions\AlphaPayValidationException;

$alphapay = new AlphaPayClient(getenv('ALPHAPAY_SECRET_KEY'));

try {
    $alphapay->transactions->payinInitialize([
        'amount' => 5000,
        'currency' => 'XOF',
        'country' => 'BJ',
        'network' => 'mtn_bj',
        'customer' => ['email' => 'a@a.com', 'first_name' => 'A', 'last_name' => 'B', 'phone' => '+22900000000'],
    ]);
} catch (AlphaPayValidationException $e) {
    // 400/422 -- $e->getFieldErrors() : ["champ" => ["message", ...], ...] si erreur de validation par champ.
    fwrite(STDERR, "Validation : " . json_encode($e->getFieldErrors()) . "\n");
} catch (AlphaPayAuthenticationException $e) {
    // 401 -- clé API absente/invalide/révoquée.
    fwrite(STDERR, "Auth invalide : {$e->getMessage()}\n");
} catch (AlphaPayIdempotencyException $e) {
    // 409 -- même Idempotency-Key réutilisée avec un payload DIFFÉRENT.
    fwrite(STDERR, "Conflit d'idempotence : {$e->getMessage()}\n");
} catch (AlphaPayRateLimitException $e) {
    // 429 -- déjà retenté automatiquement par le SDK (backoff + Retry-After) avant d'arriver ici.
    fwrite(STDERR, "Rate limit persistant après retries.\n");
} catch (AlphaPayException $e) {
    // Filet générique -- tout statut/erreur non couvert ci-dessus.
    fwrite(STDERR, "Erreur AlphaPay [{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()} (request: {$e->getRequestId()})\n");
}

Prise en main

SDKs & Intégration

Sommaire

1. Checkout (session hébergée)

2. Softpay (encaissement direct)

3. Lien de paiement

4. Balance

5. Clients (CRM)

6. Webhooks

7. Reversements et transferts wallet

8. Clés API et whitelist IP

9. Gestion des erreurs

​Sommaire

​1. Checkout (session hébergée)

​2. Softpay (encaissement direct)

​3. Lien de paiement

​4. Balance

​5. Clients (CRM)

​6. Webhooks

​7. Reversements et transferts wallet

​8. Clés API et whitelist IP

​9. Gestion des erreurs

Sommaire

1. Checkout (session hébergée)

2. Softpay (encaissement direct)

3. Lien de paiement

4. Balance

5. Clients (CRM)

6. Webhooks

7. Reversements et transferts wallet

8. Clés API et whitelist IP

9. Gestion des erreurs