API referansı

Makine tarafından okunabilir şema: GET /api/v1/openapi.json — Postman/Insomnia'ya aktarılabilir (OpenAPI 3.1).

• ·Her ödeme SİZİN bankanızın sanal POS terminalinde çekilir; böylece bankanızın normal mutabakat döngüsünde SİZİN üye işyeri hesabınıza geçer — tıpkı bankayı doğrudan entegre etmiş gibi.
• ·Paranızı asla tutmaz, havuzda toplamaz veya bir platform hesabından geçirmeyiz. Ödeme adımı, çekilecek bir bakiye veya işlem tutarından platform payı yoktur.
• ·Bankanızın size verdiği sanal POS bilgilerini panele bir kez girersiniz. O andan itibaren canlı ödemeleriniz doğrudan bankanıza akar.
• ·Paneldeki Mutabakat görünümü, banka ve gün bazında çekilen ve iade edilen tutarların bir raporudur — bizim yaptığımız bir ödeme (payout) değildir.

Sandbox ortamı ödeme altyapısı tarafından işletilir. sk_test_ anahtarlarınız bizim ortak banka test terminallerimizi kullanır — yapılandırmanız gereken bir şey yok, bankayla anlaşmanıza da gerek yok. Kendi bilgileriniz yalnızca canlı ortam içindir.

{
  "id": "pay_2c7d8e…",
  "status": "captured",
  "provider": "isbank",
  "simulated": true,
  "simulatedReason": "NO_SANDBOX_CREDENTIALS"
}

• ·Her ödeme yanıtı `simulated` alanı taşır. İstek gerçek bir bankaya ulaştığında false olur.
• ·Sandbox erişimimiz olan bankalarda sk_test_ trafiği bankanın kendi test adresine gider — bizim değil, o bankanın test kartlarını kullanın.
• ·Henüz sandbox erişimimiz olmayan bir banka için altyapı sonucu simüle eder ve `simulated: true` ile bir `simulatedReason` döner. Yanıt yapısı birebir aynıdır; banka gerçek sandbox'a geçtiğinde entegrasyonunuz değişmez.
• ·Bize ait `7433` test kartları, gerçek sandbox'ı olan bir bankada bile her zaman simülatör tarafından yanıtlanır (`simulated: true`, sebep `MHPAY_TEST_CARD`) — böylece senaryo kartları her yerde çalışır. Gerçek sandbox'lı bir bankada başka herhangi bir kart bankaya ulaşır.
• ·Canlı ödemeler asla simüle edilmez — sk_live_ trafiğinde `simulated` her zaman false'tur.

Authorization: MHPAYv1 base64("apiKey:<pk>&randomKey:<rnd>&signature:<hex>")
x-mhpay-timestamp: <unix seconds>

signature = HMAC-SHA256(secret, `${timestamp}.${randomKey}.${path}.${rawBody}`)

• ·path includes the query string (e.g. /api/v1/payments?limit=50).
• ·rawBody is the exact bytes you send (empty string for GET).
• ·randomKey is fresh per request; the server accepts a ±300s window.

import { createHmac, randomBytes } from 'crypto';

function mhpayHeaders(pk, secret, path, body) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const randomKey = randomBytes(12).toString('hex');
  const signature = createHmac('sha256', secret)
    .update(`${timestamp}.${randomKey}.${path}.${body}`)
    .digest('hex');
  const raw = `apiKey:${pk}&randomKey:${randomKey}&signature:${signature}`;
  return {
    Authorization: `MHPAYv1 ${Buffer.from(raw).toString('base64')}`,
    'x-mhpay-timestamp': timestamp,
    'Content-Type': 'application/json',
  };
}

{
  "amount": 15000,
  "currency": "TRY",
  "orderId": "order-1024",
  "callbackUrl": "https://store.example/checkout/return",
  "returnUrl": "https://store.example/orders/1024",
  "use3ds": true
}

