Contribution Reports

What are Contribution Reports?

Kota’s contribution reporting system provides the data you need while allowing your payroll engine to handle the business logic. By integrating properly with this system, you can ensure accurate, compliant payroll processing across multiple countries and insurance providers with minimal manual intervention.

Contribution reports are a critical component for platforms that handle contributions, such as payroll and benefits platforms. They provide a structured way to access and process insurance contributions across multiple countries, enabling scalable systems and efficient reporting.

A contribution report represents a comprehensive breakdown of all insurance contributions for a specific employer over a defined period. Each report contains detailed employee breakdowns that include both employer and employee contributions.

For detailed API references, see the Contribution Reports API documentation.

Understanding Contribution Report Structure

Contribution reports consist of three main components that work together to provide a complete picture of insurance contributions:

1. Contribution Report - The top-level container identified by a ctr_ prefix

   • Represents all contributions, whether employee-made or employer-made, for a specific employer during a specific period (usually a month)
   • Has a status of either open or finalized

2. Employee Breakdowns - The per-employee details within a contribution report

   • Contains separate sections for employer and employee contributions to the policy
   • Employer and employee sections represent their respective contributions to the employee’s insurance (e.g. employer may pay for the main policy with the employee paying for dependents, or employer may pay for the entire policy)
   • Employer contributions can be used for various payroll benefit calculations or reporting obligations, while employee contributions may be relevant to payroll deductions or reporting obligations
   • Organized by insurance type (health, life, etc.)

3. Individual Contributions - The actual monetary amounts identified by a ct_ prefix

   • Found within the employee breakdowns
   • Can be regular contributions or adjustments to previous contributions

When processing contribution reports, you’ll first retrieve the report, then access the employee breakdowns to get the individual contributions. The employer contributions and employee contributions are separated within each breakdown, allowing you to process them differently in your system.

For example, as mentioned above, employer contributions might be handled as company expenses and need to be reported to a national authority, while employee contributions could be deducted from employee paychecks. This separation gives you the flexibility to implement your own business logic and handle the complexity of international payroll and reporting requirements and changing regulatory environments.

Key Concepts

Report Lifecycle

Contribution reports have two possible states:

• Open: The report can still be modified as new data is processed
• Finalized: The report is immutable and serves as a historical record

Reports can be finalized at any point during the month by calling the Finalize contribution report API. If not explicitly finalized, they are automatically finalized at the end of the month.

Important: Once a report is finalized, any new contributions that arrive afterward during the same month will appear in the next month’s report. This is the standard behavior for late-arriving data, not an adjustment scenario.

Reports become available from the 1st of each month or after the finalization of the previous month’s report.

Contribution Adjustments

Adjustments are a mechanism to correct or modify previous contributions. When a contribution needs to be adjusted (due to changes in employee status, corrections, etc.), the adjustment is marked with:

• An adjustment flag set to true
• A reference to the original contribution being adjusted (adjustment_for)
• Usually accompanied by explanatory notes

Reporting Periods

The various reports contain several different reporting and cover periods throughout, each relevant to what the report is being used for. Understanding these periods is crucial for accurate processing and reporting.

Contribution report - period

Each contribution report has a period property that covers a specific time period. This helps you decide which report to use for a given payroll run. For example, if you’re running June’s payroll, you might want to use either June’s report (if finalizing it manually) or May’s completed report.

The period property is defined as a start date (from_date) and an end date (to_date). Both dates are formatted as YYYY-MM-DD.

Employee breakdown report - periods

Employee breakdowns contain different period properties at different levels of the data structure.

The employee breakdown - period:

The period property at the root of the employee breakdown is identical to the period of the parent contribution report. This represents the reporting period that the breakdown belongs to.

Note: While the breakdown’s period represents the reporting month, the individual contributions within it may have different cover_period values spanning current, previous, or future months.

Individual employer / employee contributions - cover_period:

The period for which the insurance premium contribution covers the employee. It may differ from the report’s period. This allows for flexibility in reporting and processing contributions - see scenarios below to learn about the specific scenarios where this occurs.

The cover_period property is defined as a start date (from_date) and an end date (to_date). Both dates are formatted as YYYY-MM-DD.

