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:

1. CreatePaymentProfile - Create new payment profile
2. GetPaymentProfileById - Query payment profile
3. UpdatePaymentProfile - Update payment profile
4. DeletePaymentProfileById - Delete payment profile
5. 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 Seller Profile",
  "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)

Transaction Date Based Valor Example

{
  "profileExternalId": "IslemValor1",
  "apiSecretKey": "sx",
  "name": "Transaction Calculation 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.

Response

{
  "data": {
    "profileExternalId": "IslemValor1",
    "marketplaceCode": "MP12345",
    "name": "Premium Seller Profile",
    "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 Seller Profile",
    "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": "Updated Premium Profile",
  "mpCommissionRate": 4.50,
  "mpCost": 0.30,
  "paymentDay": null,
  "valorDateCount": 2,
  "valorCalculationType": "T",
  "active": true
}

Important

All parameters must be sent. Send fields you don’t want to update with their current values.

Response

{
  "data": {
    "profileExternalId": "IslemValor1",
    "marketplaceCode": "MP12345",
    "name": "Updated Premium Profile",
    "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

You cannot delete profiles assigned to active sellers. You need to move sellers to another profile first.

---

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 Seller Profile",
      "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": "Standard Seller Profile",
      "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

// Profile for premium sellers
await createPaymentProfile({
  profileExternalId: "PREMIUM_PROFILE",
  name: "Premium Seller",
  mpCommissionRate: 3.00,  // 3% commission
  mpCost: 0.00,
  valorDateCount: 1,        // Payment after 1 day
  valorCalculationType: "T"
});

// Profile for standard sellers
await createPaymentProfile({
  profileExternalId: "STANDARD_PROFILE",
  name: "Standard Seller",
  mpCommissionRate: 5.00,  // 5% commission
  mpCost: 0.50,            // 0.50 TL per transaction
  valorDateCount: 3,        // Payment after 3 days
  valorCalculationType: "T"
});

// Profile for new sellers
await createPaymentProfile({
  profileExternalId: "NEW_SELLER_PROFILE",
  name: "New Seller",
  mpCommissionRate: 8.00,  // 8% commission
  mpCost: 1.00,
  valorDateCount: 7,        // Payment after 7 days
  valorCalculationType: "T"
});

Scenario 2: Weekly Payment Profile

// Profile with payment every Monday
await createPaymentProfile({
  profileExternalId: "WEEKLY_MONDAY",
  name: "Weekly Monday Payment",
  mpCommissionRate: 5.00,
  mpCost: 0.00,
  paymentDay: 1,            // 1 = Monday
  valorDateCount: 7,
  valorCalculationType: "W" // Weekly
});

Scenario 3: Delivery Date Based Payment

// Payment 2 days after cargo delivery
await createPaymentProfile({
  profileExternalId: "DELIVERY_BASED",
  name: "Post-Delivery Payment",
  mpCommissionRate: 4.00,
  mpCost: 0.00,
  paymentDay: null,
  valorDateCount: 2,        // 2 days after delivery
  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;
  }
}

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

// Create profile
const newProfile = await manager.createProfile({
  profileExternalId: "PROFILE_001",
  name: "Test Profile",
  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