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 ».

Guides par plateforme

Étapes d'installation, configuration et test pour chaque plateforme. Le reste de cette page décrit le principe commun (création de paiement, webhook, remboursement).

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

Plusieurs boutiques sur un même compte

Si vous exploitez plusieurs sites, ou un site et des points de vente, ouvrez une boutique par point de vente depuis Paramètres > Mes offres de votre espace marchand. Chaque boutique peut porter sa propre charte, son propre contact et, si vous en détenez plusieurs, son propre contrat d'encaissement.

La façon recommandée de rattacher un site est sa clé API. Rattachez la clé à sa boutique au moment où vous la créez : le site est alors reconnu tout seul, vous n'avez rien à configurer dans le module, et rien à transmettre à chaque paiement. C'est aussi la seule façon qui reste juste si quelqu'un modifie les réglages du module.

Si une même clé équipe plusieurs sites, transmettez alors storeId à la création du paiement. C'est un champ de premier niveau, à côté de externalId, et il accepte le code de la boutique aussi bien que son identifiant. Les modules WooCommerce, PrestaShop, Magento et Odoo exposent le champ « Boutique Mobupay » dans leurs réglages.

$session = $client->createCheckoutSession(
    $order,
    $redirectUrl,
    $notificationUrl,
    [
        'externalId' => (string) $order->get_id(),
        'storeId'    => 'PAITA', // code de la boutique, ou son identifiant sto_...
    ],
    $idempotencyKey
);

Deux points à connaître. Un storeId inconnu ou désactivé fait échouer l'appel : il n'est jamais ignoré en silence. Et le libellé qui apparaît sur le relevé bancaire de votre client vient du contrat d'encaissement, pas du nom de la boutique : deux boutiques qui partagent le même contrat produisent le même libellé.

Le champ vaut pour tous les moyens de paiement, pas seulement pour les modules : codes de refus, écho de la boutique dans les réponses et comportement en environnement de test sont détaillés dans le guide Plusieurs boutiques.

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.