Pazaryeri Entegrasyonu

Ödeme İşlemleri

Son kullanıcıdan kartla ödeme alın, tutarı satıcılara ve pazaryerine komisyonlarına göre dağıtın; durum sorgulama, taksit, saklı kart ve tamamlama servisleriyle akışı yönetin.

Stopaj hatırlatma: pazaryeri işlemlerinde %1 stopaj zorunludur — KDV hariç net tutar üzerinden hesaplayıp withholdingTax alanında bildirin. Ayrıntı: Stopaj Uygulaması.

CreatePayment

Yeni bir ödeme başlatır; hem 3D Secure hem 3D'siz işlemler için kullanılır.

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

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

İstek — JSON

{
  "apiKey": "calculated_api_key",
  "apiSecretKey": "sx_value",
  "bankCard": {
    "cardHolder": "AHMET YILMAZ",
    "cardNumber": "4546711234567894",
    "cvv": "123",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "isThreeD": true,
    "registerCard": false
  },
  "installment": 2,
  "isFetchInstallments": false,
  "encodedValue": null,
  "trxCurrency": "TRY",
  "trxAmount": 150.00,
  "trxCode": "ORDER_12345",
  "trxType": "SALES",
  "callbackUrl": "https://yoursite.com/payment-callback",
  "sellerList": [
    { "sellerExternalId": "SELLER_001", "trxAmount": 100.00, "withholdingTax": 0.80, "sellerDiscountAmount": 0.00 },
    { "sellerExternalId": "SELLER_002", "trxAmount": 50.00, "withholdingTax": 0.40, "sellerDiscountAmount": 0.00 }
  ],
  "shippingCost": 0.00,
  "otherAmount": 0.00,
  "mpDiscountAmount": 0.00,
  "totalDiscountAmount": 0.00,
  "marketplaceCode": "MP12345",
  "customerCardInfo": { "mpCustomerKey": "12345678901", "cardAlias": null, "cardTranId": null, "cardToken": null }
}

Temel Parametreler

Parametre	Tip	Zorunlu	Açıklama
apiKey	String	✅	Hash ile üretilen anahtar — bkz. Hash Hesaplama
apiSecretKey	String	✅	SX değeri
trxCurrency	String	✅	Para birimi (TRY, USD, EUR)
trxAmount	BigDecimal	✅	Toplam işlem tutarı
trxCode	String	✅	İşlem takip kodu (kendi referansınız)
trxType	String	✅	İşlem tipi: SALES
callbackUrl	String	✅	3D sonucunun POST edileceği URL; autoComplete=false ise tamamlamayı yapacak kendi servisiniz
marketplaceCode	String	✅	Pazaryeri kodu

Kart Bilgileri — bankCard

