DOCS
Panel Giriş Başvurun

Pazaryeri Entegrasyonu

Masterpass

Mastercard'ın dijital ödeme çözümü: kullanıcı kart bilgisi girmez, Masterpass'e kayıtlı kartıyla cep telefonu numarası ve SMS onayı üzerinden öder.

Avantajları

  • Hızlı ödeme — kart bilgisi girilmez, yalnızca SMS onayı
  • Güvenli — kart bilgileri Masterpass tarafından saklanır
  • Mobil uyumlu — mobil cihazlarda kolay kullanım
  • Kayıtlı kartlar — kullanıcının Masterpass'teki kartları otomatik gelir

CreatePayment (Masterpass)

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

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

Standart CreatePayment ucunun sonuna /MASTERPASS eklenir.

İstek

Masterpass ödemesinde bankCard bilgileri gönderilmez; bunun yerine gsm zorunludur:

İstek — JSON
{
  "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"
}
ParametreTipZorunluAçıklama
gsmStringKullanıcının cep telefonu — başında +90 veya 0 olmadan, 5 ile başlayan 10 hane
GSM Formatı
✅ Doğru:  "5321234567"
❌ Yanlış: "+905321234567"
❌ Yanlış: "05321234567" 

Gönderilmeyen parametreler: bankCard, installment, isFetchInstallments, encodedValue ve customerCardInfo Masterpass isteğinde yer almaz. Taksit seçenekleri Masterpass ekranında gösterilir.

Yanıt

Yanıt formatı standart CreatePayment ile aynıdır: refCode, trxCode ve Base64 kodlu form döner; formu decode edip kullanıcıya gösterirsiniz.

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

İşlem Akışı

MüşteriSunucunuzPaynkolayMasterpassGSM numarası + "Öde"1POST /payment/create/MASTERPASSgsm · apiKey · sellerList2refCode + Base64 form3Formu decode edip göster4Masterpass girişi + kart seçimi5SMS onay kodu6Sonuç callbackUrl'e POST(paymentSystem=MASTERPASS)7Callback hash doğrula(hash-hesaplama sayfası)8
  1. 1GSM ile başlatınKullanıcı cep numarasını girer, siz CreatePayment/MASTERPASS çağırırsınız.
  2. 2Formu gösterinDönen Base64 HTML'i decode edip kullanıcıya render edin.
  3. 3Masterpass girişiKullanıcı Masterpass'e giriş yapar, kayıtlı kartları listelenir.
  4. 4Kart seçimi + SMS onayıKullanıcı kartını seçer ve SMS kodunu onaylar.
  5. 5CallbackSonuç callbackUrl adresinize POST edilir.
  6. 6DoğrulamaHash'i doğrulayıp siparişi sonuçlandırırsınız.
Örnek — JavaScript
const payment = await axios.post(BASE_URL + '/payment/create/MASTERPASS', {
  apiKey,
  apiSecretKey,
  gsm: '5321234567',
  trxCurrency: 'TRY',
  trxAmount: 250.00,
  trxCode: 'ORDER_789',
  trxType: 'SALES',
  callbackUrl: 'https://yoursite.com/payment-callback',
  sellerList: [{ sellerExternalId: 'SELLER_001', trxAmount: 250.00, withholdingTax: 2.00 }],
  shippingCost: 0,
  otherAmount: 0,
  marketplaceCode: 'MP12345'
});

if (payment.data.success && payment.data.data.form) {
  const htmlForm = Buffer.from(payment.data.data.form, 'base64').toString('utf-8');
  // formu kullanıcıya göster
}

Örnek Kod

Masterpass ödemesini başlatan uçtan uca örnekler:

const axios = require('axios');
const crypto = require('crypto');

class MasterpassPayment {
  constructor(apiSecretKey, merchantSecretKey, mpCode, baseURL) {
    this.apiSecretKey = apiSecretKey;
    this.merchantSecretKey = merchantSecretKey;
    this.mpCode = mpCode;
    this.baseURL = baseURL;
  }

  calculateApiKey() {
    const hashString = this.apiSecretKey + '|' + this.merchantSecretKey;
    const hash = crypto.createHash('sha512').update(hashString, 'utf8').digest();
    return hash.toString('base64');
  }

  async createMasterpassPayment(paymentData) {
    const apiKey = this.calculateApiKey();

    const response = await axios.post(
      `${this.baseURL}/payment/create/MASTERPASS`,
      {
        apiKey,
        apiSecretKey: this.apiSecretKey,
        gsm: paymentData.gsm,
        trxCurrency: 'TRY',
        trxAmount: paymentData.amount,
        trxCode: paymentData.orderId,
        trxType: 'SALES',
        callbackUrl: paymentData.callbackUrl,
        sellerList: paymentData.sellers,
        shippingCost: paymentData.shippingCost || 0,
        otherAmount: paymentData.otherAmount || 0,
        marketplaceCode: this.mpCode
      }
    );

    return response.data;
  }
}

