Reporting Services

Reporting Overview #

With marketplace reporting services, you can analyze your transactions, seller performance, and financial status in detail.

On this page, you will learn about the following reporting services:

GetTransactionReport - Transaction-based reporting
GetSellerTransactionReportByDate - Seller and date-based reporting
GetSellerPaymentList - Seller payment list
GetSellerDebtReport - Seller debt report

1. GetTransactionReport #

Retrieves a detailed report of a specific transaction.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/report

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/transaction/report

Request #

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

Parameter	Type	Required	Description
trxCode	String	❌	Your transaction code
refCode	String	❌	Paynkolay reference code
apiSecretKey	String	✅	SX value

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

Response #

{
  "data": [
    {
      "mpCode": "MP12345",
      "mpOrderCode": "ORDER_12345",
      "trxType": "SALES",
      "trxDatetime": "2025-01-20T14:30:15.204156Z",
      "trxCode": "REF123456789",
      "trxCurrency": "949",
      "trxAmount": 150.00,
      "trxStatus": "SUCCESS",
      "pfCommissionRate": 2.50,
      "pfCommissionAmount": 3.75,
      "sellerTransactionList": [
        {
          "sellerName": "Ahmet Yılmaz",
          "trxAmount": 100.00,
          "trxCurrency": "TRY",
          "trxStatus": "SUCCESS",
          "mpCommissionRate": 5.00,
          "mpCommissionAmount": 5.00,
          "mpCost": 0.50,
          "trxType": "SALES",
          "withholdingTax": 0.80,
          "trxCode": "REF123456789",
          "refCode": "REF123456789"
        },
        {
          "sellerName": "Örnek Teknoloji A.Ş.",
          "trxAmount": 50.00,
          "trxCurrency": "TRY",
          "trxStatus": "SUCCESS",
          "mpCommissionRate": 7.00,
          "mpCommissionAmount": 3.50,
          "mpCost": 0.25,
          "trxType": "SALES",
          "withholdingTax": 0.40,
          "trxCode": "REF123456789",
          "refCode": "REF123456789"
        }
      ]
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T15:00:00"
}

Response Parameters #

Main Transaction Information #

Parameter	Type	Description
mpCode	String	Marketplace code
mpOrderCode	String	Your transaction code
trxType	String	Transaction type (SALES, REFUND, CANCEL)
trxDatetime	String	Transaction date (ISO 8601)
trxCode	String	Paynkolay reference code
trxCurrency	String	Currency code
trxAmount	BigDecimal	Total transaction amount
trxStatus	String	Transaction status
pfCommissionRate	BigDecimal	Paynkolay commission rate
pfCommissionAmount	BigDecimal	Paynkolay commission amount

Seller Transaction Information #

Parameter	Type	Description
sellerName	String	Seller name
trxAmount	BigDecimal	Seller's transaction amount
mpCommissionRate	BigDecimal	Marketplace commission rate
mpCommissionAmount	BigDecimal	Marketplace commission amount
mpCost	BigDecimal	Transaction fee
withholdingTax	BigDecimal	Withholding tax amount

2. GetSellerTransactionReportByDate #

Lists all transactions of a seller within a specific date range.

Endpoint #

TEST:

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

PROD:

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

Request #

{
  "from": "2025-01-01",
  "to": "2025-01-31",
  "sellerExternalId": "SELLER_001",
  "apiSecretKey": "sx_value",
  "marketplaceCode": "MP12345",
  "trxType": "SALES",
  "trxStatus": "SUCCESS"
}

Parameter	Type	Required	Description
from	String	✅	Start date (yyyy-MM-dd)
to	String	✅	End date (yyyy-MM-dd)
sellerExternalId	String	✅	Seller external ID
apiSecretKey	String	❌	SX value
marketplaceCode	String	❌	Marketplace code
trxType	String	❌	Transaction type filter (SALES, REFUND, CANCEL)
trxStatus	String	❌	Status filter (SUCCESS, PENDING, FAILED)

Response #

{
  "countSuccessTransaction": 45,
  "countFailedTransaction": 3,
  "countSuccessSalesTransaction": 40,
  "countSuccessRefundTransaction": 4,
  "countSuccessCancelTransaction": 1,
  "totalAuthAmount": 12500.00,
  "totalPfCommissionAmount": 312.50,
  "totalMpCommissionAmount": 625.00,
  "totalSellerAmount": 11562.50,
  "data": [
    {
      "sellerName": "Ahmet Yılmaz",
      "trxAmount": 250.00,
      "trxCurrency": "TRY",
      "trxStatus": "SUCCESS",
      "mpCommissionRate": 5.00,
      "mpCommissionAmount": 12.50,
      "mpCost": 0.50,
      "trxType": "SALES",
      "withholdingTax": 2.00,
      "trxCode": "ORDER_001",
      "refCode": "REF001"
    },
    {
      "sellerName": "Ahmet Yılmaz",
      "trxAmount": 180.00,
      "trxCurrency": "TRY",
      "trxStatus": "SUCCESS",
      "mpCommissionRate": 5.00,
      "mpCommissionAmount": 9.00,
      "mpCost": 0.50,
      "trxType": "SALES",
      "withholdingTax": 1.44,
      "trxCode": "ORDER_002",
      "refCode": "REF002"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T16:30:00"
}

Summary Statistics #

Parameter	Description
countSuccessTransaction	Number of successful transactions
countFailedTransaction	Number of failed transactions
countSuccessSalesTransaction	Number of successful sales
countSuccessRefundTransaction	Number of successful refunds
countSuccessCancelTransaction	Number of successful cancellations
totalAuthAmount	Total authorized amount
totalPfCommissionAmount	Total Paynkolay commission
totalMpCommissionAmount	Total marketplace commission
totalSellerAmount	Net amount remaining to seller

3. GetSellerPaymentList #

Lists payment transfers made to the seller.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/seller/payment-report

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/transaction/seller/payment-report

Request #

{
  "from": "2025-01-01",
  "to": "2025-01-31",
  "sellerExternalId": "SELLER_001",
  "apiSecretKey": "sx_value",
  "marketplaceCode": "MP12345"
}

Response #

{
  "data": [
    {
      "sellerName": "Ahmet Yılmaz",
      "sellerExternalId": "SELLER_001",
      "trxAmount": 5000.00,
      "description": "Haftalık Hakediş Ödemesi - Hafta 3",
      "currency": "TRY",
      "transferDate": "2025-01-20",
      "eftOutDate": "2025-01-20"
    },
    {
      "sellerName": "Ahmet Yılmaz",
      "sellerExternalId": "SELLER_001",
      "trxAmount": 4500.00,
      "description": "Haftalık Hakediş Ödemesi - Hafta 2",
      "currency": "TRY",
      "transferDate": "2025-01-13",
      "eftOutDate": "2025-01-13"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T17:00:00"
}

Response Parameters #

Parameter	Type	Description
sellerName	String	Seller name
sellerExternalId	String	Seller external ID
trxAmount	BigDecimal	Transfer amount
description	String	Transfer description
currency	String	Currency
transferDate	String	Transfer date
eftOutDate	String	EFT outgoing date

4. GetSellerDebtReport #

Shows the seller's debt status.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/seller/debt-report

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/transaction/seller/debt-report

Request #

{
  "from": "2025-01-01T00:00",
  "to": "2025-01-31T23:59",
  "sellerExternalId": "SELLER_001",
  "marketplaceCode": "MP12345",
  "apiSecretKey": "sx_value"
}

The date format for this service is yyyy-MM-ddTHH:mm (datetime).

Response #

{
  "data": [
    {
      "sellerName": "Ahmet Yılmaz",
      "debtAmount": 150.00,
      "trxCurrency": "TRY",
      "debtCreateDate": "2025-01-15T14:30:00",
      "debtUpdateDate": "2025-01-20T10:00:00",
      "debtStatus": true
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T18:00:00"
}

Response Parameters #

Parameter	Type	Description
sellerName	String	Seller name
debtAmount	BigDecimal	Debt amount
trxCurrency	String	Currency
debtCreateDate	String	Debt creation date
debtUpdateDate	String	Debt update date
debtStatus	Boolean	Is debt active? (true=active, false=closed)

Example Use Cases #

Scenario 1: Daily Sales Report #

async function getDailySalesReport(date) {
  const report = await getSellerTransactionReportByDate({
    from: date,
    to: date,
    sellerExternalId: 'ALL',  // Tüm satıcılar / All sellers
    apiSecretKey: process.env.API_SECRET_KEY,
    trxType: 'SALES',
    trxStatus: 'SUCCESS'
  });

  console.log('Günlük Özet / Daily Summary:');
  console.log(`Toplam Satış / Total Sales: ${report.countSuccessSalesTransaction}`);
  console.log(`Toplam Tutar / Total Amount: ${report.totalAuthAmount} TL`);
  console.log(`Komisyon / Commission: ${report.totalMpCommissionAmount} TL`);
  console.log(`Net Kazanç / Net Profit: ${report.totalSellerAmount} TL`);

  return report;
}

Scenario 2: Seller Performance Analysis #

async function analyzeSellerPerformance(sellerExternalId, month) {
  const startDate = `${month}-01`;
  const endDate = new Date(month + '-01');
  endDate.setMonth(endDate.getMonth() + 1);
  endDate.setDate(0);
  const lastDay = endDate.toISOString().split('T')[0];

  const report = await getSellerTransactionReportByDate({
    from: startDate,
    to: lastDay,
    sellerExternalId,
    apiSecretKey: process.env.API_SECRET_KEY
  });

  const performance = {
    seller: sellerExternalId,
    period: month,
    totalSales: report.countSuccessSalesTransaction,
    totalRefunds: report.countSuccessRefundTransaction,
    revenue: report.totalSellerAmount,
    commission: report.totalMpCommissionAmount,
    refundRate: (report.countSuccessRefundTransaction / report.countSuccessSalesTransaction * 100).toFixed(2) + '%'
  };

  console.table(performance);
  return performance;
}

Scenario 3: Payment Tracking #

async function trackSellerPayments(sellerExternalId) {
  const payments = await getSellerPaymentList({
    from: '2025-01-01',
    to: '2025-12-31',
    sellerExternalId,
    apiSecretKey: process.env.API_SECRET_KEY
  });

  console.log(`\n${sellerExternalId} - Ödeme Geçmişi / Payment History:\n`);

  payments.data.forEach(payment => {
    console.log(`${payment.transferDate}: ${payment.trxAmount} TL - ${payment.description}`);
  });

  const totalPaid = payments.data.reduce((sum, p) => sum + p.trxAmount, 0);
  console.log(`\nToplam Ödenen / Total Paid: ${totalPaid} TL`);

  return payments;
}

Scenario 4: Debt Check #

async function checkSellerDebts() {
  const sellers = await getAllSellers();

  for (const seller of sellers.data) {
    const debtReport = await getSellerDebtReport({
      from: '2025-01-01T00:00',
      to: new Date().toISOString().slice(0, 16),
      sellerExternalId: seller.sellerExternalId,
      apiSecretKey: process.env.API_SECRET_KEY
    });

    const activeDebts = debtReport.data.filter(d => d.debtStatus === true);

    if (activeDebts.length > 0) {
      const totalDebt = activeDebts.reduce((sum, d) => sum + d.debtAmount, 0);

      console.log(`⚠️ ${seller.nameSurname}: ${totalDebt} TL debt`);

      // Satıcıyı bilgilendir / Notify seller
      await notifySellerAboutDebt(seller.email, totalDebt);
    }
  }
}

Dashboard Example #

class MarketplaceDashboard {
  async getOverview(from, to) {
    const allSellers = await this.getAllSellers();

    const overview = {
      totalSellers: allSellers.data.length,
      activeSellers: allSellers.data.filter(s => s.active).length,
      totalRevenue: 0,
      totalCommission: 0,
      totalTransactions: 0,
      sellerReports: []
    };

    for (const seller of allSellers.data) {
      const report = await getSellerTransactionReportByDate({
        from,
        to,
        sellerExternalId: seller.sellerExternalId,
        apiSecretKey: this.apiSecretKey
      });

      overview.totalRevenue += report.totalAuthAmount;
      overview.totalCommission += report.totalMpCommissionAmount;
      overview.totalTransactions += report.countSuccessTransaction;

      overview.sellerReports.push({
        sellerId: seller.sellerExternalId,
        sellerName: seller.nameSurname,
        sales: report.countSuccessSalesTransaction,
        revenue: report.totalAuthAmount,
        commission: report.totalMpCommissionAmount
      });
    }

    // Satıcıları ciroya göre sırala / Sort sellers by revenue
    overview.sellerReports.sort((a, b) => b.revenue - a.revenue);

    return overview;
  }

  displayDashboard(overview) {
    console.log('\n📊 MARKETPLACE DASHBOARD\n');
    console.log(`Total Sellers: ${overview.totalSellers}`);
    console.log(`Active Sellers: ${overview.activeSellers}`);
    console.log(`Total Revenue: ${overview.totalRevenue.toFixed(2)} TL`);
    console.log(`Total Commission: ${overview.totalCommission.toFixed(2)} TL`);
    console.log(`Total Transactions: ${overview.totalTransactions}\n`);

    console.log('🏆 TOP SELLERS:\n');
    overview.sellerReports.slice(0, 10).forEach((seller, index) => {
      console.log(
        `${index + 1}. ${seller.sellerName}: ` +
        `${seller.revenue.toFixed(2)} TL (${seller.sales} sales)`
      );
    });
  }
}

// Kullanım
const dashboard = new MarketplaceDashboard();
const overview = await dashboard.getOverview('2025-01-01', '2025-01-31');
dashboard.displayDashboard(overview);

Excel Export Example #

const ExcelJS = require('exceljs');

async function exportSellerReport(sellerExternalId, from, to) {
  const report = await getSellerTransactionReportByDate({
    from,
    to,
    sellerExternalId,
    apiSecretKey: process.env.API_SECRET_KEY
  });

  const workbook = new ExcelJS.Workbook();
  const worksheet = workbook.addWorksheet('İşlem Raporu');

  // Başlıklar / Headers
  worksheet.columns = [
    { header: 'İşlem Kodu', key: 'trxCode', width: 20 },
    { header: 'Tarih', key: 'date', width: 15 },
    { header: 'Tutar', key: 'amount', width: 12 },
    { header: 'Komisyon', key: 'commission', width: 12 },
    { header: 'Stopaj', key: 'tax', width: 12 },
    { header: 'Net', key: 'net', width: 12 },
    { header: 'Durum', key: 'status', width: 12 }
  ];

  // Veriler / Data
  report.data.forEach(trx => {
    worksheet.addRow({
      trxCode: trx.trxCode,
      date: trx.trxDate,
      amount: trx.trxAmount,
      commission: trx.mpCommissionAmount,
      tax: trx.withholdingTax,
      net: trx.trxAmount - trx.mpCommissionAmount - trx.withholdingTax,
      status: trx.trxStatus
    });
  });

  // Stil / Style
  worksheet.getRow(1).font = { bold: true };

  // Kaydet / Save
  await workbook.xlsx.writeFile(`seller_report_${sellerExternalId}.xlsx`);
}

Next Steps #

After setting up the reporting system:

1. Payment Transactions - Receive new payments
2. Seller Management - Add and manage sellers
3. Payment Profile - Optimize profiles