Pazaryeri Entegrasyonu

Hash Hesaplama

İsteklerin değiştirilmediğini ve yetkili kaynaktan geldiğini kanıtlayan apiKey imzasını üretme kuralları — ödeme, saklı kart ve iptal/iade için üç ayrı formül vardır.

Ödeme İşlemleri için ApiKey

CreatePayment ile tüm Payment Profile ve Seller servislerinde kullanılır:

Formül

apiKey = Base64(SHA512(apiSecretKey + "|" + merchantSecretKey + "|" + trxCode + "|" + totalTrxAmount + "|" + trxCurrency + "|" + trxType))

Parametre	Açıklama	Nereden Alınır
apiSecretKey	SX değeri	Paynkolay tarafından verilir
merchantSecretKey	Merchant gizli anahtarı	Paynkolay tarafından verilir
trxCode	İşlem takip numarası (Client Reference Code)	Siz belirlersiniz
totalTrxAmount	Toplam işlem tutarı (vergiler + komisyon dahil)	İşlem tutarı
trxCurrency	Para birimi (ör. TRY)	İşlem para birimi
trxType	İşlem tipi (ör. SALES)	SALES

<?php
function calculatePaymentApiKey($apiSecretKey, $merchantSecretKey, $trxCode, $totalTrxAmount, $trxCurrency, $trxType) {
    $hashString = $apiSecretKey . '|' . $merchantSecretKey . '|' . $trxCode . '|'
                . $totalTrxAmount . '|' . $trxCurrency . '|' . $trxType;

    return base64_encode(hash('sha512', $hashString, true));
}

const crypto = require('crypto');

function calculatePaymentApiKey(apiSecretKey, merchantSecretKey, trxCode, totalTrxAmount, trxCurrency, trxType) {
  const hashString = [apiSecretKey, merchantSecretKey, trxCode, totalTrxAmount, trxCurrency, trxType].join('|');

  return crypto.createHash('sha512').update(hashString, 'utf8').digest('base64');
}

import hashlib
import base64

def calculate_payment_api_key(api_secret_key, merchant_secret_key, trx_code, total_trx_amount, trx_currency, trx_type):
    hash_string = api_secret_key + '|' + merchant_secret_key + '|' + trx_code + '|' \
                + total_trx_amount + '|' + trx_currency + '|' + trx_type

    hash_bytes = hashlib.sha512(hash_string.encode('utf-8')).digest()

    return base64.b64encode(hash_bytes).decode('utf-8')

using System;
using System.Security.Cryptography;
using System.Text;

public static string CalculatePaymentApiKey(string apiSecretKey, string merchantSecretKey,
    string trxCode, string totalTrxAmount, string trxCurrency, string trxType)
{
    string hashString = apiSecretKey + "|" + merchantSecretKey + "|" + trxCode + "|"
                      + totalTrxAmount + "|" + trxCurrency + "|" + trxType;

    using (SHA512 sha512 = SHA512.Create())
    {
        byte[] hashBytes = sha512.ComputeHash(Encoding.UTF8.GetBytes(hashString));
        return Convert.ToBase64String(hashBytes);
    }
}

Saklı Kart Listeleme için ApiKey

/payment/storedCardList servisinin apiKey parametresi ödeme formülünden farklıdır ve yalnızca üç alandan oluşur:

Formül

apiKey = Base64(SHA512(apiSecretKey + "|" + mpCustomerKey + "|" + merchantSecretKey))

Örnek Kod — PHP

function calculateStoredCardApiKey($apiSecretKey, $mpCustomerKey, $merchantSecretKey) {
    $hashString = $apiSecretKey . '|' . $mpCustomerKey . '|' . $merchantSecretKey;
    return base64_encode(hash('sha512', $hashString, true));
}

// Kullanım
$apiKey = calculateStoredCardApiKey($apiSecretKey, $mpCustomerKey, $merchantSecretKey);

Bu servis SHA-512 yöntemini kabul eder (eski SHA-1 kaldırılmıştır). Alan sırasına dikkat: mpCustomerKey, merchantSecretKey'den önce gelir; ödeme formülündeki tutar/para birimi/tip alanları kullanılmaz.

