Hash Hesaplama

Hash Nedir? #

Hash, API isteklerinin güvenliğini sağlamak için kullanılan bir güvenlik mekanizmasıdır. İsteklerin değiştirilmediğinden ve yetkili bir kaynaktan geldiğinden emin olmak için kullanılır.

Pazaryeri API'sinde iki farklı işlem için hash hesaplaması yapmanız gerekir:

Ödeme İşlemleri için ApiKey hesaplama
İptal/İade İşlemleri için ApiKey hesaplama

Ödeme İşlemleri için ApiKey Hesaplama #

Kullanıldığı Servisler #

CreatePayment
Payment Profile servisleri (Create, Get, Update, Delete, List)
Seller servisleri (Create, Get, Update, Delete, List)

Hash Hesaplama Formülü #

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

Parametreler #

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 (Örn: TRY)	İşlem para birimi
trxType	İşlem tipi (Örn: SALES)	SALES

Önemli
apiSecretKey değeri SX değerine, merchantSecretKey değeri ise MerchantSecretKey değerine denk gelmektedir.

Örnek Kodlar #

const crypto = require('crypto');

function calculatePaymentApiKey(apiSecretKey, merchantSecretKey, trxCode, totalTrxAmount, trxCurrency, trxType) {
    // String birleştirme
    const hashString = apiSecretKey + '|' + merchantSecretKey + '|' + trxCode + '|' + totalTrxAmount + '|' + trxCurrency + '|' + trxType;

    // SHA512 hash hesaplama
    const hash = crypto.createHash('sha512').update(hashString, 'utf8').digest();

    // Base64 encode
    const apiKey = hash.toString('base64');

    return apiKey;
}

// Kullanım
const apiSecretKey = "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJl...";
const merchantSecretKey = "_viH5wUS4HiBmmw9uGybN";

const apiKey = calculatePaymentApiKey(apiSecretKey, merchantSecretKey);
console.log("ApiKey:", apiKey);

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

    // SHA512 hash hesaplama
    $hash = hash('sha512', $hashString, true);

    // Base64 encode
    $apiKey = base64_encode($hash);

    return $apiKey;
}

// Kullanım
$apiSecretKey = "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJl...";
$merchantSecretKey = "_viH5wUS4HiBmmw9uGybN";

$apiKey = calculatePaymentApiKey($apiSecretKey, $merchantSecretKey);
echo "ApiKey: " . $apiKey;
?>

import hashlib
import base64

def calculate_payment_api_key(api_secret_key, merchant_secret_key, trx_code, total_trx_amount, trx_currency, trx_type):
    # String birleştirme
    hash_string = api_secret_key + '|' + merchant_secret_key + '|' + trx_code + '|' + total_trx_amount + '|' + trx_currency + '|' + trx_type

    # SHA512 hash hesaplama
    hash_bytes = hashlib.sha512(hash_string.encode('utf-8')).digest()

    # Base64 encode
    api_key = base64.b64encode(hash_bytes).decode('utf-8')

    return api_key

# Kullanım
api_secret_key = "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJl..."
merchant_secret_key = "_viH5wUS4HiBmmw9uGybN"

api_key = calculate_payment_api_key(api_secret_key, merchant_secret_key)
print(f"ApiKey: {api_key}")

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

public class HashCalculator
{
    public static string CalculatePaymentApiKey(string apiSecretKey, string merchantSecretKey, string trxCode, string totalTrxAmount, string trxCurrency, string trxType)
    {
        // String birleştirme
        string hashString = apiSecretKey + "|" + merchantSecretKey + "|" + trxCode + "|" + totalTrxAmount + "|" + trxCurrency + "|" + trxType;

        // SHA512 hash hesaplama
        using (SHA512 sha512 = SHA512.Create())
        {
            byte[] hashBytes = sha512.ComputeHash(Encoding.UTF8.GetBytes(hashString));

            // Base64 encode
            string apiKey = Convert.ToBase64String(hashBytes);

            return apiKey;
        }
    }

    // Kullanım
    public static void Main()
    {
        string apiSecretKey = "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJl...";
        string merchantSecretKey = "_viH5wUS4HiBmmw9uGybN";

        string apiKey = CalculatePaymentApiKey(apiSecretKey, merchantSecretKey);
        Console.WriteLine($"ApiKey: {apiKey}");
    }
}

Saklı Kart Listeleme (GetStoredCardList) için ApiKey Hesaplama #

/payment/storedCardList servisinin apiKey parametresi, ödeme formülünden farklıdır. Kart saklama servisindeki hashData ile aynıdır ve yalnızca üç alandan oluşur.

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

Önemli
Bu servis SHA-512 yöntemini kabul etmektedir (eski SHA-1 yöntemi kaldırılmıştır). Alan sırasına dikkat edin: mpCustomerKey, merchantSecretKey'den önce gelir ve ödeme formülündeki totalTrxAmount|trxCurrency|trxType alanları kullanılmaz.

Ö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);
echo "ApiKey: " . $apiKey;

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

Kullanıldığı Servisler #

PaymentRefund
PaymentCancel

Hash Hesaplama Formülü #

İptal ve iade işlemleri için aynı formül kullanılır, ancak farklı bir apiSecretKey değeri kullanılır.

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

Önemli
İptal/İade işlemleri için kullanılan apiSecretKey değeri, ödeme işlemlerinden farklıdır. Bu değer size ayrıca iptal sx değeri olarak verilecektir.

Örnek Kod (JavaScript) #