// Usage
const masterpass = new MasterpassPayment(
  process.env.API_SECRET_KEY,
  process.env.MERCHANT_SECRET_KEY,
  'MP12345',
  'https://apitest.paynkolay.com.tr/marketplace/v1'
);

// Create payment
const payment = await masterpass.createMasterpassPayment({
  gsm: '5321234567',
  amount: 250.00,
  orderId: 'ORDER_789',
  callbackUrl: 'https://yoursite.com/payment-callback',
  sellers: [
    {
      sellerExternalId: 'SELLER_001',
      trxAmount: 250.00,
      withholdingTax: 2.00
    }
  ],
  shippingCost: 0,
  otherAmount: 0
});

// Decode and display form
if (payment.success && payment.data.form) {
  const htmlForm = Buffer.from(payment.data.form, 'base64').toString('utf-8');
  // Display HTML to user
}
<?php
class MasterpassPayment {
    private $apiSecretKey;
    private $merchantSecretKey;
    private $mpCode;
    private $baseURL;

    public function __construct($apiSecretKey, $merchantSecretKey, $mpCode, $baseURL) {
        $this->apiSecretKey = $apiSecretKey;
        $this->merchantSecretKey = $merchantSecretKey;
        $this->mpCode = $mpCode;
        $this->baseURL = $baseURL;
    }

    private function calculateApiKey() {
        $hashString = $this->apiSecretKey . '|' . $this->merchantSecretKey;
        $hash = hash('sha512', $hashString, true);
        return base64_encode($hash);
    }

    public function createMasterpassPayment($paymentData) {
        $apiKey = $this->calculateApiKey();

        $data = [
            'apiKey' => $apiKey,
            'apiSecretKey' => $this->apiSecretKey,
            'gsm' => $paymentData['gsm'],
            'trxCurrency' => 'TRY',
            'trxAmount' => $paymentData['amount'],
            'trxCode' => $paymentData['orderId'],
            'trxType' => 'SALES',
            'callbackUrl' => $paymentData['callbackUrl'],
            'sellerList' => $paymentData['sellers'],
            'shippingCost' => $paymentData['shippingCost'] ?? 0,
            'otherAmount' => $paymentData['otherAmount'] ?? 0,
            'marketplaceCode' => $this->mpCode
        ];

        $ch = curl_init($this->baseURL . '/payment/create/MASTERPASS');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }
}

// Usage
$masterpass = new MasterpassPayment(
    getenv('API_SECRET_KEY'),
    getenv('MERCHANT_SECRET_KEY'),
    'MP12345',
    'https://apitest.paynkolay.com.tr/marketplace/v1'
);

$payment = $masterpass->createMasterpassPayment([
    'gsm' => '5321234567',
    'amount' => 250.00,
    'orderId' => 'ORDER_789',
    'callbackUrl' => 'https://yoursite.com/payment-callback',
    'sellers' => [
        [
            'sellerExternalId' => 'SELLER_001',
            'trxAmount' => 250.00,
            'withholdingTax' => 2.00
        ]
    ]
]);

// Display form
if ($payment['success'] && isset($payment['data']['form'])) {
    $htmlForm = base64_decode($payment['data']['form']);
    echo $htmlForm;
}
?>
using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
using System.Collections.Generic;

public class MasterpassPayment
{
    private readonly string apiSecretKey;
    private readonly string merchantSecretKey;
    private readonly string mpCode;
    private readonly string baseURL;

    public MasterpassPayment(string apiSecretKey, string merchantSecretKey, string mpCode, string baseURL)
    {
        this.apiSecretKey = apiSecretKey;
        this.merchantSecretKey = merchantSecretKey;
        this.mpCode = mpCode;
        this.baseURL = baseURL;
    }

    private string CalculateApiKey()
    {
        string hashString = $"{apiSecretKey}|{merchantSecretKey}";
        using (var sha512 = SHA512.Create())
        {
            byte[] bytes = sha512.ComputeHash(Encoding.UTF8.GetBytes(hashString));
            return Convert.ToBase64String(bytes);
        }
    }

    public async Task<JsonDocument> CreateMasterpassPayment(PaymentData paymentData)
    {
        string apiKey = CalculateApiKey();

        var data = new
        {
            apiKey,
            apiSecretKey,
            gsm = paymentData.Gsm,
            trxCurrency = "TRY",
            trxAmount = paymentData.Amount,
            trxCode = paymentData.OrderId,
            trxType = "SALES",
            callbackUrl = paymentData.CallbackUrl,
            sellerList = paymentData.Sellers,
            shippingCost = paymentData.ShippingCost,
            otherAmount = paymentData.OtherAmount,
            marketplaceCode = mpCode
        };

        using var client = new HttpClient();
        var jsonContent = new StringContent(
            JsonSerializer.Serialize(data),
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"{baseURL}/payment/create/MASTERPASS", jsonContent);
        var jsonString = await response.Content.ReadAsStringAsync();
        return JsonDocument.Parse(jsonString);
    }
}

