חיבור שער תשלום מותאם
ספק התשלום “אחר” מאפשר לחנות שלך לקבל תשלומים דרך שער התשלום שלך. אתה מוסר ל-MallBasket שני דברים בהקמת חנות: נקודת קצה ליצירת כתובת תשלום (השרת שלך) וסוד משותף. MallBasket שולחת בקשה חתומה לנקודת הקצה שלך כדי לקבל קישור תשלום, והשער שלך שולח webhook חתום בחזרה ל-MallBasket כשהתשלום מסתיים. זוהי אינטגרציה למפתחים.
ההגדרה באפליקציה
בהקמת חנות ← תשלומים מקוונים (מופעל) ← מתקדם ← ספק תשלום, בחר “אחר”, ואז הזן את נקודת הקצה ליצירת כתובת התשלום ואת הסוד המשותף שלך (משמש לחתימת כל הודעה בשני הכיוונים). שמור על הסוד בסוד: כל מי שמחזיק בו יכול לאשר הזמנות.
1. MallBasket מבקשת ממך כתובת תשלום
כשקונה מגיע לתשלום, MallBasket שולחת בקשת POST חתומה לנקודת הקצה שלך. אמת את החתימה, צור אצלך סשן תשלום בדיוק על הסכום והמטבע האלה, והחזר את הכתובת שלו.
{
"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>החזר את כתובת דף התשלום המתארח. MallBasket פותחת אותה עבור הקונה. (גם data.paymentURL ו-url מתקבלים.)
{
"paymentURL": "https://your-gateway.example.com/pay/abc123"
}2. השער שלך מודיע ל-MallBasket (webhook)
אחרי שהקונה משלם, שלח ב-POST הודעה חתומה אל ה-webhookUrl ששלחנו לך. MallBasket מאמתת את החתימה, מוודאת שהסכום תואם להזמנה ומסמנת את ההזמנה כשולמה. שלח סטטוס “success” רק אחרי שהתשלום הושלם בפועל.
{
"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: ערך ה-HMAC-SHA256 בהקסדצימלי (hex) של גוף הבקשה הגולמי (RAW), מחושב עם הסוד המשותף שלך. חשב אותו על הבייטים המדויקים שנשלחים, ואמת בקשות נכנסות על הבייטים הגולמיים שהתקבלו (לא על אובייקט שעבר סריאליזציה מחדש).
// 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” לפני שהכסף נגבה בפועל.