Cover periods can vary in two important ways:

• Different month boundaries: While most coverage periods run from the 1st to the end of the month, some may start on any date (e.g. from the 10th of one month to the 9th of the next month)
• Partial periods: Coverage can be shorter than one month, particularly for mid-term joiners or leavers who have pro-rated coverage

Individual employer / employee contributions - reporting_month:

The primary month for which the contribution is relevant as it helps align contributions with standard monthly reporting cycles. It allows for consistent monthly categorisation in systems that require calendar-based reporting.

The reporting_month property is:

• Always present for every contribution entry
• Guaranteed to be in YYYY-MM-01 format (the day is always 01 by convention)
• Typically based on the start date of the period for cross-month cover periods (e.g., 10th to 9th)
• Consistent and stable for operational categorization

Key Properties in Employee Breakdowns

This report contains the breakdown of contributions for each employee, split across the employer’s and employee’s own contributions. Focusing on the health_insurance object, common to both employer and employee, it’s useful to highlight some properties:

• category: Category of the contribution gross_premium, tax, tax_relief - critical for how you process and report the contributions
• member_type: Where available we split out contributions by policyholder, partner_dependant, child_dependant - this is useful for understanding the breakdown of contributions and how they are processed and may have reporting or tax implications in different jurisdictions
• adjustment: Explained more elsewhere but this is where you’d locate and process an adjustment
• adjustment_for: References the id field of the original contribution being adjusted - this is important for tracking and reconciling adjustments within your system and presenting it back to employers
• note: Optional field for additional context, e.g. if the amount is pro-rated or backdated

Employee breakdown responses also include a currency field indicating the currency for all monetary amounts in the breakdown (e.g., eur, usd).

Using Contribution Reports

Estimated Implementation Time

Estimated implementation time: 1-2 weeks, depending on:

• Complexity of your existing system
• How you handle historical data and adjustments

Our implementation guide provides a clear path to integrate contribution reports into your system with clear code examples and scenarios through out for you which should help you decide on how much you need to support for your use-case and roadmapping.

Integrating contribution reports into your system involves a clear sequence of operations:

Step 1: Discover Available Reports

Before you can process contribution reports, you need to identify which reports are available for your use. Use the List contribution reports API to discover available reports with filtering options.

1
// List all contribution reports for a specific employer
2
async function listContributionReports(employerId, options = {}) {
3
  const params = {
4
    employer_id: employerId,
5
    ...options
6
  };
7
  
8
  const response = await kotaClient.get('/contribution_reports', { params });
9
  return response.data.data;
10
}
11
12
// Example: Get reports for payroll processing (any status)
13
async function getReportsForPayroll(employerId, year, month) {
14
  const reports = await listContributionReports(employerId, {
15
    year: year,
16
    month: month
17
  });
18
  
19
  return reports;
20
}

Common filtering scenarios:

• For payroll processing: Filter by employer_id and specific year/month
• For EoR platforms: Add external_customer_id to separate reports by customer
• For historical analysis: Use status: 'finalized' with date range filtering for completed periods

Step 2: Finalize the Report (if needed)

If the report is in open status, you need to finalize it before processing to ensure the data is immutable. If it’s already finalized, you can skip this step. Use the Finalize contribution report API.

For payroll processing, the recommended approach is to finalize the report immediately before using it for locking your payroll run. For example, if you’re running payroll on September 22nd, you should finalize September’s report on that same day before processing payroll.

1
// Complete workflow: discover and conditionally finalize
2
async function prepareReportForPayroll(employerId, year, month) {
3
  // Step 1: Find reports for the specified month
4
  const reports = await getReportsForPayroll(employerId, year, month);
5
  
6
  if (reports.length === 0) {
7
    throw new Error(`No reports found for ${year}-${month}`);
8
  }
9
  
10
  const report = reports[0];
11
  console.log(`Found report: ${report.id} (status: ${report.status})`);
12
  
13
  // Step 2: Finalize if needed
14
  if (report.status !== 'finalized') {
15
    console.log(`Report ${report.id} is not finalized, finalizing...`);
16
    await kotaClient.post(`/contribution_reports/${report.id}/finalize`);
17
    console.log(`Report ${report.id} finalized successfully`);
18
  } else {
19
    console.log(`Report ${report.id} is already finalized`);
20
  }
21
  
22
  return report.id; // Return the ID for the next step
23
}