{
  "token": "cs_9f2a7b…",
  "url": "https://pay.magazamhazir.com/pay/cs_9f2a7b…",
  "expiresAt": "2026-07-19T18:40:00.000Z"
}

1. 1Oturumu oluşturun (imzalı, sunucu tarafında).
2. 2Alışveriş yapanı url adresine yönlendirin. Sayfa ödeme alıcısını — üye işyeri adınızı — gösterir ve kartı alır.
3. 3Banka yanıt verdiğinde onu callbackUrl?paymentId=…&status=… adresine (3-D Secure sonrasında ek olarak signature ile) gönderir ve bir webhook tetikleriz.

• ·status değeri success (tahsil edildi), failed ya da pending olur: pending, bankanın yanıtının henüz doğrulanamadığı anlamına gelir. pending’i ÖDENMEMİŞ sayın ve üzerine yeniden deneme önermeyin; her sonucu yalnızca URL’ye değil, webhook’a veya GET /v1/payments/:id yanıtına göre kesinleştirin.
• ·returnUrl (isteğe bağlı) alışveriş yapanın geri dönüş yoludur: sipariş sayfanız — sunucunuzun dönüş rotası olan callbackUrl değil. Barındırılan sayfa bunu her son durumda (kullanılmış, süresi dolmuş veya ödenmiş bağlantıda) “Mağazaya dön” olarak gösterir. Kimlik bilgisi içermeyen http veya https, en fazla 2048 karakter; canlı anahtar https ister, aksi halde details[].constraint https_required_in_live ile 400 COMMON_VALIDATION_FAILED döner.

Oluştur ve yönlendir

curl -X POST https://pay.magazamhazir.com/api/v1/checkout/sessions \
  -H "Authorization: MHPAYv1 <base64(apiKey:<pk>&randomKey:<rnd>&signature:<hex>)>" \
  -H "x-mhpay-timestamp: 1721400000" \
  -H "Content-Type: application/json" \
  -d '{"amount":15000,"currency":"TRY","orderId":"order-1024","callbackUrl":"https://store.example/checkout/return","returnUrl":"https://store.example/orders/1024","use3ds":true}'
# → { "token":"cs_9f2a7b…","url":"https://pay.magazamhazir.com/pay/cs_9f2a7b…","expiresAt":"…" }
# Redirect the shopper to url; they come back to callbackUrl?paymentId=…&status=…

{
  "token": "cs_9f2a7b…",
  "amount": 15000,
  "currency": "TRY",
  "orderId": "order-1024",
  "status": "open",
  "installmentsAllowed": [1, 3, 6],
  "expiresAt": "2026-07-19T18:40:00.000Z",
  "mode": "live",
  "simulated": false,
  "merchantName": "Kafe Kuruş",
  "returnUrl": "https://store.example/orders/1024"
}

Bir token ve barındırılan /pay/:token URL'sini döndüren POST /v1/checkout/sessions ile bir oturum oluşturun. GET, sayfanın gösterdiklerini döndürür — tutar, para birimi, orderId, durum, ödeme alıcısı (merchantName) ve geri dönüş yolu (returnUrl); POST …/pay ise ödemeyi çalıştırmak için alışveriş yapanın kartını gönderir ve 3-D Secure geçidini (threeDSHtmlContent) veya üye işyeri yönlendirmesini döndürür.

HTTP/1.1 409 Conflict
{
  "statusCode": 409,
  "code": "CHECKOUT_SESSION_CONSUMED",
  "message": "CHECKOUT_SESSION_CONSUMED",
  "meta": {
    "merchantName": "Kafe Kuruş",
    "returnUrl": "https://store.example/orders/1024",
    "paymentState": "threeds_pending"
  }
}

