Pazaryeri Entegrasyonu

İptal ve İade

Pazaryeri işlemlerini aynı gün içinde iptal edin (PaymentCancel) veya sonraki günlerde kısmen ya da tamamen iade edin (PaymentRefund).

İptal ile İade Farkı

İşlem	Ne Zaman?	Açıklama
Cancel	Aynı gün	Ödeme aynı gün içinde iptal edilir, müşteriden para çekilmez
Refund	Ertesi gün ve sonrası	Çekilen para müşteriye iade edilir; 2-10 iş günü sürer

PaymentRefund

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/payment/refund

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/payment/refund

İstek — JSON

{
  "apiKey": "calculated_api_key_for_refund",
  "apiSecretKey": "sx_iptal_value",
  "mpCode": "MP12345",
  "refCode": "REF123456789",
  "trxType": "refund",
  "trxDate": "2025-01-20",
  "totalTrxAmount": 150.00,
  "trxCurrency": "TRY",
  "sellerList": [
    { "sellerExternalId": "SELLER_001", "trxAmount": 100.00, "refundedCommissionAmount": 5.00, "withholdingTax": 0.80 },
    { "sellerExternalId": "SELLER_002", "trxAmount": 50.00, "refundedCommissionAmount": 2.50, "withholdingTax": 0.40 }
  ]
}

Parametre	Tip	Zorunlu	Açıklama
apiKey	String	✅	İptal/iade formülüyle hesaplanmış anahtar — bkz. İptal/İade ApiKey
apiSecretKey	String	✅	İptal işlemleri için özel SX değeri
mpCode	String	✅	Pazaryeri kodu
refCode	String	✅	Orijinal işlemin referans kodu
trxType	String	✅	refund
trxDate	String	✅	İşlem tarihi (yyyy-MM-dd)
totalTrxAmount	BigDecimal	✅	Toplam iade tutarı
trxCurrency	String	✅	Para birimi
sellerList[].trxAmount	BigDecimal	✅	Satıcı başına iade edilecek tutar
sellerList[].refundedCommissionAmount	BigDecimal	❌	İade edilecek komisyon tutarı
sellerList[].withholdingTax	BigDecimal	❌	İade edilecek stopaj tutarı

Stopaj iadesi: iade işlemlerinde de stopajı KDV hariç tutar üzerinden hesaplayıp withholdingTax alanında bildirin (100 TL iade → 80 TL KDV hariç → 0.8 TL stopaj).

İndirimli İşlemlerde İade

Satıcı İndirimi Olan İade

Ürün Tutarı: 1000 TL, Satıcı İndirimi: 100 TL
totalTrxAmount = trxAmount - sellerDiscountAmount = 900 TL

{ "totalTrxAmount": 900.00,
  "sellerList": [ { "sellerExternalId": "SELLER_001", "trxAmount": 1000.00,
                    "sellerDiscountAmount": 100.00, "withholdingTax": 7.20 } ] }

Pazaryeri İndirimi Olan İade

Ürün Tutarı: 1000 TL, Pazaryeri İndirimi: 100 TL
totalTrxAmount = trxAmount - mpDiscountAmount = 900 TL

{ "totalTrxAmount": 900.00, "mpDiscountAmount": 100.00,
  "sellerList": [ { "sellerExternalId": "SELLER_001", "trxAmount": 1000.00,
                    "sellerDiscountAmount": 0.00 } ] }

Kısmi İade

Çok satıcılı bir siparişte yalnızca ilgili satıcıları sellerList'e koyun; totalTrxAmount yalnız iade edilen tutarı içerir. Kısmi tutar iadesi de aynı şekilde çalışır (200 TL'lik işlemden 50 TL iade gibi).

Kısmi İade Örneği — JavaScript

// Orijinal ödeme: 500 TL (3 satıcı)
// Sadece 1 satıcıya iade yapılacak / Only 1 seller will be refunded