Step 3: Retrieve Employee Breakdowns

Once you have the finalized contribution report, you need to retrieve the employee breakdowns:

• List All Breakdowns: Use List employee breakdowns to get all employee data at once
• Or Get Individual Breakdowns: For targeted processing, use Retrieve individual employee breakdown with employee IDs

1
// Retrieve all employee breakdowns for a report
2
async function getEmployeeBreakdowns(reportId) {
3
  const response = await kotaClient.get(`/contribution_reports/${reportId}/employee_breakdowns`);
4
  return response.data.data;
5
}
6
7
// Retrieve a specific employee's breakdown
8
async function getEmployeeBreakdown(reportId, employeeId) {
9
  const response = await kotaClient.get(`/contribution_reports/${reportId}/employee_breakdowns/${employeeId}`);
10
  return response.data;
11
}

Step 4: Process Contributions

After retrieving the data, process each employee’s contributions:

1. Distinguish Contribution Types:

   • Regular contributions: Process as normal additions to reports
   • Adjustments: Apply as corrections to previous periods
   • Pro-rated amounts: No special action needed as they appear like regular contributions but may contain a note field

2. Handle Each Contribution Type Appropriately:

   • Store contribution IDs for future reference (important for later adjustments)
   • Maintain a record of processed contributions

1
// Process employee breakdowns from a contribution report
2
async function processEmployeeBreakdowns(reportId) {
3
  // Get all employee breakdowns for this report
4
  const breakdowns = await getEmployeeBreakdowns(reportId);
5
6
  for (const breakdown of breakdowns) {
7
    await processEmployeeContributions(breakdown);
8
  }
9
10
  console.log(`Successfully processed all employee breakdowns for report ${reportId}`);
11
}
12
13
// Process contributions for a single employee
14
async function processEmployeeContributions(breakdown) {
15
  const { employee_id, health_insurance } = breakdown;
16
17
  // Process health insurance contributions
18
  if (health_insurance) {
19
    await processContributionSet(employee_id, health_insurance.employer_contributions, 'employer');
20
    await processContributionSet(employee_id, health_insurance.employee_contributions, 'employee');
21
  }
22
23
  // handle other types of insurance in the future
24
}

Common Scenarios

Scenario 1: Contribution Reports for Different Time Periods

Depending on insurer invoicing and report finalization timelines, contribution reports may contain contributions for different periods. Understanding these timing variations is crucial for correctly processing contributions in your system.

Previous Month Contributions

In this scenario, May’s payroll would include contributions for April coverage, which appear in the May contribution report. When you process your May payroll run, you would include these April contributions to ensure employees and employers pay for the insurance coverage that was provided in April.

• Why this happens: There are two main cases where April contributions appear in your May report:
  1. Insurer timing: The insurer provides contribution data in arrears. For example, data for April coverage is provided on May 1st. When Kota receives this data, the April contributions are added to your May report.
  2. Report finalization timing: The insurer provides contribution data during the same month as the coverage, but after you’ve already finalized your report for that month. For example, you finalize your April report on April 10th, but the insurer provides data on April 12th. These contributions roll over to your May report.
• Processing approach: Treat these as regular monthly contributions that happen to cover a previous period.
• Reconciliation needs: None required, as this is normal timing variation in insurance processing.

Current Month Contributions

In this scenario, May’s payroll would include contributions for May coverage, which appear in the May contribution report. When you process your May payroll run, you would include these May contributions to ensure employees and employers pay for the insurance coverage that will be provided in May.

• Why this happens: There are two main cases where May contributions appear in your May report:
  1. Insurer timing: The insurer provides contribution data in advance for the current month. For example, on April 1st, they provide data for April coverage. When Kota receives this data, the April contributions are added to your April report.
  2. Report finalization timing: The insurer provides contribution data for a future month, but after you’ve already finalized your current report. For example, you finalize your April report on April 10th, but on April 28th you receive data for May in advance. These May contributions roll over to your May report.