Parametre	Tip	Zorunlu	Açıklama
cardHolder	String	✅*	Kart üzerindeki isim (saklı kartta opsiyonel)
cardNumber	String	✅*	Kart numarası (saklı kartta opsiyonel)
cvv	String	✅*	CVV (saklı kartta opsiyonel)
expiryMonth / expiryYear	String	✅*	Son kullanma ay/yıl (saklı kartta opsiyonel)
isThreeD	Boolean	✅	3D Secure kullanılsın mı?
registerCard	Boolean	✅	Kart saklansın mı? (yalnızca 3D'li işlemlerde)

Taksit Bilgileri

Parametre	Tip	Zorunlu	Açıklama
installment	Integer	✅	Taksit sayısı (1 = tek çekim)
isFetchInstallments	Boolean	✅	Taksit bilgisi Paynkolay'dan mı çekilecek?
encodedValue	String	❌	FetchPaymentInstallments'tan dönen encoded değer

Satıcı Listesi — sellerList

Parametre	Tip	Zorunlu	Açıklama
sellerExternalId	String	✅	Satıcının external ID'si
trxAmount	BigDecimal	✅	Satıcıya ait işlem tutarı
commissionRate	BigDecimal	❌	Özel komisyon oranı (profil dışında)
commissionAmount	BigDecimal	❌	Hesaplanmış komisyon tutarı
mpCost	BigDecimal	❌	İşlem ücreti
withholdingTax	BigDecimal	❌	Stopaj tutarı
sellerDiscountAmount	BigDecimal	❌	Satıcı indirim tutarı

Komisyon kuralları: commissionRate ve commissionAmount aynı anda gönderilemez. Özel komisyon uygulanmayacaksa ikisini de null gönderin; yalnız oran gönderirseniz tutar otomatik hesaplanır.

İndirim ve Ücretler / Müşteri Kartı

Parametre	Tip	Zorunlu	Açıklama
shippingCost / otherAmount	BigDecimal	❌	Kargo ve diğer ücretler
mpDiscountAmount / totalDiscountAmount	BigDecimal	❌	Pazaryeri ve toplam indirim tutarları
customerCardInfo.mpCustomerKey	String	✅*	Müşteri kimliği (TCKN/cep/pasaport) — kart saklama için zorunlu
customerCardInfo.cardAlias	String	❌	Kart takma adı (saklama için)
customerCardInfo.cardTranId / cardToken	String	❌	Saklı kart ile ödeme için kimlik/token

Yanıt

Yanıt — JSON

{
  "data": {
    "refCode": "REF123456789",
    "trxCode": "ORDER_12345",
    "form": "PGh0bWw+...3D HTML Form Base64..."
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

form, 3D işlemlerde Base64 kodlu HTML formudur — decode edip müşteriye render edersiniz.

3D Secure Akışı

1CreatePayment gönderinisThreeD=true ile isteği yapın; yanıtta Base64 form döner.
2Formu render edinBase64'ü çözüp HTML'i müşterinin tarayıcısına basın.
3Banka doğrulamasıMüşteri banka 3D ekranında SMS/OTP kodunu girer.
4Callback alınBanka sonucu callbackUrl adresinize POST eder.
5Hash'i doğrulayınGelen veriyi callback hash formülüyle doğrulayın.
6Sonucu işleyinresponseCode 200/2 ise siparişi onaylayın, değilse reddedin.

Form Decode + Callback — JavaScript

// Yanıttaki 3D formunu müşteriye göster
if (response.success && response.data.form) {
  const htmlForm = Buffer.from(response.data.form, 'base64').toString('utf-8');
  res.send(htmlForm);
}

// callbackUrl'e gelen sonucu işle
app.post('/payment-callback', (req, res) => {
  if (!verifyCallbackHash(req.body, apiSecretKey)) {
    return res.status(400).send('Invalid hash');
  }

  if (req.body.responseCode === '200' || req.body.responseCode === '2') {
    updateOrderStatus(req.body.trxCode, 'PAID');
  } else {
    updateOrderStatus(req.body.trxCode, 'FAILED');
  }

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

autoComplete: pazaryeri tanımınızda autoComplete ayarı false ise callback'e gelen POST ödemenin tamamlandığı anlamına gelmez; işlem beklemede kalır ve CompletePaymentExternal servisini çağırarak akışı sizin tamamlamanız gerekir.

GetPaymentStatus

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

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

İstek — JSON

{
  "refCode": "REF123456789",
  "trxCode": "ORDER_12345"
}

refCode veya trxCode'dan en az birini göndermeniz yeterlidir.

Durum	Açıklama
SUCCESS	Başarılı işlem
PENDING	İşlem devam ediyor
FAILED	Başarısız işlem
CANCELLED	İptal edilmiş
REFUNDED	İade yapılmış

GetStoredCardList & Saklı Kartla Ödeme

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

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

İstek — JSON

{
  "mpCode": "MP12345",
  "apiSecretKey": "sx_value",
  "mpCustomerKey": "12345678901",
  "apiKey": "calculated_api_key"
}

Bu servisin apiKey değeri ödeme formülünden farklıdır: Base64(SHA512(apiSecretKey | mpCustomerKey | merchantSecretKey)) — bkz. Saklı Kart ApiKey.

Yanıtta müşterinin kartları cardToken, cardTranId, maskeli PAN ve banka bilgileriyle listelenir. Saklı kartla ödemede kart bilgileri gönderilmez:

Saklı Kartla Ödeme — JavaScript

await createPayment({
  // ...diğer parametreler
  bankCard: {
    isThreeD: true,
    registerCard: false
    // kart bilgileri GÖNDERİLMEZ
  },
  customerCardInfo: {
    mpCustomerKey: '12345678901',
    cardTranId: selectedCard.cardTranId  // VEYA cardToken
  }
});

FetchPaymentInstallments

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

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

İstek — JSON

{
  "mpCode": "MP12345",
  "apiSecretKey": "sx_value",
  "cardNumber": "45467112",
  "amount": 1000.00,
  "isCardValid": false
}

Parametre	Tip	Zorunlu	Açıklama
mpCode	String	✅	Pazaryeri kodu
apiSecretKey	String	✅	SX değeri
cardNumber	String	✅	Kart numarasının ilk 6-8 hanesi veya tamamı
amount	BigDecimal	✅	İşlem tutarı
isCardValid	Boolean	❌	true ise kart geçerliliği kontrol edilir

Yanıttaki her taksit seçeneği installmentAmount, komisyon bilgileri ve bir encodedValue içerir. Kullanıcının seçtiği taksidin encodedValue'sunu CreatePayment'ta isFetchInstallments: true ile gönderirsiniz.

UpdatePaymentCommission

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

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

İstek — JSON

{
  "mpCode": "MP12345",
  "refCode": "REF123456789",
  "trxCode": "ORDER_12345",
  "sellerList": [
    { "sellerExternalId": "SELLER_001", "commissionAmount": 5.00, "trxAmount": 100.00, "withholdingTax": 0.80, "sellerDiscountAmount": 0.00 }
  ]
}

Bu servis yalnızca ödeme işlemiyle aynı gün kullanılabilir; ertesi gün çalışmaz. Stopaj bilgisini de güncellemeyi unutmayın.

CompletePaymentExternal

autoComplete = false olan pazaryerlerinde ödeme otomatik tamamlanmaz: form akışı bitince callback önce sizin servisinize gelir; kendi validasyon ve kayıt işlemlerinizden sonra bu servisi çağırarak akışı tamamlarsınız.

autoComplete	Davranış
true	Varsayılan — ödeme, form akışı tamamlanınca otomatik tamamlanır; ek çağrı gerekmez.
false	Ödeme beklemede kalır; validasyon/DB kaydı sonrası CompletePaymentExternal çağrısıyla siz tamamlarsınız.

Ayar üye işyeri bazında Paynkolay tarafından yapılandırılır; false çalışmak için entegrasyon ekibiyle iletişime geçin.

1CreatePaymentcallbackUrl olarak kendi servisinizi verin.
2Callback POSTForm sonucu REFERENCE_CODE dahil servisinize POST edilir.
3Kayıt oluşturunİşlemi kendi veritabanınıza yazın.
4ValidasyonKendi iş mantığı kontrollerinizi çalıştırın.
5CompletePaymentExternalreferenceCode + satış SX ile tamamlayın.
6Sonuçİşlem sonucu döner, akış tamamlanır.

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

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

Server-to-server JSON POST'tur; JWT token gerektirmez — kimlik doğrulama satış SX ile yapılır. Bu servis, tekil üye işyeri (Vpos) tarafındaki CompletePayment'tan farklıdır ve yalnızca pazaryeri işlemleri içindir. Bu akışta callback alanları büyük harflidir (REFERENCE_CODE, RESPONSE_CODE…); RESPONSE_CODE=2 + boş AUTH_CODE, işlemin tamamlama beklediği anlamına gelir.

İstek — JSON

{
  "referenceCode": "qv6UkBD2m1Ora+tS6UHTW36hm0s4+0RG1pUsoAF6xBuM3cW8ZbIupXOYVpUW6983ZXKzL4qXdE01MEwD+ObnAnA6pOg=",
  "apiSecretKey": "sx_value"
}

Parametre	Tip	Zorunlu	Açıklama
referenceCode	String	✅	Callback'te REFERENCE_CODE alanında gelen Base64 değer — değiştirilmeden gönderilir, tek kullanımlıktır
apiSecretKey	String	✅	Satış SX değeri

Başarılı yanıt responseCode: "2" ile işlem detaylarını (authCode, tutarlar, komisyon, hash…) döner. Hata durumlarında da HTTP 200 gelir — sonucu success ve responseCode alanlarından kontrol edin. Aynı referenceCode ile ikinci deneme "Aynı referans kodu ile birden fazla deneme yapılmıştır." hatası verir.

UpdateDeliveryDate

Teslimat bazlı valör (valorCalculationType = "D") profiliyle çalışan satıcı işlemleri için teslim tarihini bildirir; bildirilmeden satıcıya ödeme yapılmaz.

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/update-delivery

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/transaction/update-delivery

İstek — JSON

{
  "apiSecretKey": "sx_value",
  "sellerTransactionList": [
    { "refCode": "IKSIRPF471619", "deliveryDate": "18.12.2025", "sellerExternalId": "SELLER_001" },
    { "refCode": "IKSIRPF471619", "deliveryDate": "18.12.2025", "sellerExternalId": "SELLER_002" }
  ]
}

Kurallar: deliveryDate her işlem için yalnızca 1 kez girilebilir ve sonradan değiştirilemez; her zaman güncellemenin yapıldığı günün tarihi olmalıdır (dd.MM.yyyy). Sepette birden çok satıcı varsa her satıcının teslimatı ayrı liste elemanı olarak bildirilir. Güncellenemeyen işlemlerin referansları yanıtın message alanında döner.

Bu Bölümde Pazaryeri Entegrasyonu

Bu sayfa yardımcı oldu mu?

Son güncelleme: 5 Eylül 2026