Bir oturum tek kullanımlıktır. Kullanılmış, süresi dolmuş veya engellenmiş bir oturum — GET, …/pay ve …/installments çağrılarında aynı şekilde — 409 CHECKOUT_SESSION_CONSUMED, 410 CHECKOUT_SESSION_EXPIRED veya 403 CHECKOUT_MERCHANT_UNAVAILABLE (üye işyeri artık canlı ödeme alamayan canlı oturum) döner; yanıtta meta.merchantName, meta.returnUrl ve bağlı ödemenin durumu ya da null olan meta.paymentState bulunur. Kullanılmış oturum ödenmiş oturum değildir: yalnızca paymentState captured olduğunda “ödendi” gösterin, çünkü yarım kalan veya başarısız bir 3-D Secure da oturumu kullanır. 404 CHECKOUT_SESSION_NOT_FOUND meta taşımaz.

curl "https://pay.magazamhazir.com/api/v1/checkout/sessions/cs_9f2a7b…/installments?bin=454671"

{
  "provider": "garanti",
  "family": "bonus",
  "options": [
    { "count": 1, "perInstallmentMinor": 12000, "totalMinor": 12000, "rateBps": 0,   "surchargeMinor": 0 },
    { "count": 3, "perInstallmentMinor": 4180,  "totalMinor": 12540, "rateBps": 450, "surchargeMinor": 540 },
    { "count": 6, "perInstallmentMinor": 2180,  "totalMinor": 13080, "rateBps": 900, "surchargeMinor": 1080 }
  ]
}

Her iki uç nokta da aynı şekli döndürür: provider, isteğe bağlı bir family (kartın taksit programı — bonus, world, axess, maximum, cardfinans, paraf, bankkart veya saglam) ve her biri count, taksit başına tutar ve minör birim cinsinden genel toplam içeren options[]. count 1 (tek çekim) her zaman bulunur. Herkese açık ödeme varyantı, alışverişçi kartını yazarken barındırılan /pay sayfasının çağırdığıdır; imzalı /v1/installments varyantı ise kendi kart formunuz içindir. Sunulan sayıları sınırlamak için oturumu installmentsAllowed ile oluşturun (POST /v1/checkout/sessions) ve planı çalıştırmak için POST /v1/payments'a veya barındırılan pay'e installments gönderin — izin verilmeyen bir sayı 422 INSTALLMENTS_NOT_AVAILABLE döndürür.

Her seçenek ayrıca rateBps ve surchargeMinor taşır — üyenin o taksit sayısı için tanımladığı vade farkı. totalMinor bunu zaten içerir (örn. 450 bps ile 3× %4,50 ekler), bu yüzden perInstallmentMinor ve totalMinor değerlerini olduğu gibi gösterin. Bu yalnızca gösterim içindir: gerçek vade farkını banka hesap kesiminde uygular, dolayısıyla tahsil edilen tutar değişmez. Vade farkı tablosu olmayan bir üyede her sayıda rateBps 0 döner (vade farksız) ve TRY dışındaki para birimlerinde taksit hiç sunulmaz.

POST /api/v1/payments
{
  "amount": 12000,
  "currency": "TRY",
  "orderId": "order-1024",
  "installments": 3,
  "card": { "number": "4111111111111111", "expireMonth": 12, "expireYear": 2030, "cvc": "123" }
}

Politika: taksit yalnızca TRY içindir. Canlı rotalarda plan on-us'tur — kartın kendi çıkaran bankası, üye işyerinin entegre ettiği bir banka olmalıdır — ve sunulan sayılar o bankanın tanımlı azami değerinde sınırlanır. Sandbox esnektir: sahte sağlayıcı, planların gerçek bir kart olmadan test edilebilir kalması için üye işyerinin varsayılan hesap sınırını (veya oturumun installmentsAllowed izin listesini) kullanır.

{
  "amount": 12000,
  "currency": "TRY",
  "orderId": "order-1024",
  "installments": 1,
  "card": {
    "number": "4111111111111111",
    "expireMonth": 12,
    "expireYear": 2030,
    "cvc": "123",
    "holderName": "Ayşe Yılmaz"
  },
  "buyer": { "email": "ayse@example.com", "ip": "88.255.1.1" }
}

