MallBasket

カスタム決済ゲートウェイを接続

チェックアウトプロバイダー「その他」を使うと、ストアは独自の決済ゲートウェイで支払いを受け取れます。「ストア設定」で MallBasket に登録するのは、決済 URL を発行するエンドポイント（あなたのサーバー）と共有シークレットの 2 つです。MallBasket は決済リンクを取得するためにエンドポイントへ署名付きリクエストを送り、支払いが完了するとゲートウェイから MallBasket へ署名付きの webhook を返します。これは開発者向けの連携機能です。

アプリで設定する

「ストア設定 → オンライン決済（有効）→ アドバンスト → チェックアウトプロバイダー」で「その他」を選び、決済 URL のエンドポイントと共有シークレット（双方向のすべてのメッセージの署名に使用）を入力します。シークレットは厳重に管理してください。これを持つ人は誰でも注文を承認できてしまいます。

1. MallBasket が決済 URL をリクエスト

購入者が支払いに進むと、MallBasket はエンドポイントに署名付きの POST を送信します。署名を検証し、ちょうどこの金額と通貨で決済セッションを作成して、その URL を返してください。

POST → あなたのエンドポイント · 本文（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" }
}
ヘッダー
x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

ホスト型決済ページの URL を返します。MallBasket がそれを購入者に表示します。（data.paymentURL と url も使用できます。）

レスポンス · 200（application/json）
{
  "paymentURL": "https://your-gateway.example.com/pay/abc123"
}

2. ゲートウェイが MallBasket に通知（webhook）

購入者が支払った後、こちらから送った webhookUrl に署名付きメッセージを POST してください。MallBasket は署名を検証し、金額が注文と一致することを確認して、注文を支払い済みにします。ステータス「success」は、支払いが実際に完了してから送信してください。

POST → webhookUrl · 本文（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
}
ヘッダー
x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

3. 署名（双方向）

すべてのリクエストには x-mb-signature ヘッダーが付きます。これは共有シークレットを使って計算した、リクエスト本文の生データ（RAW）の HMAC-SHA256（16 進数）です。送信する正確なバイト列に対して計算し、受信したリクエストは受け取った生のバイト列で検証してください（再シリアライズしたオブジェクトではありません）。

// 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>
受信したリクエストを検証する
// 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 || "")
  );
}

ルールと保証

  • 金額は一致している必要があります：webhook の金額は、MallBasket が送った金額と同じ通貨で等しくなければならず、一致しない場合は拒否されます。
  • transactionId はそのまま返してください。MallBasket はこれを使って支払いと注文を照合します。
  • MallBasket はストアのシークレットだけで webhook を認証するため、ほかのストアがあなたの注文を完了させることはできません。
  • 確定処理はべき等（idempotent）です。webhook は安全に再送できます。注文が記録されると MallBasket は 2xx を返します。2xx 以外の場合は再送してください。
  • 実際に入金（キャプチャ）される前に、ステータス「success」を送信しないでください。