Payment Profile Management

What is a Payment Profile? #

A Payment Profile is a configuration set that includes commission rates, transaction fees, payment days, and valor calculation methods that the marketplace will apply to its sellers.

The marketplace can work with different payment profiles for different sellers. For example:

2% commission for premium sellers
5% commission for standard sellers
7% commission for new sellers

Valor Calculation Types #

The valor calculation type defined in the payment profile determines when the payment will be made to the seller.

Code	Type	Description
W	WEEKLY	Weekly Valor Calculation - Payment is made on a specific day of the week
H	HALF_MONTHLY	Half-Monthly Valor Calculation - Payment is made twice a month
M	MONTHLY	Monthly Valor Calculation - Payment is made on a specific day of the month
T	TRANSACTION	Transaction Date Based Valor - Payment is made N days after transaction date
D	DELIVERY	Delivery Date Based Valor - Payment is made N days after delivery date

Payment Profile Services #

The following services are used for payment profile management:

CreatePaymentProfile - Create new payment profile
GetPaymentProfileById - Query payment profile
UpdatePaymentProfile - Update payment profile
DeletePaymentProfileById - Delete payment profile
GetAllPaymentProfileByApiSecretKey - List all profiles

1. CreatePaymentProfile #

Creates a new payment profile.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/paymentprofile

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/paymentprofile

Request Parameters #

{
  "profileExternalId": "IslemValor1",
  "apiSecretKey": "sx_value_here",
  "name": "Premium Satıcı Profili",
  "mpCommissionRate": 5.00,
  "mpCost": 0.50,
  "paymentDay": null,
  "valorDateCount": 1,
  "valorCalculationType": "T",
  "active": true
}

Parameter Details #

Parameter	Type	Required	Description
profileExternalId	String	✅	Unique external ID - ID in your own system
apiSecretKey	String	✅	SX value belonging to the marketplace
name	String	❌	Profile name (e.g., "Premium Profile")
mpCommissionRate	BigDecimal	✅	Marketplace commission rate (%)
mpCost	BigDecimal	❌	Fixed fee per transaction (TL)
paymentDay	Integer	✅*	Payment day (1-7, monday=1). Required for Weekly/Monthly
valorDateCount	Integer	✅	Waiting period for money transfer (days)
valorCalculationType	String	✅	Valor calculation type (W, H, M, T, D)
active	Boolean	❌	Is profile active? (default: true)

{ "profileExternalId": "IslemValor1", "apiSecretKey": "sx", "name": "İşlem Hesaplama 1", "mpCommissionRate": 5.00, "mpCost": 0.00, "paymentDay": null, "valorDateCount": 1, "valorCalculationType": "T", "active": true }
In this example, payment is made 1 day after the transaction. d-flex align-items-start mb-4" role="alert">

info

Response #