{
  "id": "pay_2c7d8e…",
  "status": "captured",
  "flow": "sale",
  "orderId": "order-1024",
  "amount": 12000,
  "capturedAmount": 12000,
  "refundedAmount": 0,
  "currency": "TRY",
  "provider": "garanti",
  "providerPaymentRef": "620008031419",
  "simulated": false,
  "simulatedReason": null,
  "card": { "bin": "411111", "last4": "1111", "brand": "VISA" },
  "errorCode": null,
  "createdAt": "2026-07-19T18:32:10.000Z"
}

İmzalı istek

curl -X POST https://pay.magazamhazir.com/api/v1/payments \
  -H "Authorization: MHPAYv1 <base64(apiKey:<pk>&randomKey:<rnd>&signature:<hex>)>" \
  -H "x-mhpay-timestamp: 1721400000" \
  -H "Idempotency-Key: 6f1c9e2a-6d5b-4f0e-9b1a-2c7d8e9f0a1b" \
  -H "Content-Type: application/json" \
  -d '{"amount":12000,"currency":"TRY","orderId":"order-1024","installments":1,"card":{"number":"4111111111111111","expireMonth":12,"expireYear":2030,"cvc":"123"}}'

{
  "amount": 12000,
  "currency": "TRY",
  "orderId": "order-1024",
  "callbackUrl": "https://store.example/checkout/return",
  "preAuth": false,
  "card": { "number": "4111111111111111", "expireMonth": 12, "expireYear": 2030, "cvc": "123" }
}

{
  "paymentId": "pay_2c7d8e…",
  "status": "threeds_pending",
  "threeDSHtmlContent": "PGh0bWw+…(base64 gate page)",
  "redirectUrl": null
}

threeDSHtmlContent alanını — bankanın 3-D Secure geçit sayfasını — base64’ten çözüp alışveriş yapanın sayfası olarak sunun: sayfa onu bankasına gönderir. Yanıt bunun yerine bir redirectUrl taşıyorsa alışveriş yapanı oraya yönlendirin. Banka sonucu ağ geçidine gönderir; ağ geçidi ödemeyi tamamlayıp callbackUrl adresinize yönlendirir. Geçit sayfası bankanın ihtiyaç duyduğu kart verisini taşır: asla loglamayın veya saklamayın, alışveriş yapanın tarayıcısından başka hiçbir yere göndermeyin.

Yönlendirme paymentId, status ve signature taşır. status; success (tahsil edildi ya da ön provizyonda authorized), failed veya pending olur: pending, bankanın dönüşünün henüz doğrulanamadığı ya da karara bağlanamadığı anlamına gelir — para hareket etmiş olabilir. pending’i ÖDENMEMİŞ sayın, üzerine yeniden deneme önermeyin ve kesinleşene kadar GET /v1/payments/:id ile yeniden okuyun; ağ geçidi operatörü durumu banka panelinden kesinleştirir ve ilgili webhook gönderilir.

Tahsil etmek yerine provizyon tutmak için preAuth: true gönderin. Ödeme authorized olarak tamamlanır (webhook payment.authorized), callbackUrl adresiniz yine status=success alır ve tutarı daha sonra /capture ile tahsil edersiniz — 3DS’siz ön provizyon akışıyla tamamen aynı.

Başlatma ve geri çağırma akışı

# 1. Initialize — returns the base64 gate page
curl -X POST https://pay.magazamhazir.com/api/v1/payments/3ds/initialize \
  -H "Authorization: MHPAYv1 <base64(apiKey:<pk>&randomKey:<rnd>&signature:<hex>)>" \
  -H "x-mhpay-timestamp: 1721400000" \
  -H "Content-Type: application/json" \
  -d '{"amount":12000,"currency":"TRY","orderId":"order-1024","callbackUrl":"https://store.example/checkout/return","card":{"number":"4111111111111111","expireMonth":12,"expireYear":2030,"cvc":"123"}}'
