mobupay-php

SDK PHP officiel Mobupay. Mutualise par les connecteurs e-commerce (WooCommerce, PrestaShop, Magento) pour : créer des paiements (session / lien), rembourser, et vérifier la signature des webhooks.

Le client ne manipule jamais de données carte : le client final paie sur la page hébergée Mobupay (widget Monext), puis le marchand est notifié par webhook signé.

Installation

composer require mobupay/mobupay-php

Dépendances : PHP >= 7.4, extensions curl, json, hash (toutes standard).

Licence : MIT.

Transport HTTP personnalisé

Par défaut le SDK utilise cURL (CurlTransport). Les environnements qui imposent leur propre pile HTTP peuvent injecter un transport implémentant Mobupay\HttpTransportInterface (4e argument du constructeur). Exemple : le plugin WordPress officiel injecte un transport basé sur wp_remote_request (exigence du répertoire wordpress.org).

Démarrage

use Mobupay\MobupayClient;

// Clé test (sandbox) ou live. 2e argument optionnel = base API (défaut : https://api.mobupay.nc)
$client = new MobupayClient('sk_test_xxx');

$session = $client->createCheckoutSession(
    ['reference' => 'CMD-1042', 'amount' => 2500, 'currency' => 'EUR'], // montant en centimes
    'https://maboutique.nc/commande/merci',   // retour client
    'https://maboutique.nc/?wc-api=mobupay',  // URL webhook
    ['externalId' => '1042'],                 // id de commande boutique (clé de rapprochement)
    'CMD-1042'                                 // Idempotency-Key (anti double-paiement)
);

header('Location: ' . $session['checkoutUrl']); // rediriger le client

Vérifier un webhook (obligatoire)

À la réception d'une notification sur votre notificationUrl :

use Mobupay\Webhook;
use Mobupay\MobupayException;

$payload = file_get_contents('php://input'); // CORPS BRUT, non re-décodé
$secret  = 'whsec_xxx'; // = $client->getSigningSecret(), à récupérer/stocker une fois

try {
    $event = Webhook::verify($payload, getallheaders(), $secret);
} catch (MobupayException $e) {
    http_response_code(403);
    exit;
}

// $event = ['id', 'type', 'createdAt', 'data' => ['paymentId', 'externalId', 'status', 'amount', 'currency', ...]]
$orderId = $event['data']['externalId']; // votre id de commande
switch ($event['type']) {
    case 'payment.captured':
    case 'payment.authorized':
        // marquer la commande payée
        break;
    case 'payment.failed':
    case 'payment.cancelled':
    case 'payment.expired':
        // marquer la commande échouée / abandonnée
        break;
    case 'payment.refunded':
    case 'payment.partially_refunded':
        // refléter le remboursement
        break;
}
http_response_code(200);

Webhook::verify privilégie le schéma V2 (X-Mobupay-Signature-V2 + X-Mobupay-Timestamp, anti-rejeu : horodatage signé, tolérance 5 min par défaut) et retombe sur V1 (X-Mobupay-Signature) si V2 absent.

Règle d'or

Le statut de commande est piloté par le webhook signé, jamais par le paramètre ?status= de la redirection navigateur (falsifiable). La redirection ne sert qu'à afficher « paiement en cours de confirmation ».

Remboursement

$client->refund('pay_xxx');        // total
$client->refund('pay_xxx', 1000);  // partiel : 10,00 EUR (centimes)

Récupérer / stocker le secret de signature

$secret = $client->getSigningSecret(); // 'whsec_...'

Il est auto-provisionné à la première création de clé API. Vous pouvez aussi le récupérer via GET /api/v1/webhooks/signing-secret ou le faire tourner via POST /api/v1/webhooks/signing-secret/rotate.