MallBasket

Individuelles Zahlungsgateway verbinden

Mit dem Checkout-Anbieter „Andere“ nimmt Ihr Shop Zahlungen über Ihr eigenes Zahlungsgateway an. Sie hinterlegen in der Shop-Einrichtung zwei Dinge für MallBasket: einen Payment-URL-Endpunkt (Ihren Server) und ein gemeinsames Secret. MallBasket sendet eine signierte Anfrage an Ihren Endpunkt, um einen Zahlungslink zu erhalten, und Ihr Gateway sendet einen signierten Webhook an MallBasket zurück, wenn die Zahlung abgeschlossen ist. Dies ist eine Integration für Entwickler.

Einrichtung in der App

Wählen Sie unter Shop-Einrichtung → Online-Zahlungen (Aktiviert) → Erweitert → Checkout-Anbieter die Option „Andere“ und geben Sie dann Ihren Payment-URL-Endpunkt und Ihr gemeinsames Secret ein (damit wird jede Nachricht in beide Richtungen signiert). Halten Sie das Secret geheim: Wer es besitzt, kann Bestellungen autorisieren.

1. MallBasket fordert eine Payment-URL bei Ihnen an

Wenn ein Käufer zur Kasse geht, sendet MallBasket einen signierten POST an Ihren Endpunkt. Prüfen Sie die Signatur, erstellen Sie auf Ihrer Seite eine Zahlungssitzung über genau diesen Betrag und diese Währung und geben Sie deren URL zurück.

POST → Ihr Endpunkt · Body (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" }
}
Header
x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

Geben Sie die URL der gehosteten Zahlungsseite zurück. MallBasket öffnet sie für den Käufer. (data.paymentURL und url werden ebenfalls akzeptiert.)

Ihre Antwort · 200 (application/json)
{
  "paymentURL": "https://your-gateway.example.com/pay/abc123"
}

2. Ihr Gateway benachrichtigt MallBasket (Webhook)

Nachdem der Käufer bezahlt hat, senden Sie per POST eine signierte Nachricht an die webhookUrl, die wir Ihnen geschickt haben. MallBasket prüft die Signatur, bestätigt, dass der Betrag zur Bestellung passt, und markiert die Bestellung als bezahlt. Senden Sie den Status „success“ erst, wenn die Zahlung tatsächlich abgeschlossen ist.

POST → webhookUrl · Body (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
}
Header
x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

3. Signierung (in beide Richtungen)

Jede Anfrage enthält einen x-mb-signature-Header: den HMAC-SHA256 (hex) des ROHEN Anfrage-Bodys, berechnet mit Ihrem gemeinsamen Secret. Berechnen Sie ihn über genau die gesendeten Bytes und prüfen Sie eingehende Anfragen anhand der empfangenen Rohbytes (nicht anhand eines neu serialisierten Objekts).

// 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>
Eingehende Anfrage prüfen
// 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 || "")
  );
}

Regeln und Garantien

  • Beträge müssen übereinstimmen: Der Webhook-Betrag muss dem von MallBasket gesendeten Betrag in derselben Währung entsprechen, sonst wird er abgelehnt.
  • Geben Sie die transactionId unverändert zurück. Darüber ordnet MallBasket die Zahlung der Bestellung zu.
  • MallBasket authentifiziert Ihren Webhook ausschließlich mit dem Secret Ihres Shops; ein anderer Shop kann Ihre Bestellungen nicht abschließen.
  • Der Abschluss ist idempotent: Der Webhook kann gefahrlos wiederholt werden. MallBasket gibt 2xx zurück, sobald die Bestellung erfasst ist; wiederholen Sie bei jeder anderen Antwort als 2xx.
  • Senden Sie den Status „success“ niemals, bevor das Geld tatsächlich eingezogen wurde.