İptal/İade İşlemleri için ApiKey

PaymentRefund ve PaymentCancel servislerinde kullanılır; formül aynıdır ancak iptal SX değeriyle imzalanır:

Formül

apiKey = Base64(SHA512(apiSecretKey_iptal + "|" + merchantSecretKey + "|" + trxType + "|" + trxDate + "|" + amount + "|" + trxCurrency + "|" + referenceCode))

Örnek Kod — JavaScript

function calculateRefundCancelApiKey(apiSecretKey_iptal, merchantSecretKey,
                                    trxType, trxDate, amount, trxCurrency, referenceCode) {
    const hashString = apiSecretKey_iptal + '|' + merchantSecretKey + '|' + trxType + '|'
                     + trxDate + '|' + amount + '|' + trxCurrency + '|' + referenceCode;

    return crypto.createHash('sha512').update(hashString, 'utf8').digest('base64');
}

İptal/iade için kullanılan apiSecretKey, ödeme işlemlerindekinden farklıdır; bu değer size ayrıca iptal sx olarak verilir.

Hash Hesaplama Servisleri

Kendi implementasyonunuzu doğrulamak için API üzerinde iki yardımcı servis vardır; gönderdiğiniz alanlardan apiKey'i sunucuda hesaplayıp döner. Bu servisler JWT token ile çağrılır ve geliştirme sırasında doğrulama amaçlıdır — canlıda her istek için hash'i lokal hesaplayın, ek servis çağrısı gecikme yaratır.

Ödeme Hash Servisi

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/calculate-hash/payment

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/calculate-hash/payment

İstek — JSON

{
  "apiSecretKey": "sx_value",
  "secretKey": "merchant_secret_key",
  "trxCode": "ORDER_12345",
  "totalTrxAmount": "5000.00",
  "trxCurrency": "TRY",
  "trxType": "SALES"
}

Yanıt — JSON