# → { "paymentId":"pay_…","status":"threeds_pending","threeDSHtmlContent":"PGh0bWw+…" }

# 2. Base64-decode threeDSHtmlContent and serve it as the shopper's page — it
#    posts them to their bank. The bank posts back to the gateway, which redirects to:
#    https://store.example/checkout/return?paymentId=pay_…&status=success&signature=…
#    (status: success | failed | pending — pending is NOT paid: re-read the payment)

{
  "amount": 12000,
  "currency": "TRY",
  "orderId": "order-1024",
  "card": { "number": "4111111111111111", "expireMonth": 12, "expireYear": 2030, "cvc": "123" }
}

{
  "id": "pay_2c7d8e…",
  "status": "authorized",
  "flow": "preauth",
  "amount": 12000,
  "capturedAmount": 0,
  "refundedAmount": 0,
  "currency": "TRY",
  "provider": "garanti",
  "createdAt": "2026-07-19T18:32:10.000Z"
}

Yetenek bazlı: provizyon bloğu olmayan bankalar (ör. bir katılım bankası olan Kuveyt Türk) 501 PROVIDER_PREAUTH_UNSUPPORTED yanıtı verir. Sunmadan önce GET /v1/capabilities içindeki preAuth alanını kontrol edin. 3-D Secure bloğu için bunun yerine POST /v1/payments/3ds/initialize isteğine "preAuth": true gönderin.

POST /api/v1/payments/pay_2c7d8e…/capture
{ "amount": 8000 }

capture bloğu kapatır ve payment.captured yayar; tam yetkilendirmeyi almak için amount alanını atlayın. cancel aynı gün yetkilendirmesini iptal eder, reverse ise provizyon bloğunu serbest bırakır (payment.cancelled / payment.reversed). Hepsi idempotenttir ve orijinal bankaya yönlendirilir.

{
  "id": "pay_2c7d8e…",
  "status": "captured",
  "providerSync": {
    "supported": true,
    "providerStatus": "captured",
    "providerPaymentRef": "0210600150160001"
  }
}

?sync=true additionally queries the acquiring bank. Banks without an inquiry service return providerSync.supported: false — the endpoint's shape never changes with the bank. It is read-only: status always reflects the gateway's own record and is never overwritten by the bank's answer.

Geliştirmeye başlamadan önce bunu kontrol edin. Her banka her özelliği sunmaz ve uç noktalar bankaya göre çoğaltılmaz, ortaktır: bir bankada bir özellik yoksa aynı rota farklı davranmak yerine 501 döner. tokenization false ise kayıtlı kartlar PROVIDER_TOKENIZATION_UNSUPPORTED, preAuth false ise /payments/preauth PROVIDER_PREAUTH_UNSUPPORTED döner (bir katılım bankası olan Kuveyt Türk’te provizyon bloğu yoktur). Aynı çağrı anahtarın kime ait olduğunu ve şu anda CANLI ödeme alınıp alınamayacağını da söyler. Salt okunurdur; bu yüzden canlı erişim kapalıyken bile canlı anahtar yanıt alır.

{
  "provider": "isbank",
  "capabilities": { "threeDS": true, "preAuth": true, "tokenization": false, "installments": true, "inquiry": true },
  "sandbox": { "simulated": false, "sharedTerminal": true, "verified": true, "verifiedAt": "2026-07-21T01:37:11.036Z" },
  "defaultProvider": "isbank",
  "enabledProviders": [
    { "name": "isbank", "capabilities": { "threeDS": true, … }, "sandbox": { "simulated": false, … } }
  ],
  "merchantId": "6f1c9e2a-6d5b-4f0e-9b1a-2c7d8e9f0a1b",
  "mode": "live",
  "liveEnabled": true,
  "liveReady": false,
  "liveBlockers": ["LIVE_ACCOUNT_INCOMPLETE"]
}