{
  "data": {
    "profileExternalId": "IslemValor1",
    "marketplaceCode": "MP12345",
    "name": "Premium Satıcı Profili",
    "mpCommissionRate": 5.00,
    "mpCost": 0.50,
    "paymentDay": "per",
    "valorDateCount": 1,
    "active": true,
    "createDate": "2025-01-15T10:30:00Z",
    "updateDate": "2025-01-15T10:30:00Z"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

2. GetPaymentProfileById #

Retrieves details of a specific payment profile.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/paymentprofile/get

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/paymentprofile/get

Request #

{
  "profileExternalId": "IslemValor1"
}

Response #

{
  "data": {
    "profileExternalId": "IslemValor1",
    "marketplaceCode": "MP12345",
    "name": "Premium Satıcı Profili",
    "mpCommissionRate": 5.00,
    "mpCost": 0.50,
    "paymentDay": "per",
    "valorDateCount": 1,
    "active": true,
    "createDate": "2025-01-15T10:30:00Z",
    "updateDate": "2025-01-15T10:30:00Z"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

3. UpdatePaymentProfile #

Updates an existing payment profile.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/paymentprofile/update

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/paymentprofile/update

Request #

{
  "profileExternalId": "IslemValor1",
  "apiSecretKey": "sx_value_here",
  "name": "Güncellenmiş Premium Profil",
  "mpCommissionRate": 4.50,
  "mpCost": 0.30,
  "paymentDay": null,
  "valorDateCount": 2,
  "valorCalculationType": "T",
  "active": true
}

warning

Response #

{
  "data": {
    "profileExternalId": "IslemValor1",
    "marketplaceCode": "MP12345",
    "name": "Güncellenmiş Premium Profil",
    "mpCommissionRate": 4.50,
    "mpCost": 0.30,
    "paymentDay": "per",
    "valorDateCount": 2,
    "active": true,
    "createDate": "2025-01-15T10:30:00Z",
    "updateDate": "2025-01-16T14:20:00Z"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

4. DeletePaymentProfileById #

Deletes a payment profile.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/paymentprofile/delete

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/paymentprofile/delete

Request #

{
  "profileExternalId": "IslemValor1"
}

Response #

{
  "data": null,
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

warning

5. GetAllPaymentProfileByApiSecretKey #

Lists all payment profiles belonging to the marketplace.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/paymentprofile/list

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/paymentprofile/list

Request #

{
  "apiSecretKey": "sx_value_here",
  "active": true
}

Parameter	Type	Required	Description
apiSecretKey	String	✅	SX value belonging to the marketplace
active	Boolean	❌	true=only active, false=only inactive, null=all

Response #

{
  "data": [
    {
      "profileExternalId": "Premium1",
      "marketplaceCode": "MP12345",
      "name": "Premium Satıcı Profili",
      "mpCommissionRate": 5.00,
      "mpCost": 0.50,
      "paymentDay": "per",
      "valorDateCount": 1,
      "active": true,
      "createDate": "2025-01-15T10:30:00Z",
      "updateDate": "2025-01-15T10:30:00Z"
    },
    {
      "profileExternalId": "Standard1",
      "marketplaceCode": "MP12345",
      "name": "Standart Satıcı Profili",
      "mpCommissionRate": 7.00,
      "mpCost": 1.00,
      "paymentDay": "per",
      "valorDateCount": 3,
      "active": true,
      "createDate": "2025-01-10T09:15:00Z",
      "updateDate": "2025-01-10T09:15:00Z"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Use Case Scenarios #

Scenario 1: Different Profiles for Different Categories #

// Premium satıcılar için profil
await createPaymentProfile({
  profileExternalId: "PREMIUM_PROFILE",
  name: "Premium Satıcı",
  mpCommissionRate: 3.00,  // %3 komisyon
  mpCost: 0.00,
  valorDateCount: 1,        // 1 gün sonra ödeme
  valorCalculationType: "T"
});

// Standart satıcılar için profil
await createPaymentProfile({
  profileExternalId: "STANDARD_PROFILE",
  name: "Standart Satıcı",
  mpCommissionRate: 5.00,  // %5 komisyon
  mpCost: 0.50,            // İşlem başına 0.50 TL
  valorDateCount: 3,        // 3 gün sonra ödeme
  valorCalculationType: "T"
});

// Yeni satıcılar için profil
await createPaymentProfile({
  profileExternalId: "NEW_SELLER_PROFILE",
  name: "Yeni Satıcı",
  mpCommissionRate: 8.00,  // %8 komisyon
  mpCost: 1.00,
  valorDateCount: 7,        // 7 gün sonra ödeme
  valorCalculationType: "T"
});

Scenario 2: Weekly Payment Profile #

// Her pazartesi ödeme yapılan profil
await createPaymentProfile({
  profileExternalId: "WEEKLY_MONDAY",
  name: "Haftalık Pazartesi Ödemeli",
  mpCommissionRate: 5.00,
  mpCost: 0.00,
  paymentDay: 1,            // 1 = Pazartesi
  valorDateCount: 7,
  valorCalculationType: "W" // Weekly
});

Scenario 3: Delivery Date Based Payment #

// Kargo teslim edildikten 2 gün sonra ödeme
await createPaymentProfile({
  profileExternalId: "DELIVERY_BASED",
  name: "Teslimat Sonrası Ödeme",
  mpCommissionRate: 4.00,
  mpCost: 0.00,
  paymentDay: null,
  valorDateCount: 2,        // Teslimat sonrası 2 gün
  valorCalculationType: "D" // Delivery based
});

Complete Code Example #

const axios = require('axios');

class PaymentProfileManager {
  constructor(apiSecretKey, merchantSecretKey, baseURL) {
    this.apiSecretKey = apiSecretKey;
    this.merchantSecretKey = merchantSecretKey;
    this.baseURL = baseURL;
  }

  async createProfile(profileData) {
    const response = await axios.post(
      `${this.baseURL}/paymentprofile`,
      {
        ...profileData,
        apiSecretKey: this.apiSecretKey
      }
    );
    return response.data;
  }

  async getProfile(profileExternalId) {
    const response = await axios.post(
      `${this.baseURL}/paymentprofile/get`,
      { profileExternalId }
    );
    return response.data;
  }

  async updateProfile(profileData) {
    const response = await axios.post(
      `${this.baseURL}/paymentprofile/update`,
      {
        ...profileData,
        apiSecretKey: this.apiSecretKey
      }
    );
    return response.data;
  }

  async deleteProfile(profileExternalId) {
    const response = await axios.post(
      `${this.baseURL}/paymentprofile/delete`,
      { profileExternalId }
    );
    return response.data;
  }

  async listProfiles(activeOnly = null) {
    const response = await axios.post(
      `${this.baseURL}/paymentprofile/list`,
      {
        apiSecretKey: this.apiSecretKey,
        active: activeOnly
      }
    );
    return response.data;
  }
}

// Kullanım
const manager = new PaymentProfileManager(
  process.env.API_SECRET_KEY,
  process.env.MERCHANT_SECRET_KEY,
  'https://apitest.paynkolay.com.tr/marketplace/v1'
);

// Profil oluştur
const newProfile = await manager.createProfile({
  profileExternalId: "PROFILE_001",
  name: "Test Profili",
  mpCommissionRate: 5.00,
  mpCost: 0.50,
  valorDateCount: 2,
  valorCalculationType: "T",
  active: true
});

Next Steps #

After creating payment profiles:

1. Seller Management - Add your sellers and assign profiles
2. Payment Operations - Start accepting payments
3. Reporting - Get profile-based reports