{
  "data": {
    "apiKey": "c74C2ED/3GSEv16w72oRe+VDOczKa1UKDWVMOe+lOeQQOwsaKX2RU+ZFWRS76wESvTAsfaMAqR2ss2h13K66WA=="
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "İşlem Başarılı"
}

Dönen data.apiKey değeri /payment/create servisinde kullanılır.

İptal/İade Hash Servisi

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/calculate-hash/refund-cancel

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/calculate-hash/refund-cancel

İstek — JSON

{
  "apiSecretKey": "cancel_sx_value",
  "secretKey": "merchant_secret_key",
  "trxType": "refund",
  "trxDate": "2025-10-30",
  "amount": "2000.00",
  "trxCurrency": "TRY",
  "referenceCode": "IKSIRPF456012"
}

Yanıt — JSON

{
  "data": {
    "apiKey": "rs5B9t+dc140bY68A5FlhVxpb6fjo2Qm5ihs98J0ODyCLFc0B0RLz9MgEX4G5yqgNu31m0KJg8kKsMug6UjylA=="
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "İşlem Başarılı"
}

trxType: iptal için cancel, iade ya da kısmi iade için refund. Dönen apiKey, /payment/refund ve /payment/cancel servislerinde kullanılır.

Callback Hash Doğrulama

Ödeme tamamlandığında callbackUrl adresinize POST edilen verinin bütünlüğünü mutlaka doğrulayın:

Callback Hash Formülü

expectedHash = Base64(SHA512(
    apiSecretKey | statusCode | refCode | authCode | trxCode |
    commissionRate | commissionAmount | installment | trxAmount |
    authAmount | timestamp | currencyCode | cardType | issuerBankCode |
    installmentFeeRate | installmentFeeAmount | paymentSystem
))

Doğrulama — JavaScript (Express)

function verifyCallbackHash(cb, apiSecretKey) {
  const hashString = [
    apiSecretKey, cb.statusCode, cb.refCode, cb.authCode, cb.trxCode,
    cb.commissionRate, cb.commissionAmount, cb.installment, cb.trxAmount,
    cb.authAmount, cb.timestamp, cb.currencyCode, cb.cardType, cb.issuerBankCode,
    cb.installmentFeeRate, cb.installmentFeeAmount, cb.paymentSystem
  ].join('|');

  const calculated = crypto.createHash('sha512').update(hashString, 'utf8').digest('base64');

  return calculated === cb.hash;
}

// Kullanım — Express callback ucu
app.post('/payment-callback', (req, res) => {
  const apiSecretKey = process.env.API_SECRET_KEY;

  if (!verifyCallbackHash(req.body, apiSecretKey)) {
    // Hash doğrulanamadı: şüpheli istek, işleme alma
    return res.status(400).send('Invalid hash');
  }

  // Hash doğrulandı — siparişi burada sonuçlandırın
  console.log('Ödeme doğrulandı:', req.body.trxCode);
  res.status(200).send('OK');
});

Test Ortamı Değerleri

Test ortamında hash hesaplaması için kullanabileceğiniz herkese açık örnek değerler:

Test Anahtarları

apiSecretKey (SX): 118591467|W8a1JLU8A5Cw+HfadVcO6HiR/GGGxr0NkWr2OGythr8fo0YWdw70cvnI6oKMqvzra3Qu+Wa5u0NRil9gRdJmjocVNd4XciDwfD9+pkVqDErw7/pVZfpcSO+GePg+ZvcqFbOO5A==

merchantSecretKey: _viH5wUS4HiBmmw9uGybN

apiSecretKey (İptal): 118591467|W8a1JLU8A5Cw+HfadVcO6HiR/GGGxr0NkWr2OGythr8fo0YWdw70cvnI6oKMqvzra3Qu+Wa5u0NRil9gRdJmjocVNd4XciDwfD9+pkVqDErw7/pVZfpcSO+GePg+ZvcqFbOO5A==|yDUZaCk6rsoHZJWI3d471A/+TJA7C81X

Canlı ortam anahtarlarınız Paynkolay tarafından size özel verilir.

Güvenlik En İyi Uygulamaları

Anahtarları environment variable'da saklayın, asla koda gömmeyin
Yalnızca HTTPS kullanın
Hash'i cache'lemeyin — her istek için yeniden hesaplayın
Callback'lerde gelen hash'i mutlaka doğrulayın, doğrulanmayan isteği reddedin

1 · Anahtarları güvenli saklayın

// ❌ YANLIŞ — koda gömmeyin
const apiSecretKey = "118591467|bScbGDYC...";

// ✅ DOĞRU — environment variable kullanın
const apiSecretKey = process.env.API_SECRET_KEY;
const merchantSecretKey = process.env.MERCHANT_SECRET_KEY;

2 · HTTPS kullanın

// ❌ YANLIŞ — HTTP kullanmayın
const url = "http://api.paynkolay.com.tr/marketplace/v1/payment/create";

// ✅ DOĞRU — yalnızca HTTPS
const url = "https://api.paynkolay.com.tr/marketplace/v1/payment/create";

3 · Hash'i her istek için yeniden hesaplayın

// Hash'i cache'lemeyin — her istek için yeniden hesaplayın
function createPayment(paymentData) {
  const apiKey = calculatePaymentApiKey(
    apiSecretKey, merchantSecretKey,
    paymentData.trxCode, paymentData.totalTrxAmount, 'TRY', 'SALES'
  );

  return fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...paymentData, apiKey, apiSecretKey })
  });
}

4 · Callback hash'ini mutlaka doğrulayın

// Callback'te gelen hash'i MUTLAKA doğrulayın
app.post('/callback', (req, res) => {
  // ❌ YANLIŞ — hash kontrolü yapmadan işleme devam etmek
  // processPayment(req.body);

  // ✅ DOĞRU — önce hash'i doğrula
  if (!verifyCallbackHash(req.body, apiSecretKey)) {
    return res.status(400).send('Invalid hash');
  }

  processPayment(req.body);
  res.status(200).send('OK');
});

Bu sayfa yardımcı oldu mu?

Son güncelleme: 10 Eylül 2026