{
  "id": "card_7a1f…",
  "cardUserKey": "cuk_1a2b…",
  "cardToken": "ctok_9f8e…",
  "bin": "552879",
  "last4": "0008",
  "brand": "MASTERCARD",
  "expMonth": 12,
  "expYear": 2030
}

POST /api/v1/payments
{
  "amount": 12000,
  "currency": "TRY",
  "orderId": "order-1025",
  "token": { "cardUserKey": "cuk_1a2b…", "cardToken": "ctok_9f8e…" }
}

Tokenleştirme, PAN'ı asla değil, opak token referansları ile bin ve last4 döndürür. Kayıtlı bir kartı, card yerine token'ını ödeme aracı olarak geçirerek tahsil edin. Bir token yalnızca onu üreten kasanın bankasında çalışır; bankalar arasında taşınabilir değildir.

curl https://pay.magazamhazir.com/api/v1/banks

{
  "banks": [
    {
      "provider": "garanti",
      "displayName": "Garanti BBVA",
      "protocol": "GVPS",
      "tier": "certified",
      "credentialFields": [
        { "key": "merchantId", "label": "Merchant ID", "secret": false },
        { "key": "terminalId", "label": "Terminal ID", "secret": false },
        { "key": "provisionPassword", "label": "Provision password", "secret": true }
      ],
      "capabilities": {
        "threeDS": true, "preAuth": true, "tokenization": false,
        "installments": true, "inquiry": true
      }
    }
  ]
}

Yalnızca entegre bankalar döner, kademeye göre sıralanmış olarak. tier şunlardan biridir: certified, protocol-confirmed, creds-pending, not-started veya not-planned; certified, bankaya karşı canlı doğrulandığı anlamına gelir. credentialFields, bir operatörün bankayı etkinleştirmek için sağlaması gereken tam alanları listeler.

{
  "providers": [
    {
      "name": "garanti",
      "capabilities": {
        "threeDS": true, "preAuth": true, "tokenization": false,
        "installments": true, "inquiry": true
      },
      "sandbox": { "simulated": false, "sharedTerminal": true, "verified": true, "verifiedAt": "2026-07-21T01:37:11.036Z" }
    }
  ]
}

• ·sandbox.simulated true ise o bankaya giden sk_test_ trafiğini banka değil, ağ geçidinin simülatörü yanıtlar; sharedTerminal bankanın herkese açık test terminalini işaretler; verified ve verifiedAt, bankanın onayladığı gerçek bir sandbox satışını kaydeder.
• ·Varsayılan banka destekliyorsa yetenek true'dur; paylaşılan /v1 uç noktaları, false olduğunda bankaya göre farklı davranmak yerine 501 döndürür.
• ·tokenization false olduğunda kayıtlı kartları, preAuth false olduğunda ön provizyonu gizleyin; banka adlarını sabit kodlamayın.

1. 1The gateway reads the card's BIN (leading digits).
2. 2It finds the card's issuing bank and, if the merchant has integrated it, routes there.
3. 3Otherwise the merchant's default bank runs the payment.

Yönlendirme alışveriş yapanın tarayıcısı içindir; webhook'u doğruluk kaynağı olarak kabul edin ve siparişi yalnızca imzasını doğruladıktan sonra tamamlayın.

{ "url": "https://store.example/webhooks/mhpay", "events": ["payment.succeeded", "refund.succeeded"] }

X-MHPAY-Signature: t=1721400000,v1=8f3c…       (two v1 during a secret rotation)
X-MHPAY-Event: payment.succeeded
User-Agent: MHPay-Webhooks/1.0
Content-Type: application/json

{
  "id": "evt_5c2d…",
  "type": "payment.succeeded",
  "created": 1721400000,
  "mode": "sandbox",
  "data": {
    "paymentId": "pay_2c7d8e…",
    "orderId": "order-1024",
    "status": "captured",
    "amount": 12000,
    "currency": "TRY",
    "cardLast4": "1111"
  }
}

