Panel Giriş Başvurun
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))
ParametreAçıklamaNereden Alınır
apiSecretKeySX değeriPaynkolay tarafından verilir
merchantSecretKeyMerchant gizli anahtarıPaynkolay tarafından verilir
trxCodeİşlem takip numarası (Client Reference Code)Siz belirlersiniz
totalTrxAmountToplam işlem tutarı (vergiler + komisyon dahil)İşlem tutarı
trxCurrencyPara 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')

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))

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))

İ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"
}

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"
}

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
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;
}

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

Son güncelleme: 5 Eylül 2026

v2 · Versiyonlar