Özel bir ödeme ağ geçidi bağlayın

“Diğer” ödeme sağlayıcısı, mağazanızın ödemeleri kendi ödeme ağ geçidiniz üzerinden almasını sağlar. Mağaza Kurulumu'nda MallBasket'e iki şey verirsiniz: bir ödeme URL'si uç noktası (sunucunuz) ve paylaşılan bir gizli anahtar. MallBasket, ödeme bağlantısı almak için uç noktanıza imzalı bir istek gönderir; ödeme tamamlandığında ağ geçidiniz de MallBasket'e imzalı bir webhook gönderir. Bu bir geliştirici entegrasyonudur.

Uygulamada ayarlayın

Mağaza Kurulumu → Online Ödemeler (Etkin) → Gelişmiş → Ödeme Sağlayıcısı bölümünde “Diğer”i seçin, ardından ödeme URL'si uç noktanızı ve paylaşılan gizli anahtarınızı girin (her iki yöndeki her mesajı imzalamak için kullanılır). Gizli anahtarı kimseyle paylaşmayın: ona sahip olan herkes siparişleri onaylayabilir.

1. MallBasket sizden bir ödeme URL'si ister

Bir alıcı ödeme yaptığında MallBasket, uç noktanıza imzalı bir POST gönderir. İmzayı doğrulayın, kendi tarafınızda tam olarak bu tutar ve para birimi için bir ödeme oturumu oluşturun ve URL'sini döndürün.

POST → uç noktanız · gövde (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" }
}

Başlık

x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

Barındırılan ödeme URL'sini döndürün. MallBasket bunu alıcı için açar. (data.paymentURL ve url de kabul edilir.)

Yanıtınız · 200 (application/json)

{
  "paymentURL": "https://your-gateway.example.com/pay/abc123"
}

2. Ağ geçidiniz MallBasket'i bilgilendirir (webhook)

Alıcı ödedikten sonra, size gönderdiğimiz webhookUrl adresine imzalı bir mesajı POST ile gönderin. MallBasket imzayı doğrular, tutarın siparişle eşleştiğini onaylar ve siparişi ödendi olarak işaretler. “success” durumunu yalnızca ödeme gerçekten tamamlandığında gönderin.

POST → webhookUrl · gövde (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
}

Başlık

x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

3. İmzalama (her iki yönde)

Her istek bir x-mb-signature başlığı taşır: paylaşılan gizli anahtarınızla hesaplanan, HAM istek gövdesinin onaltılık (hex) HMAC-SHA256 değeri. Bunu tam olarak gönderilen baytlar üzerinden hesaplayın, gelen istekleri de aldığınız ham baytlar üzerinden doğrulayın (yeniden serileştirilmiş bir nesne üzerinden değil).

// 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>

Gelen bir isteği doğrulayın

// 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 || "")
  );
}

Kurallar ve güvenceler

Tutarlar eşleşmelidir: webhook tutarı, MallBasket'in gönderdiği tutara aynı para biriminde eşit olmalıdır, aksi halde reddedilir.
transactionId değerini aynen geri gönderin. MallBasket ödemeyi siparişle bu değer üzerinden eşleştirir.
MallBasket webhook'unuzu yalnızca mağazanızın gizli anahtarıyla doğrular; başka bir mağaza sizin siparişlerinizi tamamlayamaz.
Sonlandırma idempotent'tir: webhook'u yeniden denemek güvenlidir. Sipariş kaydedildiğinde MallBasket 2xx döndürür; 2xx olmayan her yanıtta yeniden deneyin.
Para gerçekten tahsil edilmeden asla “success” durumunu göndermeyin.