Ö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

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
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 === '00' || responseCode === '0000') {
    // Siparişi onayla
    updateOrderStatus(trxCode, 'PAID');
  } else {
    // Hata durumu
    updateOrderStatus(trxCode, 'FAILED');
  }

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

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"
}

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"
}

Ö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ı