Esc
Aramaya başlamak için yazın...

Masterpass Entegrasyonu

Masterpass Nedir? #

Masterpass, Mastercard'ın dijital ödeme çözümüdür. Kullanıcılar kartlarını Masterpass sisteminde kayıt ettikten sonra, cep telefonu numaraları ile hızlı ve güvenli ödeme yapabilirler.

Pazaryeri sistemi, standart kart ödemelerinin yanı sıra Masterpass ile de ödeme almayı destekler.

Avantajları #

  • ✅ Hızlı Ödeme - Kullanıcı kart bilgisi girmez, sadece SMS onayı
  • ✅ Güvenli - Kart bilgileri Masterpass tarafından saklanır
  • ✅ Mobil Uyumlu - Mobil cihazlarda kolay kullanım
  • ✅ Kayıtlı Kartlar - Kullanıcıların Masterpass'e kayıtlı kartları kullanılır

CreatePayment (Masterpass) #

Masterpass ile ödeme almak için özel bir endpoint kullanılır.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/payment/create/MASTERPASS

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/payment/create/MASTERPASS

İstek Parametreleri #

Masterpass ödemesinde bankCard bilgileri gönderilmez. Bunun yerine gsm parametresi zorunludur.

{
  "apiKey": "calculated_api_key",
  "apiSecretKey": "sx_value",
  "gsm": "5321234567",
  "trxCurrency": "TRY",
  "trxAmount": 150.00,
  "trxCode": "ORDER_12345",
  "trxType": "SALES",
  "callbackUrl": "https://yoursite.com/payment-callback",
  "sellerList": [
    {
      "sellerExternalId": "SELLER_001",
      "trxAmount": 100.00,
      "withholdingTax": 0.80
    },
    {
      "sellerExternalId": "SELLER_002",
      "trxAmount": 50.00,
      "withholdingTax": 0.40
    }
  ],
  "shippingCost": 0.00,
  "otherAmount": 0.00,
  "marketplaceCode": "MP12345"
}

Masterpass'e Özel Parametreler #

ParametreTipZorunluAçıklama
gsmString✅Kullanıcının cep telefonu (başında +90 olmadan)

GSM Format:

✅ Doğru: "5321234567"
❌ Yanlış: "+905321234567"
❌ Yanlış: "05321234567"

Ortak Zorunlu Parametreler #

Standart CreatePayment ile aynı zorunlu parametreler:

  • apiKey
  • apiSecretKey
  • trxCurrency
  • trxAmount
  • trxCode
  • trxType
  • callbackUrl
  • sellerList (sellerExternalId, trxAmount, withholdingTax)
  • shippingCost
  • otherAmount
  • marketplaceCode

GÖNDERİLMEYEN Parametreler #

Masterpass ödemesinde aşağıdaki parametreler gönderilmez:

  • ❌ bankCard (kart bilgileri)
  • ❌ installment
  • ❌ isFetchInstallments
  • ❌ encodedValue
  • ❌ customerCardInfo

Yanıt #

