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

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

Bu Bölümde Pazaryeri Entegrasyonu

Bu sayfa yardımcı oldu mu?

Son güncelleme: 5 Eylül 2026