Ödeme İşlemleri

Ödeme İşlemleri Genel Bakış #

Pazaryeri ödeme sistemi ile son kullanıcılardan kart ile ödeme alabilir, bu ödemeleri satıcılara ve pazaryerine komisyonlarına göre dağıtabilirsiniz.

Bu sayfada aşağıdaki işlemleri öğreneceksiniz:

Ödeme oluşturma (3D ve 3D'siz)
Ödeme durumu sorgulama
Saklı kart listesi çekme
Taksit bilgilerini çekme
Komisyon güncelleme
Harici ödeme tamamlama (autoComplete=false akışı)
Teslimat tarihi bildirme (teslimat bazlı valör)

Stopaj Uygulaması Hatırlatma #

Stopaj Yükümlülüğü
Pazaryeri işlemlerinde %1 stopaj uygulanması zorunludur. Stopaj tutarını KDV ve vergiler hariç net satış tutarı üzerinden hesaplayıp withholdingTax alanında bildirmelisiniz.

Hesaplama:

Ürün Bedeli: 100 TL
KDV Hariç: 80 TL
Stopaj: 80 TL × 0.01 = 0.8 TL

1. CreatePayment #

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

Endpoint #

TEST:

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

PROD:

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

İstek Parametreleri #

{
  "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",
      "commissionRate": null,
      "commissionAmount": null,
      "mpCost": null,
      "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
  }
}

Parametre Detayları #

Temel Parametreler #

