Connecteurs e-commerce

Principe

Un connecteur ne manipule jamais de données carte. À la validation du panier, le plugin crée une session de paiement, redirige le client vers la page hébergée Mobupay (widget Monext), puis la boutique est notifiée par webhook signé. Le client paie sur la page Mobupay, jamais sur le serveur du marchand : le périmètre PCI reste minimal.

1. 1Le client valide son panier sur la boutique.
2. 2Le plugin appelle POST /payments/sessions (server-to-server) et reçoit { paymentId, checkoutUrl, status, expiresAt, externalId }.
3. 3La boutique redirige le client vers checkoutUrl (page hébergée Mobupay).
4. 4Le client paie par carte via le widget Monext, sur la page Mobupay.
5. 5Mobupay envoie un webhook signé (payment.captured) à votre notificationUrl.
6. 6La boutique marque la commande payée et affiche la page « merci ».

1. Créer le paiement

À la validation de la commande, créez une session avec le SDK PHP (mobupay/mobupay-php). Passez l'identifiant de commande de la boutique dans externalId (clé de rapprochement) et une Idempotency-Key pour éviter tout double-paiement sur rejeu réseau.

use Mobupay\MobupayClient;

$client = new MobupayClient($apiKey); // sk_test_* (sandbox) ou sk_live_*

$session = $client->createCheckoutSession(
    ['reference' => $order->get_order_number(), 'amount' => 2500, 'currency' => 'EUR'], // centimes
    $order->get_checkout_order_received_url(), // retour client
    home_url('/?wc-api=mobupay'),              // URL webhook
    ['externalId' => (string) $order->get_id()], // id de commande boutique
    (string) $order->get_id()                    // Idempotency-Key
);

wp_redirect($session['checkoutUrl']); // rediriger le client

2. Recevoir le webhook

Sur votre notificationUrl, vérifiez la signature puis mettez à jour la commande. Récupérez votre secret une fois via GET /api/v1/webhooks/signing-secret (auto-provisionné).

use Mobupay\Webhook;
use Mobupay\MobupayException;

$payload = file_get_contents('php://input'); // CORPS BRUT
try {
    $event = Webhook::verify($payload, getallheaders(), $secret); // V2 anti-rejeu + repli V1
} catch (MobupayException $e) {
    http_response_code(403); exit;
}

// Rapprochement : orderReference = votre order.reference (echo systematique) ;
// externalId = champ libre optionnel passe a la creation. Les deux pointent votre commande.
$orderId = $event['data']['orderReference'] ?? $event['data']['externalId'];
switch ($event['type']) {
    case 'payment.captured':
    case 'payment.authorized':       /* commande payée */ break;
    case 'payment.failed':
    case 'payment.cancelled':
    case 'payment.expired':          /* commande échouée / abandonnée */ break;
    case 'payment.refunded':
    case 'payment.partially_refunded': /* refléter le remboursement */ break;
}
http_response_code(200);

3. Remboursements

Branchez le bouton « rembourser » du back-office de la boutique sur l'API.

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

Règles à respecter

• Le webhook est la source de vérité, jamais le paramètre ?status= de la redirection navigateur (falsifiable par le client). La page de retour n'affiche que « paiement en cours de confirmation ».
• Rapprochement par orderReference : chaque webhook ré-émet le order.reference fourni à la création, ce qui relie l'event à la commande de la boutique sans configuration. Le champ libre externalId reste disponible si vous préférez votre propre clé.
• Abandon client : si le client quitte la page de paiement, Mobupay le renvoie vers votre redirectUrl avec ?status=cancelled et émet payment.cancelled. Libérez la commande sur ce webhook, pas sur le retour navigateur.
• Idempotence côté receiver : un même event peut être livré plusieurs fois (retries). Dédupliquez sur event.id / X-Mobupay-Delivery-Id.
• Testez en sandbox avec une clé sk_test_* : le simulateur délivre les webhooks (signés) à votre notificationUrlcomme en production.

WordPress sans plugin

Pour un site WordPress hors WooCommerce (Easy Digital Downloads, formulaires, page de vente simple), pas besoin d'extension : utilisez les liens de paiement. Créez un lien via POST /payments/links, placez son linkUrl derrière un bouton ou un QR, le client paie sur la page hébergée Mobupay, et la commande est suivie par le même notificationUrl (webhook signé) que les plugins.

$link = $client->createCheckoutLink(
  ['reference' => 'CMD-1042', 'amount' => 2500, 'currency' => 'EUR'],
  'https://mon-site.nc/merci',           // redirectUrl
  'https://mon-site.nc/mobupay-webhook', // notificationUrl (source de vérité)
  ['externalId' => '1042']
);
// $link['linkUrl'] -> à coller dans le bouton de paiement

Mêmes règles que les plugins : statut piloté par le webhook, rapprochement par orderReference, idempotence sur event.id.

SDK & plugins

Le SDK PHP mobupay/mobupay-php (création de paiements, remboursement, vérification de signature) est mutualisé par les plugins WooCommerce, PrestaShop et Magento. Voir aussi le guide Webhooks (signature V2) et Idempotence.