MallBasket

Connecter une passerelle de paiement personnalisée

Le fournisseur de paiement « Autre » permet à votre boutique d'encaisser les paiements via votre propre passerelle de paiement. Dans Configuration de la Boutique, vous fournissez deux éléments à MallBasket : un endpoint d'URL de paiement (votre serveur) et un secret partagé. MallBasket envoie une requête signée à votre endpoint pour obtenir un lien de paiement, et votre passerelle renvoie un webhook signé à MallBasket une fois le paiement terminé. Il s'agit d'une intégration pour développeurs.

Configuration dans l'application

Dans Configuration de la Boutique → Paiements en Ligne (Activé) → Avancé → Fournisseur de paiement, choisissez « Autre », puis saisissez votre endpoint d'URL de paiement et votre secret partagé (utilisé pour signer chaque message dans les deux sens). Gardez ce secret privé : toute personne qui le détient peut autoriser des commandes.

1. MallBasket vous demande une URL de paiement

Lorsqu'un acheteur passe au paiement, MallBasket envoie un POST signé à votre endpoint. Vérifiez la signature, créez de votre côté une session de paiement pour exactement ce montant et cette devise, et renvoyez son URL.

POST → votre endpoint · corps (application/json)
{
  "orderId": "6f2a…",              // your MallBasket order id
  "transactionId": "o_6f2a…",     // echo this back in the webhook
  "storeId": "store_abc",
  "userId": "user_123",
  "amount": "12.50",              // decimal string, charge exactly this
  "currency": "USD",
  "email": "buyer@example.com",
  "webhookUrl": "https://europe-west3-mallbasket.cloudfunctions.net/otherWebhook",
  "successUrl": "https://www.mallbasket.com/en/payment/complete?orderId=6f2a…&status=success",
  "cancelUrl": "https://www.mallbasket.com/en/payment/complete?orderId=6f2a…&status=cancelled",
  "nonce": "b1d9…",
  "metadata": { "itemId": "item_1" }
}
En-tête
x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

Renvoyez l'URL de la page de paiement hébergée. MallBasket l'ouvre pour l'acheteur. (data.paymentURL et url sont aussi acceptés.)

Votre réponse · 200 (application/json)
{
  "paymentURL": "https://your-gateway.example.com/pay/abc123"
}

2. Votre passerelle notifie MallBasket (webhook)

Une fois que l'acheteur a payé, envoyez en POST un message signé au webhookUrl que nous vous avons transmis. MallBasket vérifie la signature, confirme que le montant correspond à la commande et marque la commande comme payée. N'envoyez le statut « success » qu'une fois le paiement réellement réglé.

POST → webhookUrl · corps (application/json)
{
  "orderId": "6f2a…",           // same order id
  "transactionId": "o_6f2a…",  // the transactionId we sent you
  "status": "success",          // only send this once payment truly succeeded
  "amount": "12.50",            // must equal the amount we sent
  "currency": "USD",
  "reference": "your-gateway-txn-id"   // optional, shown on the receipt
}
En-tête
x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

3. Signature (dans les deux sens)

Chaque requête porte un en-tête x-mb-signature : le HMAC-SHA256 en hexadécimal du corps BRUT de la requête, calculé avec votre secret partagé. Calculez-le sur les octets exacts envoyés, et vérifiez les requêtes entrantes sur les octets bruts reçus (pas sur un objet resérialisé).

// Node.js: sign the EXACT raw body bytes you are about to send
const crypto = require("crypto");

const rawBody = JSON.stringify(payload);          // the bytes you POST
const signature = crypto
  .createHmac("sha256", MALLBASKET_SECRET)        // your restricted key
  .update(rawBody, "utf8")
  .digest("hex");

// send header:  x-mb-signature: <signature>
Vérifier une requête entrante
// Node.js: verify a request MallBasket sent to your endpoint
const crypto = require("crypto");

function verify(rawBody, headerSig, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")                        // RAW bytes, not re-parsed JSON
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(headerSig || "")
  );
}

Règles et garanties

  • Les montants doivent correspondre : le montant du webhook doit être égal à celui envoyé par MallBasket, dans la même devise, sinon il est rejeté.
  • Renvoyez le transactionId tel quel. C'est grâce à lui que MallBasket associe le paiement à la commande.
  • MallBasket authentifie votre webhook uniquement avec le secret de votre boutique ; une autre boutique ne peut pas finaliser vos commandes.
  • La finalisation est idempotente : vous pouvez renvoyer le webhook sans risque. MallBasket répond 2xx une fois la commande enregistrée ; réessayez pour toute réponse autre que 2xx.
  • N'envoyez jamais le statut « success » avant que l'argent ait réellement été encaissé.