function calculateRefundCancelApiKey(apiSecretKey_iptal, merchantSecretKey, trxType, trxDate, amount, trxCurrency, referenceCode) {
    const hashString = apiSecretKey_iptal + '|' + merchantSecretKey + '|' + trxType + '|' + trxDate + '|' + amount + '|' + trxCurrency + '|' + referenceCode;
    const hash = crypto.createHash('sha512').update(hashString, 'utf8').digest();
    const apiKey = hash.toString('base64');
    return apiKey;
}

// Kullanım
const apiSecretKey_iptal = "118591467|bScbGDYC...iptal_sx_degeri...";
const merchantSecretKey = "_viH5wUS4HiBmmw9uGybN";

const apiKey = calculateRefundCancelApiKey(apiSecretKey_iptal, merchantSecretKey);
console.log("Refund/Cancel ApiKey:", apiKey);

Hash Hesaplama Servisleri #

Kendi hash implementasyonunuzu doğrulamak için Pazaryeri API'si üzerinde iki yardımcı servis bulunur. Bu servisler, gönderdiğiniz alanlardan apiKey değerini sunucu tarafında hesaplayıp döner; sonuç, yukarıdaki formüllerle lokal olarak hesaplayacağınız değerle birebir aynıdır.

Bu servisler entegrasyon geliştirme sırasında doğrulama amaçlıdır. Canlı ortamda her istek için hash'i lokal olarak hesaplamanız önerilir; her ödeme öncesi ek bir servis çağrısı yapmak gecikme yaratır. Bu servisler JWT token ile çağrılır.

Ödeme Hash Servisi #

TEST:

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

PROD:

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

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
apiSecretKey	String	✅	Satış SX değeri
secretKey	String	✅	MerchantSecretKey değeri
trxCode	String	✅	İşlem takip kodu (Client Reference Code)
totalTrxAmount	String	✅	Karttan çekilecek toplam tutar (vergiler + komisyon dahil)
trxCurrency	String	✅	Para birimi (TRY)
trxType	String	✅	İşlem tipi (SALES)

Yanıt #

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

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

İptal/İade Hash Servisi #

TEST:

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

PROD:

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

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
apiSecretKey	String	✅	İptal SX değeri
secretKey	String	✅	MerchantSecretKey değeri
trxType	String	✅	İptal için `cancel`, iade ya da kısmi iade için `refund`
trxDate	String	✅	İşlem tarihi (yyyy-MM-dd)
amount	String	✅	İptal/tam iade için karttan çekilen tutar; kısmi iade için iade edilecek tutar
trxCurrency	String	✅	Para birimi (TRY)
referenceCode	String	✅	İşleme ait Paynkolay referans numarası

Yanıt #

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

Dönen apiKey değeri /payment/refund ve /payment/cancel servislerinde kullanılır.

Hash Doğrulama (Callback'lerde) #

Ödeme işlemi tamamlandığında, callbackUrl adresinize post edilen verilerin doğruluğunu kontrol etmek için hash doğrulaması yapmalısınız.

Callback Hash Formülü #

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

Callback Hash Doğrulama Örneği #

function verifyCallbackHash(callbackData, apiSecretKey) {
    const {
        statusCode,
        refCode,
        authCode,
        trxCode,
        commissionRate,
        commissionAmount,
        installment,
        trxAmount,
        authAmount,
        timestamp,
        currencyCode,
        cardType,
        issuerBankCode,
        installmentFeeRate,
        installmentFeeAmount,
        paymentSystem,
        hash
    } = callbackData;

    // Hash string oluştur
    const hashString = [
        apiSecretKey,
        statusCode,
        refCode,
        authCode,
        trxCode,
        commissionRate,
        commissionAmount,
        installment,
        trxAmount,
        authAmount,
        timestamp,
        currencyCode,
        cardType,
        issuerBankCode,
        installmentFeeRate,
        installmentFeeAmount,
        paymentSystem
    ].join('|');

    // Hash hesapla
    const calculatedHash = crypto
        .createHash('sha512')
        .update(hashString, 'utf8')
        .digest('base64');

    // Karşılaştır
    return calculatedHash === hash;
}

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

    if (verifyCallbackHash(callbackData, apiSecretKey)) {
        // Hash doğrulandı, işlemi kabul et
        console.log('Ödeme doğrulandı:', callbackData.trxCode);
        // İşleminizi burada gerçekleştirin
    } else {
        // Hash doğrulanamadı, şüpheli istek
        console.error('Hash doğrulama başarısız!');
        return res.status(400).send('Invalid hash');
    }

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

Güvenlik En İyi Uygulamaları #

1. Anahtarları Güvenli Saklayın #

// ❌ YANLIŞ - Koda hardcode etmeyin
const apiSecretKey = "118591467|bScbGDYC...";

// ✅ DOĞRU - Environment variables 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 - Sadece HTTPS kullanın
const url = "https://api.paynkolay.com.tr/marketplace/v1/payment/create";

3. Hash'i Her İstek İçin Yeniden Hesaplayın #

// Hash'i cache'lemeyin, her istek için yeniden hesaplayın
function createPayment(paymentData) {
    // Her seferinde yeni hash hesapla
    const apiKey = calculatePaymentApiKey(apiSecretKey, merchantSecretKey);

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

4. Callback Hash'ini Mutlaka Doğrulayın #

// Callback'lerde 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');
});

Test Ortamı Değerleri #

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

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 için size özel anahtarlar Paynkolay tarafından verilecektir.

Sonraki Adımlar #

Hash hesaplama mekanizmasını öğrendikten sonra:

1. Ödeme Profili Oluşturma - İlk profilinizi oluşturun
2. Ödeme İşlemleri - Ödeme almaya başlayın
3. İptal ve İade İşlemleri - İptal/iade yapın