• Processing approach: Treat these as regular monthly contributions where the coverage period aligns with the payment period.
• Reconciliation needs: Adjustments may occur in the next month if employee status changes happen during the coverage month after finalization or cut-off dates.

Next Month Contributions

In this scenario, May’s payroll would include contributions for June coverage, which appear in the May contribution report. When you process your May payroll run, you would include these June contributions to ensure employees and employers pay for the insurance coverage that will be provided in June.

• Why this happens: The insurer requires advance payment for future coverage. For example, on May 15th, they provide data for June coverage requiring payment before the coverage period begins. When Kota receives this data, the June contributions are added to your May report.
• Processing approach: Treat these as prepaid expenses in your accounting system, as payment occurs before the coverage period.
• Reconciliation needs: You may need to account for adjustments if employee status changes before the coverage period ends.

Cross-Month Coverage Periods

In this scenario, May’s payroll might include contributions with coverage periods that span across calendar months, such as mid-April to mid-May or mid-May to mid-June.

• Why this happens: Some insurers allow coverage periods to start on any date during the month, not just the 1st. This creates coverage periods that don’t align with standard calendar months.
• Processing approach:
  • Use the cover_period dates to understand the actual coverage timeframe
  • For systems requiring strict calendar month assignment, use the reporting_month property which provides a standardized monthly categorization
  • Treat these as regular contributions while being mindful of the non-standard coverage periods
• Reconciliation needs: Standard adjustment handling applies, with particular attention to changes that occur during the cross-month coverage period.

For example, if contribution data with a coverage period from April 10th to May 9th is received by Kota on May 5th, it will be included in your May contribution report. The reporting_month field will help you categorize this contribution consistently with your monthly reporting cycles.

1
// Process contributions with various timing scenarios using reporting_month for categorization
2
// Note: Adjustment handling is omitted for brevity - see Scenario 2 for adjustment processing
3
async function processEmployeeContributions(breakdown) {
4
  const { employee_id, health_insurance } = breakdown;
5
6
  if (!health_insurance?.employer_contributions) return;
7
8
  for (const contribution of health_insurance.employer_contributions) {
9
    // Use reporting_month for consistent monthly categorization
10
    const reportingMonth = contribution.reporting_month.substring(0, 7); // Extract YYYY-MM
11
12
    // Process the contribution amount for payroll
13
    await processPayrollContribution(employee_id, contribution.amount, reportingMonth);
14
15
    // Store coverage details for auditing and transparency
16
    await auditContributionCoverage({
17
      contributionId: contribution.id,
18
      employeeId: employee_id,
19
      amount: contribution.amount,
20
      coveragePeriod: contribution.cover_period,
21
      reportingMonth: reportingMonth,
22
      category: contribution.category,
23
      memberType: contribution.member_type,
24
      isAdjustment: contribution.adjustment,
25
      adjustmentFor: contribution.adjustment_for,
26
      note: contribution.note
27
    });
28
  }
29
}
30
31
// Example: Categorize contributions by reporting month for monthly reports
32
function categorizeContributionsByMonth(contributions) {
33
  const monthlyBreakdown = {};
34
35
  contributions.forEach(contribution => {
36
    const month = contribution.reporting_month.substring(0, 7);
37
38
    if (!monthlyBreakdown[month]) {
39
      monthlyBreakdown[month] = {
40
        totalAmount: 0,
41
        contributions: []
42
      };
43
    }
44
45
    monthlyBreakdown[month].totalAmount += contribution.amount;
46
    monthlyBreakdown[month].contributions.push({
47
      id: contribution.id,
48
      amount: contribution.amount,
49
      coveragePeriod: contribution.cover_period,
50
      note: contribution.note
51
    });
52
  });
53
54
  return monthlyBreakdown;
55
}

Scenario 2: Contribution Reports with Adjustments

When corrections need to be made to previous contributions, they appear as adjustments in subsequent reports. Understanding how to process these adjustments is critical for maintaining accurate records and ensuring proper accounting.

What Are Contribution Adjustments?

Adjustments are special contribution entries that modify previously processed contributions. As mention above, they are characterized by:

• An adjustment flag set to true to distinguish them from regular contributions
• An adjustment_for field that references the ID of the original contribution being adjusted
• An amount that can be positive (additional payment) or negative (refund/reduction)
• Often include explanatory notes about the reason for the adjustment