{
  "data": {
    "refCode": "REF123456789",
    "trxCode": "ORDER_12345",
    "form": "PGh0bWw+...Masterpass HTML Form Base64..."
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Yanıt formatı standart CreatePayment ile aynıdır. form alanı Base64 encoded HTML içerir.

Masterpass İşlem Akışı #

sequenceDiagram
    participant User as Kullanıcı
    participant Your as Sizin Sistem
    participant PNK as Paynkolay
    participant MP as Masterpass

    User->>Your: GSM numarası ile ödeme başlat
    Your->>PNK: CreatePayment/MASTERPASS (gsm)
    PNK->>Your: HTML Form (Base64)
    Your->>Your: Base64 Decode
    Your->>User: Masterpass Form Göster
    User->>MP: Masterpass'e Giriş
    MP->>User: Kayıtlı Kartları Göster
    User->>MP: Kart Seç + SMS Onay
    MP->>PNK: Ödeme Sonucu
    PNK->>Your: callbackUrl'e POST
    Your->>User: Sonuç Sayfası

Örnek Kod #

Callback İşleme #

Masterpass ödemesinin callback işlemi standart ödeme ile aynıdır:

app.post('/payment-callback', (req, res) => {
  const {
    trxCode,
    responseCode,
    referenceCode,
    authAmount,
    timestamp,
    hash,
    paymentSystem  // Masterpass için "MASTERPASS" değeri gelir
  } = req.body;

  // Hash doğrula
  const calculatedHash = calculateCallbackHash({
    timestamp,
    referenceCode,
    trxCode,
    authAmount,
    responseCode
  }, apiSecretKey);

  if (calculatedHash !== hash) {
    return res.status(400).send('Invalid hash');
  }

  // Ödeme başarılı mı?
  if (responseCode === '00' || responseCode === '0000') {
    // Masterpass ile ödeme başarılı
    console.log('Masterpass ödeme başarılı:', trxCode);
    updateOrderStatus(trxCode, 'PAID', 'MASTERPASS');
  } else {
    console.log('Masterpass ödeme başarısız:', responseCode);
    updateOrderStatus(trxCode, 'FAILED');
  }

  res.status(200).send('OK');
});

Kullanıcı Arayüzü Örneği #

Ödeme Yöntemi Seçimi #

<div class="payment-methods">
  <label>
    <input type="radio" name="paymentMethod" value="card">
    Kredi/Banka Kartı
  </label>

  <label>
    <input type="radio" name="paymentMethod" value="masterpass">
    <img src="/images/masterpass-logo.png" alt="Masterpass">
    Masterpass ile Öde
  </label>
</div>

<div id="card-form" style="display:none;">
  <!-- Standart kart formu -->
  <input type="text" name="cardNumber" placeholder="Kart Numarası">
  <input type="text" name="cardHolder" placeholder="Kart Üzerindeki İsim">
  <!-- ... -->
</div>

<div id="masterpass-form" style="display:none;">
  <label>Cep Telefonu Numaranız:</label>
  <input type="tel" name="gsm" placeholder="5XX XXX XX XX" pattern="5[0-9]{9}">
  <small>Masterpass'e kayıtlı cep telefonu numaranız</small>
</div>

<script>
document.querySelectorAll('input[name="paymentMethod"]').forEach(radio => {
  radio.addEventListener('change', (e) => {
    document.getElementById('card-form').style.display =
      e.target.value === 'card' ? 'block' : 'none';

    document.getElementById('masterpass-form').style.display =
      e.target.value === 'masterpass' ? 'block' : 'none';
  });
});
</script>

Form Gönderimi #

async function processPayment(formData) {
  const paymentMethod = formData.get('paymentMethod');

  if (paymentMethod === 'masterpass') {
    // Masterpass ile ödeme
    const gsm = formData.get('gsm').replace(/\s/g, ''); // Boşlukları temizle

    // GSM validasyonu
    if (!/^5[0-9]{9}$/.test(gsm)) {
      alert('Geçerli bir cep telefonu numarası girin');
      return;
    }

    const response = await fetch('/api/payment/masterpass', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        gsm: gsm,
        amount: orderTotal,
        orderId: orderId
      })
    });

    const result = await response.json();

    if (result.success) {
      // Base64 decode ve göster
      const htmlForm = atob(result.data.form);
      document.body.innerHTML = htmlForm;
    }

  } else {
    // Standart kart ile ödeme
    // ...
  }
}

Masterpass Özellikleri #

Kart Bilgisi Gerekmiyor #

// ❌ YANLIŞ - Masterpass için kart bilgisi göndermeyin
// ❌ WRONG - Do not send card info for Masterpass
{
  "bankCard": {
    "cardNumber": "...",
    "cvv": "..."
  },
  "gsm": "5321234567"
}

// ✅ DOĞRU - Sadece GSM yeterli
// ✅ CORRECT - Only GSM is sufficient
{
  "gsm": "5321234567"
  // bankCard GÖNDERİLMEZ / OMITTED
}

Taksit Desteği #

Masterpass ödemelerinde taksit seçenekleri Masterpass ekranında gösterilir. API isteğinde taksit parametresi gönderilmez.

Kayıtlı Kartlar #

GSM numarası kullanılarak kullanıcının Masterpass'e kayıtlı kartları otomatik olarak getirilir. Ek bir işlem gerekmez.

Hata Durumları #

Masterpass'e Kayıtlı Değil #

Kullanıcının GSM numarası Masterpass'e kayıtlı değilse, Masterpass ekranında kayıt olma seçeneği sunulur.

// Kullanıcıyı bilgilendir
if (paymentMethod === 'masterpass') {
  alert(
    'Masterpass ile ödeme yapmak için Masterpass hesabınızın olması gerekmektedir. ' +
    'Eğer hesabınız yoksa, ödeme ekranında Masterpass\'e kayıt olabilirsiniz.'
  );
}

Geçersiz GSM #

function validateGSM(gsm) {
  // Başında 5, toplam 10 hane
  if (!/^5[0-9]{9}$/.test(gsm)) {
    throw new Error('Geçersiz GSM formatı. Başında 0 olmadan 10 hane olmalı.');
  }
  return true;
}

Masterpass vs Standart Kart #

ÖzellikMasterpassStandart Kart
Kart Bilgisi❌ Gerekmiyor✅ Gerekiyor
GSM✅ Zorunlu❌ Opsiyonel
Hız⚡ Çok Hızlı🐢 Daha Yavaş
Güvenlik🔒 Masterpass🔒 3D Secure
Kayıtlı Kart✅ Otomatik❌ Manuel
Mobil📱 Optimize💻 Standart

Test Etme #

Masterpass test işlemleri için:

  • Test GSM Numarası: Mastercard tarafından sağlanan test numaralarını kullanın
  • Test Kartları: Masterpass test hesabına test kartları ekleyin
  • Test Ortamı: apitest.paynkolay.com.tr kullanın

Sonraki Adımlar #

Masterpass entegrasyonunu tamamladıktan sonra: