Payment Operations

Payment Operations Overview

With the marketplace payment system, you can accept card payments from end users and distribute these payments to sellers and the marketplace according to their commissions.

On this page you will learn about the following operations:

• Creating payments (3D and non-3D)
• Querying payment status
• Fetching stored card list
• Fetching installment information
• Updating commission

Withholding Tax Reminder

Withholding Tax Obligation

Applying 1% withholding tax is mandatory in marketplace transactions. You must calculate the withholding tax amount over the net sales amount excluding VAT and taxes, and report it in the withholdingTax field.

Calculation:

Product Price: 100 TL
Excluding VAT: 80 TL
Withholding Tax: 80 TL × 0.01 = 0.8 TL

---

1. CreatePayment

Initiates a new payment transaction. Used for both 3D Secure and non-3D transactions.

Endpoint

TEST:

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

PROD:

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

Request Parameters

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

Parameter Details

Basic Parameters

Parameter	Type	Required	Description
apiKey	String	✅	Key generated with hash calculation
apiSecretKey	String	✅	SX value
trxCurrency	String	✅	Currency code (TRY, USD, EUR)
trxAmount	BigDecimal	✅	Total transaction amount
trxCode	String	✅	Transaction tracking code (your own reference)
trxType	String	✅	Transaction type: SALES
callbackUrl	String	✅	URL where 3D result will be posted
marketplaceCode	String	✅	Marketplace code

Card Information (bankCard)

Parameter	Type	Required	Description
cardHolder	String	✅*	Name on card (Optional for stored card)
cardNumber	String	✅*	Card number (Optional for stored card)
cvv	String	✅*	CVV code (Optional for stored card)
expiryMonth	String	✅*	Expiry month (Optional for stored card)
expiryYear	String	✅*	Expiry year (Optional for stored card)
isThreeD	Boolean	✅	Use 3D Secure?
registerCard	Boolean	✅	Store card? (Only for 3D transactions)

Installment Information

Parameter	Type	Required	Description
installment	Integer	✅	Number of installments (1 = single payment)
isFetchInstallments	Boolean	✅	Fetch installment info from Pay N Kolay?
encodedValue	String	❌	Encoded value from FetchPaymentInstallments

Seller List (sellerList)

Parameter	Type	Required	Description
sellerExternalId	String	✅	Seller’s external ID
trxAmount	BigDecimal	✅	Transaction amount for seller
commissionRate	BigDecimal	❌	Custom commission rate (outside profile)
commissionAmount	BigDecimal	❌	Calculated commission amount
mpCost	BigDecimal	❌	Transaction fee
withholdingTax	BigDecimal	❌	Withholding tax amount
sellerDiscountAmount	BigDecimal	❌	Seller discount amount

Commission Rules

• commissionRate and commissionAmount cannot be sent at the same time
• If custom commission will not be applied, send both as null
• If you only send commissionRate, amount is automatically calculated
• If you only send commissionAmount, rate is not calculated

Discounts and Fees

Parameter	Type	Required	Description
shippingCost	BigDecimal	❌	Shipping fee
otherAmount	BigDecimal	❌	Other fees
mpDiscountAmount	BigDecimal	❌	Marketplace discount amount
totalDiscountAmount	BigDecimal	❌	Total discount amount

Customer Card Information (customerCardInfo)

Parameter	Type	Required	Description
mpCustomerKey	String	✅*	Customer identifier (ID/Mobile/Passport) - Required for card storage
cardAlias	String	❌	Card alias (for storage)
cardTranId	String	❌	Stored card ID (for payment with stored card)
cardToken	String	❌	Stored card token (for payment with stored card)

Response

Successful Response

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

Response Parameters

Parameter	Type	Description
refCode	String	Pay N Kolay reference code
trxCode	String	Your transaction code
form	String	Base64 encoded HTML form (filled in 3D transactions)

3D Secure Transaction Flow

sequenceDiagram
    participant Client as Customer Browser
    participant Your as Your Server
    participant PNK as Pay N Kolay
    participant Bank as Bank 3D

    Client->>Your: Submit Payment Form
    Your->>PNK: CreatePayment (isThreeD=true)
    PNK->>Your: form (Base64 HTML)
    Your->>Your: Base64 Decode
    Your->>Client: HTML Form Render
    Client->>Bank: 3D Verification
    Bank->>Client: SMS/OTP
    Client->>Bank: Enter Code
    Bank->>Your: POST to callbackUrl
    Your->>Your: Validate Hash
    Your->>Client: Result Page

3D Form Processing

// Decode the form in the response
const response = await createPayment(paymentData);

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

  // Show HTML to customer
  res.send(htmlForm);
}

Callback Handling

When the 3D transaction is completed, the following data will be POSTed to your callbackUrl:

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;

  // Validate hash
  const calculatedHash = calculateCallbackHash({
    timestamp,
    referenceCode,
    trxCode,
    authAmount,
    responseCode
  }, apiSecretKey);

  if (calculatedHash !== hash) {
    return res.status(400).send('Invalid hash');
  }

  // Successful payment
  if (responseCode === '00' || responseCode === '0000') {
    // Confirm order
    updateOrderStatus(trxCode, 'PAID');
  } else {
    // Error status
    updateOrderStatus(trxCode, 'FAILED');
  }

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

---

2. GetPaymentStatus

Queries the status of a payment transaction.

Endpoint

TEST:

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

PROD:

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

Request

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

Information

It is sufficient to send at least one of refCode or trxCode.

Response

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

Status Codes

Code	Description
SUCCESS	Successful transaction
PENDING	Transaction in progress
FAILED	Failed transaction
CANCELLED	Cancelled
REFUNDED	Refunded

---

3. GetStoredCardList

Lists stored cards belonging to a customer.

Endpoint

TEST:

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

PROD:

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

Request

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

Response

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

Payment with Stored Card

// First, fetch stored cards
const cards = await getStoredCardList({
  mpCode: 'MP12345',
  apiSecretKey: 'sx',
  mpCustomerKey: '12345678901',
  apiKey: calculateApiKey()
});

// Show cards to user, let them choose
const selectedCard = cards.data.storedCardList[0];

// Payment with stored card
await createPayment({
  // ... other parameters
  bankCard: {
    isThreeD: true,
    registerCard: false
    // Card details are NOT SENT
  },
  customerCardInfo: {
    mpCustomerKey: '12345678901',
    cardTranId: selectedCard.cardTranId,  // OR
    cardToken: selectedCard.cardToken
  }
});

---

4. FetchPaymentInstallments

Fetches installment options from Pay N Kolay.

Endpoint

TEST:

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

PROD:

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

Request

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

Parameter	Type	Required	Description
mpCode	String	✅	Marketplace code
apiSecretKey	String	✅	SX value
cardNumber	String	✅	First 6-8 digits of card number or full number
amount	BigDecimal	✅	Transaction amount
isCardValid	Boolean	❌	If true, card validity is checked

Response

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

Installment Selection and Payment

// 1. Fetch installment options
const installments = await fetchPaymentInstallments({
  mpCode: 'MP12345',
  apiSecretKey: 'sx',
  cardNumber: cardNumber.substring(0, 8),
  amount: 1000.00
});

// 2. Show installment options to user
installments.data.paymentInstallments.forEach(inst => {
  console.log(`${inst.installment} Installments: ${inst.installmentAmount} TL`);
});

// 3. User made a selection (e.g., 2 installments)
const selectedInstallment = installments.data.paymentInstallments[1];

// 4. Create payment
await createPayment({
  // ... other parameters
  installment: selectedInstallment.installment,
  isFetchInstallments: true,
  encodedValue: selectedInstallment.encodedValue
});

---

5. UpdatePaymentCommission

Updates the commission information of a payment transaction. Can only be used within the transaction day.

Endpoint

TEST:

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

PROD:

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

Request

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

Important

• This service can only be used on the same day as the payment transaction
• Does not work the next day
• Don’t forget to update withholding tax information as well

Response

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

Complete Payment Flow Example

class MarketplacePayment {
  async processPayment(orderData) {
    try {
      // 1. Fetch installment options
      const installments = await this.fetchInstallments(
        orderData.cardNumber,
        orderData.amount
      );

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

      // 3. Calculate ApiKey
      const apiKey = this.calculateApiKey();

      // 4. Create payment
      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. Show 3D form
      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% withholding tax
  }
}

Next Steps

After learning about payment operations:

1. Payment Modifications - Cancel and refund operations
2. Masterpass Integration - Alternative payment methods
3. Reporting - Transaction reports