Reporting Services

Reporting Overview

With marketplace reporting services, you can analyze your transactions, sellers’ 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	❌	Pay N Kolay reference code
`apiSecretKey`	String	✅	SX value

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	Pay N Kolay reference code
`trxCurrency`	String	Currency code
`trxAmount`	BigDecimal	Total transaction amount
`trxStatus`	String	Transaction status
`pfCommissionRate`	BigDecimal	Pay N Kolay commission rate
`pfCommissionAmount`	BigDecimal	Pay N Kolay 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 Pay N Kolay 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"
}

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',  // All sellers
    apiSecretKey: process.env.API_SECRET_KEY,
    trxType: 'SALES',
    trxStatus: 'SUCCESS'
  });

  console.log('Daily Summary:');
  console.log(`Total Sales: ${report.countSuccessSalesTransaction}`);
  console.log(`Total Amount: ${report.totalAuthAmount} TL`);
  console.log(`Commission: ${report.totalMpCommissionAmount} TL`);
  console.log(`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} - 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(`\nTotal 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`);

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

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

// Usage
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');

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

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

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

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

Next Steps

After setting up the reporting system:

Payment Transactions - Receive new payments
Seller Management - Add and manage sellers
Payment Profile - Optimize profiles