Ödeme Profili Yönetimi

Ödeme Profili Nedir? #

Ödeme Profili, pazaryerinin satıcılarına uygulayacağı komisyon oranları, işlem ücretleri, ödeme günleri ve valör hesaplama yöntemlerini içeren yapılandırma setidir.

Pazaryeri, farklı satıcılarla farklı ödeme profilleri kullanarak çalışabilir. Örneğin:

Premium satıcılar için %2 komisyon
Standart satıcılar için %5 komisyon
Yeni satıcılar için %7 komisyon

Valör Hesaplama Tipleri #

Ödeme profilinde tanımlanan valör hesaplama tipi, satıcıya ödemenin ne zaman yapılacağını belirler.

Kod	Tip	Açıklama
W	WEEKLY	Haftalık Valör Hesaplama - Haftanın belirli gününde ödeme yapılır
H	HALF_MONTHLY	Yarım Aylık Valör Hesaplama - Ayda iki kez ödeme yapılır
M	MONTHLY	Aylık Valör Hesaplama - Ayın belirli gününde ödeme yapılır
T	TRANSACTION	İşlem Tarihi Temelli Valör - İşlem tarihinden N gün sonra ödeme yapılır
D	DELIVERY	Teslim Tarihi Temelli Valör - Teslim tarihinden N gün sonra ödeme yapılır

Ödeme Profili Servisleri #

Ödeme profili yönetimi için aşağıdaki servisler kullanılır:

CreatePaymentProfile - Yeni ödeme profili oluşturma
GetPaymentProfileById - Ödeme profili sorgulama
UpdatePaymentProfile - Ödeme profili güncelleme
DeletePaymentProfileById - Ödeme profili silme
GetAllPaymentProfileByApiSecretKey - Tüm profilleri listeleme

1. CreatePaymentProfile #

Yeni bir ödeme profili oluşturur.

Endpoint #

TEST:

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

PROD:

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

İstek Parametreleri #

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

Parametre Detayları #

Parametre	Tip	Zorunlu	Açıklama
profileExternalId	String	✅	Tekil dış ID - Kendi sisteminizdeki ID
apiSecretKey	String	✅	Pazaryerine ait SX değeri
name	String	❌	Profil adı (ör: "Premium Profil")
mpCommissionRate	BigDecimal	✅	Pazaryeri komisyon oranı (%)
mpCost	BigDecimal	❌	İşlem başına sabit ücret (TL)
paymentDay	Integer	✅*	Ödeme günü (1-7 arası, pazartesi=1). Haftalık/Aylık için zorunlu
valorDateCount	Integer	✅	Para transferi için bekleme süresi (gün)
valorCalculationType	String	✅	Valör hesaplama tipi (W, H, M, T, D)
active	Boolean	❌	Profil aktif mi? (varsayılan: true)

{ "profileExternalId": "IslemValor1", "apiSecretKey": "sx", "name": "İşlem Hesaplama 1", "mpCommissionRate": 5.00, "mpCost": 0.00, "paymentDay": null, "valorDateCount": 1, "valorCalculationType": "T", "active": true }
Bu örnekte, işlem yapıldıktan 1 gün sonra ödeme gerçekleştirilir. d-flex align-items-start mb-4" role="alert">

info

Yanıt #

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

Belirli bir ödeme profilinin detaylarını getirir.

Endpoint #

TEST:

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

PROD:

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

İstek #

{
  "profileExternalId": "IslemValor1"
}

Yanıt #

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

Mevcut bir ödeme profilini günceller.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Yanıt #

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

Bir ödeme profilini siler.

Endpoint #

TEST:

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

PROD:

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

İstek #

{
  "profileExternalId": "IslemValor1"
}

Yanıt #

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

warning

5. GetAllPaymentProfileByApiSecretKey #

Pazaryerine ait tüm ödeme profillerini listeler.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
apiSecretKey	String	✅	Pazaryerine ait SX değeri
active	Boolean	❌	true=sadece aktif, false=sadece pasif, null=tümü

Yanıt #

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

Kullanım Senaryoları #

Senaryo 1: Farklı Kategoriler için Farklı Profiller #

// 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"
});

Senaryo 2: Haftalık Ödeme Profili #

// 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
});

Senaryo 3: Teslim Tarihi Bazlı Ödeme #

// 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
});

Örnek Kod Bütünlüğü #

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

Sonraki Adımlar #

Ödeme profillerini oluşturduktan sonra:

1. Satıcı Yönetimi - Satıcılarınızı ekleyin ve profil atayın
2. Ödeme İşlemleri - Ödeme almaya başlayın
3. Raporlama - Profil bazlı raporlar alın