Common Reasons for Adjustments

Adjustments typically occur due to:

• Retroactive changes: Employee status or coverage level changed after a contribution was processed
• Correction of errors: Fixing incorrect amounts from previous periods
• Policy changes: Mid-period changes to insurance policies requiring recalculation
• Reconciliation: Aligning actual costs with previously estimated amounts

Processing Adjustments in Your System

When handling adjustments, your system should:

1. Identify the original contribution using the adjustment_for reference
2. Apply the adjustment amount to correct the previous contribution
3. Maintain an audit trail linking the adjustment to the original contribution
4. Include explanatory notes in records for transparency

This approach ensures that your system accurately reflects all changes while maintaining a clear history of contributions and their adjustments.

1
// Process contributions and handle adjustments
2
async function processContributions(breakdown) {
3
  const { employee_id, health_insurance } = breakdown;
4
5
  if (!health_insurance?.employer_contributions) return;
6
7
  for (const contribution of health_insurance.employer_contributions) {
8
    if (contribution.adjustment) {
9
      // Handle adjustment - link to previous contribution in your system
10
      console.log(`Processing adjustment of ${contribution.amount} for original contribution ${contribution.adjustment_for}`);
11
12
      // Look up the original contribution in your database using the adjustment_for ID
13
      const originalContribution = await lookupContribution(contribution.adjustment_for);
14
15
      // Apply the adjustment and maintain the link for reconciliation
16
      await applyAdjustment(employee_id, contribution, originalContribution);
17
    } else {
18
      // Handle regular contribution
19
      console.log(`Processing regular contribution of ${contribution.amount}`);
20
      await applyRegularContribution(employee_id, contribution);
21
    }
22
  }
23
}

Scenario 3: Employees Joining a Group Policy

When employees join mid-period, their first contribution report typically contains multiple contributions: pro-rated amounts for the partial initial period and full amounts for subsequent complete periods.

Understanding Pro-rated Contributions for New Employees

When an employee joins mid-month, their first contribution report typically includes:

• Pro-rated contributions for the partial first month (from join date to month-end)
• Full contributions for the upcoming complete month
• Special notes indicating the pro-rated nature of the contribution

How Pro-rata Works

Pro-rated amounts appear as regular contributions with shorter coverage periods:

• Coverage period: Clearly indicated in the cover_period field with specific from_date and to_date
• Calculation: Already handled by the insurer based on the partial coverage period

Implementation Considerations

When processing contributions for new employees, your system should:

1. Apply the correct amount to the appropriate period
2. Maintain clear records of the employee’s join date and initial coverage
3. Handle both partial and full-month contributions in the same cycle if needed

This approach ensures that new employees are charged correctly from their first day of coverage, while maintaining accurate financial records for both the employer and employee.

1
{
2
  "object": "contribution_report_employee_breakdown",
3
  "employee_id": "ee_c245fde199004eee845b2c26a5732ce2",
4
  "contribution_report_id": "ctr_7d37c383d2bf49c4beea3ebdbe4de787",
5
  "employer_id": "er_01227f212421474cbe687cde68568d37",
6
  "external_customer_id": null,
7
  "period": {
8
    "from_date": "2025-05-01",
9
    "to_date": "2025-05-31"
10
  },
11
  "currency": "eur",
12
  "status": "finalized",
13
  "finalized_at": "2025-06-01T00:00:10.311966Z",
14
  "created_at": "2025-05-10T20:53:14.196315Z",
15
  "last_updated_at": "2025-06-01T00:00:10.323195Z",
16
  "health_insurance": {
17
    "employer_contributions": [
18
      {
19
        "id": "ct_0447692a1bf74400965b1c1b00f33610",
20
        "category": "gross_premium",
21
        "member_type": "policyholder",
22
        "adjustment": false,
23
        "adjustment_for": null,
24
        "amount": 83.33,
25
        "type": "recurring",
26
        "note": "Pro-rated for employee joining April 20th",
27
        "cover_period": {
28
          "from_date": "2025-04-20",
29
          "to_date": "2025-04-30"
30
        },
31
        "employee_policy_id": "eehp_fa505f9505d3464cbf7cabd5d763722a",
32
        "reporting_month": "2025-04-01"
33
      },
34
      {
35
        "id": "ct_8db2eb4b9d9446a0b9fef29a7f3c36c9",
36
        "category": "gross_premium",
37
        "member_type": "policyholder",
38
        "adjustment": false,
39
        "adjustment_for": null,
40
        "amount": 250.00,
41
        "type": "recurring",
42
        "note": "",
43
        "cover_period": {
44
          "from_date": "2025-05-01",
45
          "to_date": "2025-05-31"
46
        },
47
        "employee_policy_id": "eehp_fa505f9505d3464cbf7cabd5d763722a",
48
        "reporting_month": "2025-05-01"
49
      }
50
    ]
51
  }
52
}