async function partialRefund() {
  const refund = await paymentRefund({
    apiKey: calculateRefundApiKey(),
    apiSecretKey: process.env.API_SECRET_KEY_CANCEL,
    mpCode: 'MP12345',
    refCode: 'REF_ORIGINAL',
    trxType: 'refund',
    trxDate: '2025-01-20',
    totalTrxAmount: 150.00,  // Sadece 1 satıcının tutarı / Only 1 seller's amount
    trxCurrency: 'TRY',
    sellerList: [
      {
        sellerExternalId: 'SELLER_001',
        trxAmount: 150.00,
        refundedCommissionAmount: 7.50,
        withholdingTax: 1.20
      }
      // Diğer satıcılar gönderilmez / Other sellers are not sent
    ]
  });

  return refund;
}

Yanıt — JSON

{
  "data": {
    "trxStatus": "APPROVED",
    "mpReferenceCode": "MPREF987654",
    "trxType": "REFUND",
    "trxReferenceCode": "REFUND123456"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

PaymentCancel

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/payment/cancel

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/payment/cancel

İstek — JSON

{
  "apiKey": "calculated_api_key_for_cancel",
  "apiSecretKey": "sx_iptal_value",
  "mpCode": "MP12345",
  "refCode": "REF123456789",
  "trxType": "cancel",
  "trxDate": "2025-01-20",
  "totalTrxAmount": 150.00,
  "trxCurrency": "TRY",
  "sellerList": []
}

sellerList boş array olarak gönderilir. İptal yalnızca işlem günü yapılabilir; ertesi gün için PaymentRefund kullanın.

Yanıt — JSON

{
  "data": {
    "trxStatus": "APPROVED",
    "mpReferenceCode": "MPCANCEL987654",
    "trxType": "CANCEL",
    "trxReferenceCode": "CANCEL123456"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Hash Hesaplama

İki servis de iptal SX ile imzalanır:

İptal/İade ApiKey — JavaScript

function calculateRefundCancelApiKey(apiSecretKeyIptal, merchantSecretKey, trxType, trxDate, amount, trxCurrency, referenceCode) {
  const hashString = [apiSecretKeyIptal, merchantSecretKey, trxType, trxDate, amount, trxCurrency, referenceCode].join('|');

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

Güvenli İade Deseni

İade öncesi işlemin durumunu sorgulayıp tutarı doğrulayan örnek:

safeRefund — JavaScript

async function safeRefund(refCode, sellers) {
  try {
    const result = await refundPayment(refCode, sellers);

    if (result.success) {
      console.log('İade başarılı:', result.data.trxReferenceCode);
      return result;
    } else {
      throw new Error(result.responseMessage);
    }

  } catch (error) {
    console.error('İade hatası:', error.message);

    // Hata tipine göre işlem
    if (error.message.includes('ALREADY_REFUNDED')) {
      console.log('Bu işlem zaten iade edilmiş');
      // Veritabanında güncelle
    } else if (error.message.includes('INSUFFICIENT_BALANCE')) {
      console.log('Yetersiz bakiye, sonra tekrar dene');
      // Kuyruğa ekle
    } else {
      // Genel hata
      console.log('İade başarısız, destek ekibine bildir');
    }

    throw error;
  }
}

Hata Durumları

Hata	Sebep	Çözüm
ALREADY_REFUNDED	İşlem zaten iade edilmiş	İade durumunu kontrol edin
INSUFFICIENT_BALANCE	Yetersiz bakiye	Satıcı hesabında yeterli bakiye olmalı
INVALID_DATE	Geçersiz tarih	Tarih formatını kontrol edin (yyyy-MM-dd)
TRANSACTION_NOT_FOUND	İşlem bulunamadı	refCode'u kontrol edin
SAME_DAY_USE_CANCEL	Aynı gün için refund kullanılmış	Cancel kullanın
INVALID_HASH	Hash doğrulama hatası	İptal SX değerini kontrol edin

Bu sayfa yardımcı oldu mu?

Son güncelleme: 10 Eylül 2026