Seller Management

What is Seller Management? #

With seller management services, you can add, update, query, and delete sub-sellers connected to your marketplace.

Each seller is associated with a payment profile, and commission rates and payment days are determined according to this profile.

Seller Types #

Three types of sellers can be defined in the marketplace system:

Type	Code	Description	Identity
Individual	1	Individual sellers	11-digit TCKN
Sole Proprietorship	2	Single-person companies	11-digit TCKN
Corporation	3	Limited, Joint-stock companies	10-digit VKN

Seller Services #

CreateSeller - Create new seller
GetSellerById - Query seller information
UpdateSeller - Update seller information
DeleteSellerById - Delete seller
GetAllSellerByApiSecretKey - List all sellers

1. CreateSeller #

Creates a new seller.

Endpoint #

TEST:

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

PROD:

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

Request Parameters #

{
  "sellerExternalId": "SELLER_001",
  "nameSurname": "Ahmet Yılmaz",
  "sellerType": 1,
  "tckn": "12345678901",
  "vkn": null,
  "birthDate": "15.05.1985",
  "taxOffice": "Kadıköy",
  "contactPerson": "Ahmet Yılmaz",
  "email": "ahmet@example.com",
  "phoneNumber": "5551234567",
  "city": "34",
  "address": "Atatürk Cad. No:123 Kadıköy",
  "iban": "TR330006100519786457841326",
  "accountHolder": "Ahmet Yılmaz",
  "apiSecretKey": "sx_value_here",
  "active": true,
  "mpPaymentProfileExternalId": "PREMIUM_PROFILE"
}

Parameter Details #

Parameter	Type	Required	Description
sellerExternalId	String	✅	Unique external ID - Seller ID in your own system
nameSurname	String	✅	Name Surname (Individual/Sole Prop.) or Company Name (Corp.)
sellerType	Integer	✅	1=Individual, 2=Sole Prop., 3=Corporation
tckn	String	✅*	11-digit TCKN (Required for Type 1 and 2)
vkn	String	✅*	10-digit VKN (Required for Type 3)
birthDate	String	❌	Birth date (in dd.MM.yyyy format)
taxOffice	String	❌	Tax office name
contactPerson	String	❌	Contact person name-surname
email	String	❌	Email address
phoneNumber	String	❌	Mobile phone (in 5551234567 format)
city	String	❌	City plate code (e.g., 34, 06, 35)
address	String	❌	Address information
iban	String	✅	IBAN number (must start with TR)
accountHolder	String	❌	Account holder name (must be same as nameSurname)
apiSecretKey	String	✅	SX value belonging to the marketplace
active	Boolean	❌	Is seller active? (default: true)
mpPaymentProfileExternalId	String	✅	ID of the payment profile to be assigned

Example Requests #

Individual Seller #

{
  "sellerExternalId": "GK_001",
  "nameSurname": "Ayşe Demir",
  "sellerType": 1,
  "tckn": "98765432101",
  "birthDate": "20.03.1990",
  "taxOffice": "Beşiktaş",
  "contactPerson": "Ayşe Demir",
  "email": "ayse@example.com",
  "phoneNumber": "5559876543",
  "city": "34",
  "address": "Barbaros Bulvarı No:45 Beşiktaş",
  "iban": "TR120006200011122233344455",
  "accountHolder": "Ayşe Demir",
  "apiSecretKey": "sx_value",
  "active": true,
  "mpPaymentProfileExternalId": "STANDARD_PROFILE"
}

Corporation #

{
  "sellerExternalId": "COMPANY_001",
  "nameSurname": "Örnek Teknoloji A.Ş.",
  "sellerType": 3,
  "vkn": "1234567890",
  "taxOffice": "Kozyatağı",
  "contactPerson": "Mehmet Kaya",
  "email": "info@ornekteknoloji.com",
  "phoneNumber": "5551112233",
  "city": "34",
  "address": "Atatürk Mah. Teknoloji Cad. No:100 Kadıköy",
  "iban": "TR450006400000115638974521",
  "accountHolder": "Örnek Teknoloji A.Ş.",
  "apiSecretKey": "sx_value",
  "active": true,
  "mpPaymentProfileExternalId": "PREMIUM_PROFILE"
}

Response #