Parametre	Tip	Zorunlu	Açıklama
apiKey	String	✅	Hash hesaplama ile oluşturulan anahtar
apiSecretKey	String	✅	SX değeri
trxCurrency	String	✅	Para birimi kodu (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 sonucu post edilecek URL. `autoComplete=false` ise ödemeyi tamamlayacak kendi servisinizin adresi (bkz. CompletePaymentExternal)
marketplaceCode	String	✅	Pazaryeri kodu

Kart Bilgileri (bankCard) #

Parametre	Tip	Zorunlu	Açıklama
cardHolder	String	✅*	Kart üzerindeki isim (Saklı kart için opsiyonel)
cardNumber	String	✅*	Kart numarası (Saklı kart için opsiyonel)
cvv	String	✅*	CVV kodu (Saklı kart için opsiyonel)
expiryMonth	String	✅*	Son kullanma ayı (Saklı kart için opsiyonel)
expiryYear	String	✅*	Son kullanma yılı (Saklı kart için opsiyonel)
isThreeD	Boolean	✅	3D Secure kullanılsın mı?
registerCard	Boolean	✅	Kart saklanacak mı? (Sadece 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 çekilecek mi?
encodedValue	String	❌	FetchPaymentInstallments'dan gelen 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
Sadece commissionRate gönderirseniz tutar otomatik hesaplanır
Sadece commissionAmount gönderirseniz oran hesaplanmaz

İndirim ve Ücretler #

Parametre	Tip	Zorunlu	Açıklama
shippingCost	BigDecimal	❌	Kargo ücreti
otherAmount	BigDecimal	❌	Diğer ücretler
mpDiscountAmount	BigDecimal	❌	Pazaryeri indirim tutarı
totalDiscountAmount	BigDecimal	❌	Toplam indirim tutarı

Müşteri Kart Bilgileri (customerCardInfo) #

Parametre	Tip	Zorunlu	Açıklama
mpCustomerKey	String	✅*	Müşteri kimliği (TCKN/Cep/Pasaport) - Kart saklama için zorunlu
cardAlias	String	❌	Kart takma adı (saklama için)
cardTranId	String	❌	Saklı kart ID'si (saklı kart ile ödeme için)
cardToken	String	❌	Saklı kart token'ı (saklı kart ile ödeme için)

Yanıt #

Başarılı Yanıt #

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

Yanıt Parametreleri #

Parametre	Tip	Açıklama
refCode	String	Paynkolay referans kodu
trxCode	String	Sizin gönderdiğiniz işlem kodu
form	String	Base64 encoded HTML form (3D işlemlerde dolu)

3D Secure İşlem Akışı #

sequenceDiagram
    participant Client as Müşteri Tarayıcı
    participant Your as Sizin Sunucu
    participant PNK as Paynkolay
    participant Bank as Banka 3D

    Client->>Your: Ödeme Formu Gönder
    Your->>PNK: CreatePayment (isThreeD=true)
    PNK->>Your: form (Base64 HTML)
    Your->>Your: Base64 Decode
    Your->>Client: HTML Form Render
    Client->>Bank: 3D Doğrulama
    Bank->>Client: SMS/OTP
    Client->>Bank: Kod Gir
    Bank->>Your: callbackUrl'e POST
    Your->>Your: Hash Doğrula
    Your->>Client: Sonuç Sayfası

3D Form İşleme #

// Yanıttaki form'u decode et
const response = await createPayment(paymentData);

if (response.success && response.data.form) {
  // Base64 decode
  const htmlForm = Buffer.from(response.data.form, 'base64').toString('utf-8');

  // HTML'i müşteriye göster
  res.send(htmlForm);
}

Callback Handling #

3D işlem tamamlandığında callbackUrl adresinize aşağıdaki veriler POST edilir:

app.post('/payment-callback', (req, res) => {
  const {
    trxCode,
    trxAmount,
    authAmount,
    commissionRate,
    authCode,
    bankMessage,
    installment,
    responseMessage,
    referenceCode,
    currencyCode,
    hash,
    responseCode,
    commissionAmount,
    timestamp,
    issuerBankCode,
    installmentFeeRate,
    installmentFeeAmount,
    cardType,
    paymentSystem
  } = req.body;

  // Hash doğrula
  // verifyCallbackHash fonksiyonu detayları için: Hash Hesaplama sayfası
  if (!verifyCallbackHash(req.body, apiSecretKey)) {
    return res.status(400).send('Invalid hash');
  }

  // Başarılı ödeme
  if (responseCode === '200' || responseCode === '2') {
    // Siparişi onayla
    updateOrderStatus(trxCode, 'PAID');
  } else {
    // Hata durumu
    updateOrderStatus(trxCode, 'FAILED');
  }

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

autoComplete
Pazaryeri üye işyeri tanımınızdaki autoComplete ayarı false ise, callbackUrl adresinize gelen POST ödemenin tamamlandığı anlamına gelmez; işlem beklemede kalır. Kendi validasyon ve kayıt işlemlerinizi çalıştırdıktan sonra CompletePaymentExternal servisini çağırarak ödemeyi tamamlamanız gerekir.

2. GetPaymentStatus #

Ödeme işleminin durumunu sorgular.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

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

Yanıt #

{
  "data": [
    {
      "trxStatus": "SUCCESS",
      "trxCode": "ORDER_12345",
      "refCode": "REF123456789",
      "trxType": "SALES",
      "trxAmount": 150.00,
      "trxCurrency": "TRY"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Durum Kodları #

Kod	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ış

3. GetStoredCardList #

Müşteriye ait saklı kartları listeler.

Endpoint #

TEST:

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

PROD:

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

İstek #

{
  "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)). Detay için ApiKey Hesaplama sayfasına bakın.

Yanıt #

{
  "data": {
    "cardTotalCount": 2,
    "storedCardList": [
      {
        "cardToken": "token_abc123",
        "cardTranId": "tran_xyz789",
        "cardMaskedPan": "454671******7894",
        "cardIssuer": "Akbank",
        "cardType": "Credit",
        "cardBrand": "VISA",
        "cardAlias": "İş Kartım"
      },
      {
        "cardToken": "token_def456",
        "cardTranId": "tran_uvw321",
        "cardMaskedPan": "540061******1234",
        "cardIssuer": "İş Bankası",
        "cardType": "Debit",
        "cardBrand": "MASTERCARD",
        "cardAlias": "Kişisel Kart"
      }
    ]
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Saklı Kart ile Ödeme #

// Önce saklı kartları çek
const cards = await getStoredCardList({
  mpCode: 'MP12345',
  apiSecretKey: 'sx',
  mpCustomerKey: '12345678901',
  apiKey: calculateApiKey()
});

// Kullanıcıya kartları göster, seçim yaptır
const selectedCard = cards.data.storedCardList[0];

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

4. FetchPaymentInstallments #

Taksit seçeneklerini Paynkolay'dan çeker.

Endpoint #

TEST:

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

PROD:

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

İstek #

{
  "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ıt #

{
  "data": {
    "cardScope": "WORLD",
    "paymentInstallments": [
      {
        "installment": 1,
        "installmentAmount": 1000.00,
        "cardTrxType": "CREDIT",
        "bankCode": "0046",
        "commissionAmount": 0.00,
        "commissionRate": 0.00,
        "trxAmount": 1000.00,
        "currencyCode": "TRY",
        "currencyNumber": "949",
        "program": "WORLD",
        "cardBankNo": "0046",
        "plusInstallment": 0,
        "encodedValue": "encoded_value_1"
      },
      {
        "installment": 2,
        "installmentAmount": 510.00,
        "cardTrxType": "CREDIT",
        "bankCode": "0046",
        "commissionAmount": 20.00,
        "commissionRate": 2.00,
        "trxAmount": 1020.00,
        "currencyCode": "TRY",
        "currencyNumber": "949",
        "program": "WORLD",
        "cardBankNo": "0046",
        "plusInstallment": 0,
        "encodedValue": "encoded_value_2"
      }
    ]
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Taksit Seçimi ve Ödeme #

// 1. Taksit seçeneklerini çek
const installments = await fetchPaymentInstallments({
  mpCode: 'MP12345',
  apiSecretKey: 'sx',
  cardNumber: cardNumber.substring(0, 8),
  amount: 1000.00
});

// 2. Kullanıcıya taksit seçeneklerini göster
installments.data.paymentInstallments.forEach(inst => {
  console.log(`${inst.installment} Taksit: ${inst.installmentAmount} TL`);
});

// 3. Kullanıcı seçim yaptı (örn: 2 taksit)
const selectedInstallment = installments.data.paymentInstallments[1];

// 4. Ödemeyi oluştur
await createPayment({
  // ... diğer parametreler
  installment: selectedInstallment.installment,
  isFetchInstallments: true,
  encodedValue: selectedInstallment.encodedValue
});

5. UpdatePaymentCommission #

Ödeme işleminin komisyon bilgilerini günceller. Sadece işlem günü içinde kullanılabilir.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Önemli

Bu servis sadece ödeme işlemi ile aynı gün kullanılabilir
Ertesi gün çalışmaz
Stopaj bilgisini de güncellemeyi unutmayın

Yanıt #

{
  "data": [
    {
      "mpCode": "MP12345",
      "refCode": "REF123456789",
      "trxCode": "ORDER_12345",
      "trxCurrency": "TRY",
      "trxAmount": 100.00,
      "trxStatus": "SUCCESS",
      "sellerTransactionList": [
        {
          "sellerName": "Ahmet Yılmaz",
          "trxAmount": 100.00,
          "trxCurrency": "TRY",
          "trxStatus": "SUCCESS",
          "pfCommissionRate": 2.50,
          "pfCommissionAmount": 2.50,
          "mpCommissionRate": 5.00,
          "mpCommissionAmount": 5.00,
          "mpCost": 0.50,
          "trxType": "SALES",
          "withholdingTax": 0.80
        }
      ]
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

6. CompletePaymentExternal #

Pazaryeri (MPLACE) üzerinden yapılan ödemelerde, üye işyerinin kendi süreçlerini yönetebilmesi için ödeme tamamlama adımını üye işyerine bırakan servistir. autoComplete = false olan pazaryerlerinde ödeme otomatik tamamlanmaz; ödeme formu tamamlandığında callbackUrl adresinize gelen istek önce sizin servisiniz tarafından karşılanır, kendi validasyon ve veritabanı kayıt işlemlerinizi yaptıktan sonra bu servisi çağırarak akışı tamamlarsınız.

autoComplete Nedir? #

autoComplete, pazaryeri üye işyeri tanımınız üzerinde Paynkolay tarafından yapılandırılan bir ayardır:

Değer	Davranış
`true`	Varsayılan davranış. Ödeme, form akışı tamamlandığında otomatik olarak tamamlanır; ek bir çağrı gerekmez.
`false`	Ödeme otomatik tamamlanmaz. Üye işyeri kendi validasyon, DB kaydı ve iş mantığı işlemlerini yaptıktan sonra CompletePaymentExternal çağrısı ile akışı tamamlar.

Bu ayarın açılıp kapatılması üye işyeri bazında yapılır. autoComplete=false olarak çalışmak istiyorsanız Paynkolay entegrasyon ekibi ile iletişime geçin.

İş Akışı #

sequenceDiagram
    participant Client as Müşteri Tarayıcı
    participant MP as Sizin Servisiniz (callbackUrl)
    participant PNK as Paynkolay

    MP->>PNK: 1. CreatePayment (callbackUrl = kendi servisiniz)
    PNK->>Client: Ödeme formu / 3D akışı
    Client->>MP: 2. Form sonucu callbackUrl'e POST edilir (referenceCode dahil)
    MP->>MP: 3. İşlem kaydı oluştur (kendi DB)
    MP->>MP: 4. Validasyon / iş mantığı işlemleri
    MP->>PNK: 5. CompletePaymentExternal (referenceCode + apiSecretKey)
    PNK->>MP: 6. İşlem sonucu döner, akış tamamlanır

Endpoint #

TEST:

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

PROD:

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

Teknik Gereksinimler

Server-to-Server POST isteğidir, Content-Type: application/json ile gönderilir
JWT token gerektirmez; kimlik doğrulama apiSecretKey (satış SX) ile yapılır
Bu servis, tekil üye işyeri (Vpos) tarafındaki CompletePayment servisinden farklıdır ve yalnızca pazaryeri işlemleri için kullanılır

Callback İçeriği
Bu akışta callbackUrl adresinize gelen POST alanları büyük harfli formattadır (REFERENCE_CODE, RESPONSE_CODE, AUTH_CODE…). RESPONSE_CODE=2 ve boş AUTH_CODE, işlemin başlatıldığı ve tamamlama beklediği anlamına gelir; RESPONSE_DATA alanında ödeme tamamlama servisini çağırmanız gerektiği belirtilir.

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
referenceCode	String	✅	Callback formunda servisinize `REFERENCE_CODE` alanında POST edilen değer. Base64 kodlu tam değer, değiştirilmeden gönderilmelidir ve tek kullanımlıktır
apiSecretKey	String	✅	Satış SX değeri

Yanıt #

Başarılı Yanıt #

{
  "success": true,
  "message": null,
  "responseCode": "2",
  "responseMessage": "İşlem Başarılı",
  "trxCode": "ORDER_12345",
  "referenceCode": "IKSIRPF123456",
  "authCode": "S35971",
  "timestamp": "2026-07-27 16:43:47+0300",
  "currencyCode": "949",
  "hash": "I6mMIL2JW1yREC+RW1kos/pJzAN/L8+d5oaMY6Pe9RtuEcnP+NievGxC/R1IYAxG+vhBE4i4i1zyNvzR0pyuHQ==",
  "commissionRate": "1.3000",
  "commissionAmount": "25.9900",
  "installment": "1",
  "trxAmount": "1999.00",
  "authAmount": "1999.00",
  "bankMessage": "Onaylandı",
  "issuerBankCode": "111",
  "installmentFeeRate": "0.00",
  "installmentFeeAmount": "0.00",
  "cardType": "CreditCard",
  "paymentSystem": "V"
}

Yanıt Parametreleri #

Parametre	Tip	Açıklama
success	Boolean	İşlem başarılı mı?
responseCode	String	`2` = başarılı, `0` = hata
responseMessage	String	İşlem sonuç mesajı
message	String	Hata durumunda hata detayı
trxCode	String	Sizin gönderdiğiniz işlem kodu
referenceCode	String	Paynkolay referans kodu
authCode	String	Banka otorizasyon kodu
timestamp	String	İşlem zamanı
currencyCode	String	Para birimi kodu (949 = TRY)
hash	String	İşlem doğrulama hash'i
commissionRate	String	Komisyon oranı
commissionAmount	String	Komisyon tutarı
installment	String	Taksit sayısı
trxAmount	String	İşlem tutarı
authAmount	String	Onaylanan tutar
bankMessage	String	Banka mesajı
issuerBankCode	String	Kartı veren banka kodu
installmentFeeRate	String	Taksit ücret oranı
installmentFeeAmount	String	Taksit ücret tutarı
cardType	String	Kart tipi (CreditCard, DebitCard)
paymentSystem	String	Ödeme sistemi

Hata durumlarında da servis HTTP 200 döner; sonucu success ve responseCode alanlarından kontrol edin. Hata detayı message / responseMessage alanlarında taşınır. referenceCode tek kullanımlıktır: başarılı bir tamamlamadan sonra aynı kodla yapılan ikinci deneme "Aynı referans kodu ile birden fazla deneme yapılmıştır." hatası döner.

Örnek Uygulama #

Aşağıdaki örnek, callbackUrl olarak verdiğiniz servisin callback'ten gelen referenceCode değerini alıp CompletePaymentExternal servisine iletmesini gösterir:

// createPayment isteğinde callbackUrl olarak verdiğiniz endpoint
app.post('/payment-callback', async (req, res) => {
  const referenceCode = req.body.REFERENCE_CODE || req.body.referenceCode;

  if (!referenceCode) {
    return res.status(400).send('referenceCode zorunludur');
  }

  // 1. İşlem kaydı oluştur (kendi DB'niz)
  await saveTransactionRecord(req.body);

  // 2. Validasyon / iş mantığı işlemleri
  // ...

  // 3. Ödemeyi tamamla
  const response = await fetch(
    'https://apitest.paynkolay.com.tr/marketplace/v1/payment/completePaymentExternal',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        referenceCode: referenceCode,
        apiSecretKey: process.env.API_SECRET_KEY
      })
    }
  );

  const result = await response.json();

  if (result.success && result.responseCode === '2') {
    await updateOrderStatus(result.trxCode, 'PAID');
  } else {
    await updateOrderStatus(result.trxCode, 'FAILED');
    console.error('Ödeme tamamlanamadı:', result.message || result.responseMessage);
  }

  res.status(200).send(result.responseMessage);
});

<?php
// createPayment isteğinde callbackUrl olarak verdiğiniz endpoint
$referenceCode = $_POST['REFERENCE_CODE'] ?? $_POST['referenceCode'] ?? '';

if ($referenceCode === '') {
    http_response_code(400);
    exit('referenceCode zorunludur');
}

// 1. İşlem kaydı oluştur (kendi DB'niz)
// 2. Validasyon / iş mantığı işlemleri
// ...

// 3. Ödemeyi tamamla
$ch = curl_init('https://apitest.paynkolay.com.tr/marketplace/v1/payment/completePaymentExternal');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'referenceCode' => $referenceCode,
        'apiSecretKey' => getenv('API_SECRET_KEY'),
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['success'] ?? false) && ($result['responseCode'] ?? '') === '2') {
    // Siparişi onayla
} else {
    // Hata: $result['message'] / $result['responseMessage']
}

7. UpdateDeliveryDate #

Teslimat tarihi bazlı valör (valorCalculationType = "D") profiliyle çalışan satıcıların işlemleri için teslimat tarihini bildirir. Bu profillerde satıcıya ödeme, teslimat tarihi bildirilmeden yapılmaz; valör süresi bildirilen teslim tarihinden itibaren işler. Profil tipleri için Ödeme Profili Yönetimi sayfasına bakın.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
apiSecretKey	String	✅	Satış SX değeri
sellerTransactionList	Array	✅	Teslimatı bildirilecek satıcı işlemleri listesi
sellerTransactionList[].refCode	String	✅	İşleme ait Paynkolay referans kodu
sellerTransactionList[].deliveryDate	String	✅	Teslim tarihi (dd.MM.yyyy formatında)
sellerTransactionList[].sellerExternalId	String	✅	Satıcının external ID'si

Kurallar

deliveryDate her işlem için yalnızca 1 kez girilebilir, sonradan değiştirilemez
deliveryDate her zaman güncellemenin yapıldığı günün tarihi olmalıdır
Sepette birden çok satıcı olabilir; her satıcının teslimatı ayrı bir liste elemanı olarak bildirilir
Teslimat tarihi güncellenemeyen işlemlerin referans numaraları yanıtın message alanında döner

Yanıt #

Başarılı yanıtta success: true döner; teslimat tarihi güncellenemeyen işlemlerin referans numaraları message alanında listelenir. Hatalı isteklerde servis HTTP 400 ile hata mesajı döner:

{
  "success": false,
  "message": "Gönderdiğiniz refCode ve trxCode bilgilerine ait bir ödeme işlemi kaydı bulunamadı.!"
}

Örnek Tam Ödeme Akışı #

class MarketplacePayment {
  async processPayment(orderData) {
    try {
      // 1. Taksit seçeneklerini çek
      const installments = await this.fetchInstallments(
        orderData.cardNumber,
        orderData.amount
      );

      // 2. Stopaj hesapla
      const sellers = orderData.items.map(item => ({
        sellerExternalId: item.sellerId,
        trxAmount: item.price,
        withholdingTax: this.calculateWithholdingTax(item.priceWithoutVAT),
        sellerDiscountAmount: item.sellerDiscount || 0
      }));

      // 3. ApiKey hesapla
      const apiKey = this.calculateApiKey(
        orderData.orderId,
        orderData.amount,
        'TRY',
        'SALES'
      );

      // 4. Ödeme oluştur
      const payment = await this.createPayment({
        apiKey,
        apiSecretKey: this.apiSecretKey,
        bankCard: {
          cardHolder: orderData.cardHolder,
          cardNumber: orderData.cardNumber,
          cvv: orderData.cvv,
          expiryMonth: orderData.expiryMonth,
          expiryYear: orderData.expiryYear,
          isThreeD: true,
          registerCard: orderData.saveCard
        },
        installment: orderData.selectedInstallment,
        trxAmount: orderData.amount,
        trxCode: orderData.orderId,
        trxType: 'SALES',
        trxCurrency: 'TRY',
        callbackUrl: 'https://yoursite.com/payment-callback',
        sellerList: sellers,
        marketplaceCode: this.mpCode,
        customerCardInfo: {
          mpCustomerKey: orderData.customerId
        }
      });

      // 5. 3D form'u göster
      if (payment.data.form) {
        const htmlForm = Buffer.from(
          payment.data.form,
          'base64'
        ).toString('utf-8');
        return { type: '3D_FORM', html: htmlForm };
      }

      return { type: 'SUCCESS', data: payment.data };

    } catch (error) {
      console.error('Payment error:', error);
      throw error;
    }
  }

  calculateWithholdingTax(amountWithoutVAT) {
    return amountWithoutVAT * 0.01; // %1 stopaj
  }
}

Sonraki Adımlar #

Ödeme işlemlerini öğrendikten sonra:

1. Ödeme Değişiklikleri - İptal, iade işlemleri
2. Masterpass Entegrasyonu - Alternatif ödeme yöntemleri
3. Raporlama - İşlem raporları