Scenario 4: Employees Leaving the Company

When employees leave but their final payroll is processed before the contribution report reflecting their departure, you’ll need to handle pro-rata reimbursements. This scenario requires careful handling to ensure proper accounting and to avoid overcharging for insurance coverage.

Understanding Employee Departure Refunds

When an employee leaves mid-month, the contribution report will typically include:

• Negative adjustment to refund the unused portion of the month’s premium
• Reference to the original contribution being adjusted via the adjustment_for field
• Coverage period indicating the correct covered portion
• Explanatory note mentioning the employee’s departure date

Timing Challenges with Employee Departures

A common challenge occurs when:

1. An employee leaves mid-month (e.g., May 10th)
2. Their final payroll is processed immediately (e.g., May 11th)
3. The contribution report reflecting their departure isn’t finalized until later (e.g., June 1st)

This timing mismatch means you’ll need to handle the refund in a subsequent payroll cycle after the employee has already departed.

Refunds for departed employees are identified by:

• The same employee_id and employee_policy_id as the original contribution
• Marked with adjustment=true and a reference via adjustment_for
• Negative amounts for refunds
• Often include explanatory notes mentioning the departure

Implementation Considerations

When processing refunds for departed employees, your system should:

1. Identify departure refunds by checking the adjustment flag and negative amounts
2. Link the refund to the original contribution using the adjustment_for reference
3. Consider applying the refund to the employer’s account rather than the departed employee (depending on your platform’s refund policy)
4. Maintain records of the departure date and refund for compliance and auditing

This approach ensures that employers receive appropriate refunds for departed employees while maintaining accurate financial records.

1
// Process refund for an employee who has left
2
async function processEmployeeLeaverRefund(breakdown) {
3
  const { employee_id, health_insurance } = breakdown;
4
5
  if (!health_insurance?.employer_contributions) return;
6
7
  // Find refund adjustments (negative amounts with adjustment flag)
8
  const refundAdjustments = health_insurance.employer_contributions.filter(
9
    contribution => contribution.adjustment && contribution.amount < 0
10
  );
11
12
  for (const refund of refundAdjustments) {
13
    // Link to the original contribution being adjusted
14
    const originalContributionId = refund.adjustment_for;
15
16
    // Process the refund in your system
17
    await processRefund(employee_id, refund, originalContributionId);
18
  }
19
}
20
21
// Implementation for processing refunds
22
async function processRefund(employeeId, refund, originalContributionId) {
23
  // Apply the refund to your system (e.g., credit employer account)
24
  await applyRefundToAccount(employeeId, refund.amount);
25
26
  // Record the refund with link to original contribution for audit trail
27
  await recordRefund({
28
    employeeId: employeeId,
29
    refundId: refund.id,
30
    amount: refund.amount,
31
    originalContributionId: originalContributionId,
32
    coveragePeriod: refund.cover_period,
33
    note: refund.note
34
  });
35
}

Scenario 5: Working with tax relief - Irish Tax Relief at Source (TRS) example

In Ireland, health insurance contributions may include Tax Relief at Source (TRS), which creates separate contribution entries for premium and tax relief amounts. This scenario requires special handling to ensure correct payroll processing and compliance with Irish tax regulations.

Understanding TRS Contributions

TRS contributions appear as separate entries in the contribution report. The handling differs significantly depending on whether it’s an employer or employee contribution.

TRS Data Structure

