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
GetStoredCardList
Payment Profile servisleri (Create, Get, Update, Delete, List)
Seller servisleri (Create, Get, Update, Delete, List)

Hash Hesaplama Formülü

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

Parametreler

Parametre	Açıklama	Nereden Alınır
`apiSecretKey`	SX değeri	Pay N Kolay tarafından verilir
`merchantSecretKey`	Merchant gizli anahtarı	Pay N Kolay tarafından verilir

Örnek Kodlar

JavaScript/Node.js

const crypto = require('crypto');

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

    // 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 = "_YckdxUbv4vrnMUZ6VQsr";

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

PHP

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

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

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

    return $apiKey;
}

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

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

Python

import hashlib
import base64

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

    # 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 = "_YckdxUbv4vrnMUZ6VQsr"

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

C#

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

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

        // 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 = "_YckdxUbv4vrnMUZ6VQsr";

        string apiKey = CalculatePaymentApiKey(apiSecretKey, merchantSecretKey);
        Console.WriteLine($"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))

Örnek Kod (JavaScript)

function calculateRefundCancelApiKey(apiSecretKey_iptal, merchantSecretKey) {
    const hashString = apiSecretKey_iptal + '|' + merchantSecretKey;
    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 = "_YckdxUbv4vrnMUZ6VQsr";

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

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(
    timestamp + "|" +
    referenceCode + "|" +
    trxCode + "|" +
    authAmount + "|" +
    responseCode + "|" +
    apiSecretKey
))

Callback Hash Doğrulama Örneği

function verifyCallbackHash(callbackData, apiSecretKey) {
    const {
        timestamp,
        referenceCode,
        trxCode,
        authAmount,
        responseCode,
        hash
    } = callbackData;

    // Hash string oluştur
    const hashString = [
        timestamp,
        referenceCode,
        trxCode,
        authAmount,
        responseCode,
        apiSecretKey
    ].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|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==

merchantSecretKey: _YckdxUbv4vrnMUZ6VQsr

apiSecretKey (İptal): 118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==|yDUZaCk6rsoHZJWI3d471A/+TJA7C81X

Sonraki Adımlar

Hash hesaplama mekanizmasını öğrendikten sonra:

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