Ö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

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 Pay N Kolay’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ı

İ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	Pay N Kolay 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 Pay N Kolay
    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
  const calculatedHash = calculateCallbackHash({
    timestamp,
    referenceCode,
    trxCode,
    authAmount,
    responseCode
  }, apiSecretKey);

  if (calculatedHash !== hash) {
    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"
}

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 Pay N Kolay’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
    }
  ]
}

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();

      // 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:

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