{
  "data": {
    "sellerExternalId": "SELLER_001",
    "active": true,
    "nameSurname": "Ahmet Yılmaz",
    "sellerType": "Gerçek Kişi",
    "tckn": "12345678901",
    "birthDate": "1985-05-15",
    "vkn": null,
    "contactPerson": "Ahmet Yılmaz",
    "phoneNumber": "5551234567",
    "city": "34",
    "address": "Atatürk Cad. No:123 Kadıköy",
    "iban": "TR330006100519786457841326",
    "accountHolder": "Ahmet Yılmaz",
    "paymentProfile": {
      "profileExternalId": "PREMIUM_PROFILE",
      "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"
    },
    "marketplaceCode": "MP12345",
    "taxOffice": "Kadıköy",
    "createDate": "2025-01-20T14:25:00Z",
    "updateDate": "2025-01-20T14:25:00Z",
    "email": "ahmet@example.com"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

2. GetSellerById #

Retrieves detailed information of a specific seller.

Endpoint #

TEST:

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

PROD:

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

Request #

{
  "sellerExternalId": "SELLER_001"
}

Response #

Response format is the same as CreateSeller. Returns current seller information and associated payment profile details.

3. UpdateSeller #

Updates information of an existing seller.

Endpoint #

TEST:

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

PROD:

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

Request #

{
  "sellerExternalId": "SELLER_001",
  "nameSurname": "Ahmet Yılmaz",
  "sellerType": 1,
  "tckn": "12345678901",
  "birthDate": "15.05.1985",
  "taxOffice": "Kadıköy",
  "contactPerson": "Ahmet Yılmaz",
  "email": "ahmet.yeni@example.com",
  "phoneNumber": "5559998877",
  "city": "34",
  "address": "Yeni Adres Bilgisi",
  "iban": "TR330006100519786457841326",
  "accountHolder": "Ahmet Yılmaz",
  "apiSecretKey": "sx_value",
  "active": true,
  "mpPaymentProfileExternalId": "STANDARD_PROFILE"
}

warning

Response #

Returns updated seller information in the same format as CreateSeller.

4. DeleteSellerById #

Deletes a seller from the system.

Endpoint #

TEST:

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

PROD:

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

Request #

{
  "sellerExternalId": "SELLER_001"
}

Response #

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

warning

5. GetAllSellerByApiSecretKey #

Lists all sellers belonging to the marketplace.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/sellers

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/seller/sellers

Request #

{
  "apiSecretKey": "sx_value",
  "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": [
    {
      "sellerExternalId": "SELLER_001",
      "active": true,
      "nameSurname": "Ahmet Yılmaz",
      "sellerType": "Gerçek Kişi",
      "tckn": "12345678901",
      "birthDate": "1985-05-15",
      "paymentProfile": {
        "profileExternalId": "PREMIUM_PROFILE",
        "name": "Premium Satıcı Profili",
        "mpCommissionRate": 5.00
      },
      "email": "ahmet@example.com"
    },
    {
      "sellerExternalId": "COMPANY_001",
      "active": true,
      "nameSurname": "Örnek Teknoloji A.Ş.",
      "sellerType": "Tüzel Kişi",
      "vkn": "1234567890",
      "paymentProfile": {
        "profileExternalId": "STANDARD_PROFILE",
        "name": "Standart Profil",
        "mpCommissionRate": 7.00
      },
      "email": "info@ornekteknoloji.com"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Use Case Scenarios #

Scenario 1: Bulk Seller Addition #

const sellers = [
  {
    sellerExternalId: "SELLER_001",
    nameSurname: "Ahmet Yılmaz",
    sellerType: 1,
    tckn: "12345678901",
    iban: "TR330006100519786457841326",
    mpPaymentProfileExternalId: "PREMIUM_PROFILE"
  },
  {
    sellerExternalId: "SELLER_002",
    nameSurname: "Ayşe Demir",
    sellerType: 1,
    tckn: "98765432101",
    iban: "TR120006200011122233344455",
    mpPaymentProfileExternalId: "STANDARD_PROFILE"
  }
];

for (const seller of sellers) {
  await createSeller({
    ...seller,
    apiSecretKey: process.env.API_SECRET_KEY,
    contactPerson: seller.nameSurname,
    accountHolder: seller.nameSurname,
    active: true
  });
}

Scenario 2: Seller Profile Change #

// Satıcının performansına göre premium profile yükselt
async function upgradeSellerToPremium(sellerExternalId) {
  // Mevcut satıcı bilgilerini al
  const seller = await getSeller(sellerExternalId);

  // Premium profile güncelle
  await updateSeller({
    ...seller.data,
    mpPaymentProfileExternalId: "PREMIUM_PROFILE"
  });

  console.log(`${sellerExternalId} premium profile yükseltildi`);
}

Scenario 3: Listing Active Sellers and Reporting #

async function getActiveSellersReport() {
  const response = await getAllSellers({
    apiSecretKey: process.env.API_SECRET_KEY,
    active: true
  });

  const report = response.data.map(seller => ({
    id: seller.sellerExternalId,
    name: seller.nameSurname,
    type: seller.sellerType,
    commission: seller.paymentProfile.mpCommissionRate,
    email: seller.email
  }));

  console.table(report);
  return report;
}

Complete Code Example #

const axios = require('axios');

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

  async createSeller(sellerData) {
    const response = await axios.post(
      `${this.baseURL}/seller`,
      {
        ...sellerData,
        apiSecretKey: this.apiSecretKey
      }
    );
    return response.data;
  }

  async getSeller(sellerExternalId) {
    const response = await axios.post(
      `${this.baseURL}/seller/get`,
      { sellerExternalId }
    );
    return response.data;
  }

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

  async deleteSeller(sellerExternalId) {
    const response = await axios.post(
      `${this.baseURL}/seller/delete`,
      { sellerExternalId }
    );
    return response.data;
  }

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

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

// Satıcı oluştur
const newSeller = await manager.createSeller({
  sellerExternalId: "SELLER_123",
  nameSurname: "Test Satıcı",
  sellerType: 1,
  tckn: "12345678901",
  iban: "TR330006100519786457841326",
  accountHolder: "Test Satıcı",
  contactPerson: "Test Satıcı",
  mpPaymentProfileExternalId: "PREMIUM_PROFILE",
  active: true
});

Best Practices #

1. IBAN Doğrulama #

function validateIBAN(iban) {
  // TR ile başlamalı ve 26 karakter olmalı
  if (!iban.startsWith('TR') || iban.length !== 26) {
    throw new Error('Geçersiz IBAN formatı');
  }

  // IBAN mod-97 kontrolü
  const rearranged = iban.substring(4) + iban.substring(0, 4);
  const numericIBAN = rearranged.replace(/[A-Z]/g, (char) =>
    char.charCodeAt(0) - 55
  );

  // Büyük sayılarla çalışmak için
  const remainder = BigInt(numericIBAN) % 97n;

  if (remainder !== 1n) {
    throw new Error('IBAN doğrulama hatası');
  }

  return true;
}

2. TCKN Doğrulama #

function validateTCKN(tckn) {
  if (tckn.length !== 11) return false;

  const digits = tckn.split('').map(Number);

  // İlk hane 0 olamaz
  if (digits[0] === 0) return false;

  // 10. hane kontrolü
  const sum10 = (
    (digits[0] + digits[2] + digits[4] + digits[6] + digits[8]) * 7 -
    (digits[1] + digits[3] + digits[5] + digits[7])
  ) % 10;

  if (sum10 !== digits[9]) return false;

  // 11. hane kontrolü
  const sum11 = digits.slice(0, 10).reduce((a, b) => a + b) % 10;

  return sum11 === digits[10];
}

3. VKN Doğrulama #

function validateVKN(vkn) {
  if (vkn.length !== 10) return false;

  const v = vkn.split('').map(Number);
  let sum = 0;

  for (let i = 0; i < 9; i++) {
    let digit = (v[i] + (9 - i)) % 10;
    sum += (digit * Math.pow(2, 9 - i)) % 9;
    if (digit !== 0 && (digit * Math.pow(2, 9 - i)) % 9 === 0) sum += 9;
  }

  return (10 - (sum % 10)) % 10 === v[9];
}

Next Steps #

After adding your sellers:

1. Payment Operations - Start accepting payments from sellers
2. Reporting - Get seller-based reports
3. Payment Modifications - Refund and cancellation operations