public class PaymentData
{
    public string Gsm { get; set; }
    public decimal Amount { get; set; }
    public string OrderId { get; set; }
    public string CallbackUrl { get; set; }
    public List<Seller> Sellers { get; set; }
    public decimal ShippingCost { get; set; }
    public decimal OtherAmount { get; set; }
}

public class Seller
{
    public string sellerExternalId { get; set; }
    public decimal trxAmount { get; set; }
    public decimal withholdingTax { get; set; }
}

// Usage
var masterpass = new MasterpassPayment(
    Environment.GetEnvironmentVariable("API_SECRET_KEY"),
    Environment.GetEnvironmentVariable("MERCHANT_SECRET_KEY"),
    "MP12345",
    "https://apitest.paynkolay.com.tr/marketplace/v1"
);

// Create payment
var payment = await masterpass.CreateMasterpassPayment(new PaymentData
{
    Gsm = "5321234567",
    Amount = 250.00m,
    OrderId = "ORDER_789",
    CallbackUrl = "https://yoursite.com/payment-callback",
    Sellers = new List<Seller>
    {
        new Seller
        {
            sellerExternalId = "SELLER_001",
            trxAmount = 250.00m,
            withholdingTax = 2.00m
        }
    },
    ShippingCost = 0,
    OtherAmount = 0
});

// Decode and display form
if (payment.RootElement.GetProperty("success").GetBoolean() &&
    payment.RootElement.GetProperty("data").TryGetProperty("form", out var formElement))
{
    byte[] formBytes = Convert.FromBase64String(formElement.GetString());
    string htmlForm = Encoding.UTF8.GetString(formBytes);
    // Display HTML to user
}
import requests
import hashlib
import base64
import os
import json

class MasterpassPayment:
    def __init__(self, api_secret_key, merchant_secret_key, mp_code, base_url):
        self.api_secret_key = api_secret_key
        self.merchant_secret_key = merchant_secret_key
        self.mp_code = mp_code
        self.base_url = base_url

    def calculate_api_key(self):
        hash_string = f"{self.api_secret_key}|{self.merchant_secret_key}"
        hash_bytes = hashlib.sha512(hash_string.encode('utf-8')).digest()
        return base64.b64encode(hash_bytes).decode('utf-8')

    def create_masterpass_payment(self, payment_data):
        api_key = self.calculate_api_key()

        data = {
            'apiKey': api_key,
            'apiSecretKey': self.api_secret_key,
            'gsm': payment_data['gsm'],
            'trxCurrency': 'TRY',
            'trxAmount': payment_data['amount'],
            'trxCode': payment_data['orderId'],
            'trxType': 'SALES',
            'callbackUrl': payment_data['callbackUrl'],
            'sellerList': payment_data['sellers'],
            'shippingCost': payment_data.get('shippingCost', 0),
            'otherAmount': payment_data.get('otherAmount', 0),
            'marketplaceCode': self.mp_code
        }

        response = requests.post(
            f"{self.base_url}/payment/create/MASTERPASS",
            json=data
        )

        return response.json()

# Usage
masterpass = MasterpassPayment(
    os.getenv('API_SECRET_KEY'),
    os.getenv('MERCHANT_SECRET_KEY'),
    'MP12345',
    'https://apitest.paynkolay.com.tr/marketplace/v1'
)

# Create payment
payment = masterpass.create_masterpass_payment({
    'gsm': '5321234567',
    'amount': 250.00,
    'orderId': 'ORDER_789',
    'callbackUrl': 'https://yoursite.com/payment-callback',
    'sellers': [
        {
            'sellerExternalId': 'SELLER_001',
            'trxAmount': 250.00,
            'withholdingTax': 2.00
        }
    ],
    'shippingCost': 0,
    'otherAmount': 0
})

# Decode and display form
if payment.get('success') and payment.get('data', {}).get('form'):
    html_form = base64.b64decode(payment['data']['form']).decode('utf-8')
    # Display HTML to user

Callback İşleme

Standart ödemeyle aynıdır; paymentSystem alanı MASTERPASS değeriyle gelir. Hash doğrulamasını atlamayın. Kullanıcının GSM numarası Masterpass'e kayıtlı değilse, ödeme ekranında kayıt olma seçeneği sunulur.

Callback İşleme — JavaScript
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 === '200' || responseCode === '2') {
    // 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');
});

Sık Yapılan Hatalar

Kart bilgisi göndermeyin
// ❌ 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
}
GSM Doğrulama — JavaScript
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 bilgisiGerekmezGerekir
GSMZorunluOpsiyonel
HızÇok hızlı (SMS onayı)Form doldurma gerekir
GüvenlikMasterpass altyapısı3D Secure
Kayıtlı kartOtomatik gelirManuel yönetilir

Test Etme

Test için Mastercard'ın sağladığı test GSM numaraları ve Masterpass test hesabına ekleyeceğiniz test kartları kullanılır; ortam olarak apitest.paynkolay.com.tr seçin. Masterpass test hesabı bilgileri için Paynkolay destek ekibine başvurun.

Son güncelleme: 10 Eylül 2026

v1 · Versiyonlar