Her teslimat bu zarfa sarılır. id ile tekrarları ayıklayın — yeniden denemeler aynı id'yi kullanır, bu yüzden tekrarlanan bir id'yi aynı olay olarak değerlendirin ve yalnızca bir kez işleyin. mode, olayın sandbox'tan mı yoksa canlıdan mı geldiğini belirtir.

{
  "id": "evt_8a1f…",
  "type": "refund.succeeded",
  "created": 1721486400,
  "mode": "live",
  "data": {
    "paymentId": "pay_2c7d8e…",
    "orderId": "order-1024",
    "status": "partially_refunded",
    "amount": 12000,
    "currency": "TRY",
    "cardLast4": "1111",
    "refundAmount": 4000
  }
}

data.amount her olayda ödemenin ilk tutarı olarak kalır; refund.succeeded olayında data.refundAmount BU iadenin tutarı, data.status ise iadeden sonraki ödeme durumudur (partially_refunded veya refunded). Ne kadarın iade edildiğini bilmek için refundAmount değerlerini paymentId başına, olay id’sine göre tekrarları ayıklayarak toplayın.

[
  {
    "id": "whe_5c2d…",
    "url": "https://store.example/webhooks/mhpay",
    "events": ["payment.succeeded", "refund.succeeded"],
    "status": "active",
    "createdAt": "2026-07-19T18:32:10.000Z"
  }
]

GET, kayıtlı her uç noktayı url'si, abone olunan olayları ve durumuyla döndürür — ancak yalnızca oluşturma anında bir kez gösterilen imzalama gizli anahtarını asla göstermez. DELETE, bir uç noktayı devre dışı bırakır, böylece teslimat almayı durdurur.

• ·X-MHPAY-Signature'ı t=<unix> zaman damgasına ve her v1=<hex> değerine ayrıştırın; gövdenin JSON ayrıştırmasından önceki tam alınan baytlarını kullanın.
• ·signature = HMAC-SHA256(signingSecret, `${t}.${rawBody}`), aynı başlığın içinde hex bir v1 değeri olarak gönderilir.
• ·Zaman damgası sapması 5 dakikadan (300s) fazla olan her şeyi reddedin ve tekrar ile zamanlama saldırılarını önlemek için sabit zamanlı bir fonksiyonla karşılaştırın.
• ·Gizli anahtar döndürme sırasında başlık iki v1 değeri taşır (önce geçerli gizli anahtar); hepsini toplayın ve herhangi biri eşleşirse teslimatı kabul edin.

const crypto = require('crypto');

// Verify the X-MHPAY-Signature header: "t=<unix>,v1=<hex>[,v1=<hex>]".
// During a secret rotation TWO v1 values arrive; accept ANY match.
function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
  const parts = header.split(',').map(s => s.trim());
  const t = Number(parts.find(p => p.startsWith('t='))?.slice(2));
  const v1s = parts.filter(p => p.startsWith('v1=')).map(p => p.slice(3));
  if (!t || Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1s.some(v => v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}

{
  "id": "whe_5c2d…",
  "signingSecret": "whsec_new9f2a…",
  "previousSecretExpiresAt": "2026-07-21T18:32:10.000Z"
}

1. 1rotate çağırın ve yeni signingSecret (whsec_…) değerini saklayın — yalnızca bir kez döndürülür.
2. 2Sonraki 24 saat boyunca her iki gizli anahtar da her teslimatı imzalar, bu yüzden X-MHPAY-Signature iki v1 değeri taşır (önce geçerli gizli anahtar).
3. 3Kod değişikliğine gerek yoktur: yukarıdaki doğrulayıcı zaten tüm v1 değerlerini toplar ve herhangi bir eşleşmeyi kabul eder.
4. 4previousSecretExpiresAt sonrasında eski gizli anahtar imzalamayı bırakır ve teslimatlar yeniden tek bir v1 taşır.

{ "delivered": true, "statusCode": 200 }

Test olayı, uç noktanın events[] filtresinden bağımsız olarak teslim edilir — bir abonelik değil, açık bir testtir. delivered uç noktanızın yanıt verip vermediğini, statusCode ise HTTP durumunu (erişilemezse null) bildirir. Deneme ayrıca teslimat günlüğünüzde gerçek olayların yanında görünür.

1. Sanal POS bilgilerinizi bankanızdan alın (üye işyeri no, terminal no, mağaza/gizli anahtar — alanlar bankaya göre değişir).
2. Bunları panelde Bankalar bölümüne bir kez girin. Sandbox için bir şey tanımlamaya gerek yoktur; bilgiler yalnızca canlıya özeldir.
3. Bilgileri yerleşik denetimle doğrulayın — para hareketi olmayan, risksiz bir kontrol.
4. Entegrasyonunuzu sk_live_ anahtarınıza geçirin. Sandbox mı canlı mı olduğu, ana bilgisayara veya bir bayrağa göre değil, anahtar önekine göre belirlenir.
5. Küçük tutarlı gerçek bir ödeme gönderin, panelde doğrulayın ve banka ekstrenizle mutabık kalın.

Geçiş yapmadan önce sk_live_ anahtarıyla GET /v1/capabilities/me çağırın: liveReady true olmalıdır; eksik kalan her şeyi liveBlockers söyler.

Çekilecek bir tutar veya platform bakiyesi yoktur: ilk canlı ödemenizden itibaren para, bankanızın normal döngüsünde kendi hesabınıza geçer.

Her MHPAY test kartı 7433 işaretini taşır; böylece ilk bakışta tanınır ve başka bir alt yapının test kartlarıyla çakışamaz.

4001 7433 0010 0100
^^^^ ^^^^ ^^^^ ^^^^
|    |    |    |  └─ Luhn kontrol hanesi
|    |    |    └──── senaryo kodu (000 = onaylı)
|    |    └───────── banka kodu
|    └────────────── 7433 — her test kartındaki MHPAY işlareti
└─────────────────── marka + kart tipi (4001 Visa kredi, 5002 Mastercard banka, …)

• ·Son kullanma: gelecekteki herhangi bir tarih. Sandbox kontrol etmez.
• ·CVC: herhangi 3 hane (Amex için 4). CVC reddini test etmek için hatalı CVC yerine geçersiz-CVC kartını kullanın — hatalı CVC bankaya ulaşmadan doğrulamada reddedilir.
• ·Diğer Luhn-geçerli kartlar, gerçek sandbox’ı olan bankalarda bankaya iletilir (sonuç bankadan gelir); henüz sandbox’ımız olmayan bankalarda simülatör onaylar.

Onaylanan kartlar

Her banka için bir tane; markalar ve kart tipleri arasında dağıtılmıştır. Hepsi status: captured döner.

Başarısız kartlar

Her biri tek bir reddi sabitler. Hatalar HTTP 402 olarak, aşağıdaki kod meta.providerErrorCode içinde döner — düz retler PAYMENT_DECLINED, iade/kapatma retleri PAYMENT_PROVIDER_ERROR olarak gelir.

Banka yönlendirme kartları

Yukarıdaki kartlar gerçek bir bankaya ait olmayan BIN'ler üzerine kuruludur, bu yüzden her zaman varsayılan bankanıza düşerler. Buradaki her kart ise gerçek bir banka BIN'i taşır — entegre her banka için bir kredi ve bir banka kartı — böylece o bankayı entegre ettiyseniz ödeme on-us olarak o bankaya, aksi halde varsayılan bankanıza yönlenir. Hepsi onaylanır ve daima simüle edilir: değişen şey, sonuç değil, yanıttaki routingReason değeridir (bin_on_us / default_fallback). İki “bilinmeyen banka” kartı hiçbir bankanın aralığında olmayan bir BIN taşır, bu yüzden her zaman fallback olur.