For Irish health insurance with TRS, you will receive separate contribution entries. The following provides a simplified overview of the TRS handling, please ensure your implementation complies with current Irish tax regulations and Revenue requirements.

Employer contributions with TRS:

• Premium contribution: Gross premium amount with category: "gross_premium"
• Tax relief contribution: TRS amount with category: "tax_relief"
• Payment flow: Employer sends TRS amount to Revenue and pays discounted amount to insurer
• Employee claim: Employee can claim the TRS amount at year-end tax filing

Employee contributions with TRS:

• Premium contribution: Gross premium amount with category: "gross_premium"
• Tax relief contribution: TRS amount with category: "tax_relief"
• Payment flow: Only the discounted amount is relevant for the employee

Implementation Considerations

When processing TRS contributions, your system should:

1. Identify TRS entries by checking for category: "tax_relief"
2. Handle premium and tax relief entries according to their different requirements
3. Handle employer vs employee contributions differently as they have distinct payment flows
4. Maintain records of both gross and net amounts for compliance

1
// Process TRS contributions - identify premium and tax relief pairs
2
async function processTRSContributions(breakdown) {
3
  const { employee_id, health_insurance } = breakdown;
4
5
  if (!health_insurance) return;
6
7
  for (const contributionSet of [health_insurance.employer_contributions, health_insurance.employee_contributions]) {
8
    if (!contributionSet) continue;
9
10
    const grossPremiumContributions = contributionSet.filter(c => c.category === 'gross_premium');
11
    const trsContributions = contributionSet.filter(c => c.category === 'tax_relief');
12
13
    for (const grossPremium of grossPremiumContributions) {
14
      // Find matching TRS contribution
15
      const matchingTrs = trsContributions.find(trs => 
16
        trs.member_type === grossPremium.member_type && 
17
        trs.employee_policy_id === grossPremium.employee_policy_id
18
      );
19
20
      // Process according to your system's requirements
21
      await processTRSPair({
22
        grossPremium: grossPremium,
23
        trs: matchingTrs,
24
        employeeId: employee_id
25
      });
26
    }
27
  }
28
}

Scenario 6: EoR Platform Processing

Employer of Record (EoR) platforms handle multiple customers under a single employer relationship. For these platforms, contribution reports are automatically separated by customer, with each customer receiving their own dedicated report identified by the external_customer_id field.

Understanding EoR Report Structure

For EoR platforms, the system creates separate contribution reports for each customer:

• Separate reports per customer: Each external_customer_id gets its own contribution report, even if they share the same employer
• Customer-specific filtering: You can filter reports by external_customer_id when retrieving contribution reports
• Consistent identification: The same external_customer_id appears in both the contribution report and all associated employee breakdowns

Processing EoR Contribution Reports

When processing reports as an EoR platform, you should:

1. Filter by customer: Use the external_customer_id parameter when listing reports to process specific customers
2. Maintain customer separation: Keep contributions separated by customer in your accounting system

1
// EoR platform: Process contributions for a specific customer
2
async function processEoRCustomerContributions(customerId) {
3
  // Get all contribution reports for this specific customer
4
  const response = await kotaClient.get('/contribution_reports', {
5
    params: {
6
      external_customer_id: customerId,
7
      status: 'finalized'
8
    }
9
  });
10
11
  const reports = response.data.data;
12
13
  for (const report of reports) {
14
    console.log(`Processing report ${report.id} for customer ${report.external_customer_id}`);
15
16
    // Get employee breakdowns for this customer's report
17
    const breakdowns = await getEmployeeBreakdowns(report.id);
18
19
    // Process each employee's contributions for this customer
20
    for (const breakdown of breakdowns) {
21
      await processCustomerEmployeeContributions(breakdown, customerId);
22
    }
23
  }
24
}
25
26
// Process employee contributions with customer context
27
async function processCustomerEmployeeContributions(breakdown, customerId) {
28
  const { employee_id, health_insurance, external_customer_id } = breakdown;
29
30
  // Process contributions with customer context
31
  if (health_insurance) {
32
    await processCustomerContributions(customerId, employee_id, health_insurance.employer_contributions, 'employer');
33
    await processCustomerContributions(customerId, employee_id, health_insurance.employee_contributions, 'employee');
34
  }
35
}