Panel Giriş Başvurun
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

ParametreTipZorunluAçıklama
apiKeyString✅Hash ile üretilen anahtar — bkz. Hash Hesaplama
apiSecretKeyString✅SX değeri
trxCurrencyString✅Para birimi (TRY, USD, EUR)
trxAmountBigDecimal✅Toplam işlem tutarı
trxCodeString✅İşlem takip kodu (kendi referansınız)
trxTypeString✅İşlem tipi: SALES
callbackUrlString✅3D sonucunun POST edileceği URL; autoComplete=false ise tamamlamayı yapacak kendi servisiniz
marketplaceCodeString✅Pazaryeri kodu

Kart Bilgileri — bankCard

ParametreTipZorunluAçıklama
cardHolderString✅*Kart üzerindeki isim (saklı kartta opsiyonel)
cardNumberString✅*Kart numarası (saklı kartta opsiyonel)
cvvString✅*CVV (saklı kartta opsiyonel)
expiryMonth / expiryYearString✅*Son kullanma ay/yıl (saklı kartta opsiyonel)
isThreeDBoolean✅3D Secure kullanılsın mı?
registerCardBoolean✅Kart saklansın mı? (yalnızca 3D'li işlemlerde)

Taksit Bilgileri

ParametreTipZorunluAçıklama
installmentInteger✅Taksit sayısı (1 = tek çekim)
isFetchInstallmentsBoolean✅Taksit bilgisi Paynkolay'dan mı çekilecek?
encodedValueString❌FetchPaymentInstallments'tan dönen encoded değer

Satıcı Listesi — sellerList

ParametreTipZorunluAçıklama
sellerExternalIdString✅Satıcının external ID'si
trxAmountBigDecimal✅Satıcıya ait işlem tutarı
commissionRateBigDecimal❌Özel komisyon oranı (profil dışında)
commissionAmountBigDecimal❌Hesaplanmış komisyon tutarı
mpCostBigDecimal❌İşlem ücreti
withholdingTaxBigDecimal❌Stopaj tutarı
sellerDiscountAmountBigDecimal❌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ı

ParametreTipZorunluAçıklama
shippingCost / otherAmountBigDecimal❌Kargo ve diğer ücretler
mpDiscountAmount / totalDiscountAmountBigDecimal❌Pazaryeri ve toplam indirim tutarları
customerCardInfo.mpCustomerKeyString✅*Müşteri kimliği (TCKN/cep/pasaport) — kart saklama için zorunlu
customerCardInfo.cardAliasString❌Kart takma adı (saklama için)
customerCardInfo.cardTranId / cardTokenString❌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ışı

MüşteriSunucunuz’PaynkolayBanka (3D)Ödeme formu1POST /payment/createisThreeD=true · apiKey2refCode + Base64 form3Formu decode edip göster4SMS / OTP onayı5callbackUrl'e POST6Callback hash doğrula7Sonuç sayfası8
  1. 1CreatePayment gönderinisThreeD=true ile isteği yapın; yanıtta Base64 form döner.
  2. 2Formu render edinBase64'ü çözüp HTML'i müşterinin tarayıcısına basın.
  3. 3Banka doğrulamasıMüşteri banka 3D ekranında SMS/OTP kodunu girer.
  4. 4Callback alınBanka sonucu callbackUrl adresinize POST eder.
  5. 5Hash'i doğrulayınGelen veriyi callback hash formülüyle doğrulayın.
  6. 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.

DurumAçıklama
SUCCESSBaşarılı işlem
PENDINGİşlem devam ediyor
FAILEDBaş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
}
ParametreTipZorunluAçıklama
mpCodeString✅Pazaryeri kodu
apiSecretKeyString✅SX değeri
cardNumberString✅Kart numarasının ilk 6-8 hanesi veya tamamı
amountBigDecimal✅İşlem tutarı
isCardValidBoolean❌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.

autoCompleteDavranış
trueVarsayı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.

  1. 1CreatePaymentcallbackUrl olarak kendi servisinizi verin.
  2. 2Callback POSTForm sonucu REFERENCE_CODE dahil servisinize POST edilir.
  3. 3Kayıt oluşturunİşlemi kendi veritabanınıza yazın.
  4. 4ValidasyonKendi iş mantığı kontrollerinizi çalıştırın.
  5. 5CompletePaymentExternalreferenceCode + satış SX ile tamamlayın.
  6. 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"
}
ParametreTipZorunluAçıklama
referenceCodeString✅Callback'te REFERENCE_CODE alanında gelen Base64 değer — değiştirilmeden gönderilir, tek kullanımlıktır
apiSecretKeyString✅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.

Son güncelleme: 5 Eylül 2026

v2 · Versiyonlar