This article explains how the OrangeHRM-BizPay Central Connector moves data between the two systems, what you need to do to keep it running smoothly, and how to fix the errors you may see.
How the integration works
OrangeHRM manages employee information, while BizPay Central processes payroll using payroll codes and salary components to calculate employee payments and generate pay slips.
The integration connector facilitates data exchange between the two systems. Each data type is transferred in one direction only, with OrangeHRM serving as the source of employee information and BizPay Central serving as the source of payroll information.
For BizPay Central to process payroll accurately, each employee must have a complete and accurate employee record. This includes essential information such as department, job title, employment category, and statutory details, including NIS and TRN.
Therefore, it is important to ensure that all required employee information is entered correctly and kept up to date in OrangeHRM to support successful synchronization and accurate payroll processing in BizPay Central.
| Data | Direction | When it syncs |
|---|---|---|
| New employees | OrangeHRM → BizPay Central | At five-minute intervals |
| Employee updates | OrangeHRM → BizPay Central | At five-minute intervals. Changes to job details are sent on their effective date |
| Master data (sub units, job titles, employment statuses) | OrangeHRM → BizPay Central | Whenever a change is detected in the master data |
| Pay slips | BizPay Central → OrangeHRM | Once a day, for closed payroll cycles. Saved as PDFs in the Salary tab attachments |
| Salary components | BizPay Central → OrangeHRM | Weekly (configurable frequency), displayed in the Salary tab. |
| Synchronization status emails | OrangeHRM → email | Daily |
The integration supports one-way data synchronization from OrangeHRM to BizPay Central. Any changes or new master data added directly in BizPay Central will not be transferred back to OrangeHRM or synchronised through the integration.
Field mapping
The following are the fields that are synchronized between OrangeHRM and BizPay Central.
Employee data (OrangeHRM to BizPay Central)
| OrangeHRM field | BizPay Central field | Required | Notes |
| Personal Details - Employee ID | Employee ID | Required | |
| Personal Details - First Name | First Name | Required | |
| Job - Payroll name | Payroll | Required | |
| Personal Details - Middle Name | Middle Name | Optional | |
| Personal Details - Last Name | Last Name | Required | |
| Contact Details - Address Street 1 | Street/District | Required | |
| Contact Details - Address Street 2 | Town/Post Office | Optional | |
| Contact Details - City | Parish | Optional | |
| Personal Details - Date of Birth | Date of Birth | Required | |
| Job Details - Sub Unit | Department | Required | The sub unit code is matched with the department code. Changes are sent on their effective date |
| Job Details - Joined Date | Employment Date | Required | Changes are sent on their effective date |
| Personal Details - Main ID | NIS | Required | Format X123456, a capital letter followed by six digits. |
| Personal Details - Other ID | TRN | Required | Nine digits |
| Job Details - Job Title | Job Title | Required | Matched by name in both systems. Changes are sent on their effective date |
| Personal Details - Gender | Gender | Required | M or F only |
| Job Details - Employment Status | Employment Category | Required | Changes are sent on their effective date |
| Contact Details - Work Email | Optional | ||
| Contact Details - Mobile | Phone Number | Optional | Format (XXX) XXX-XXXX |
Salary data (BizPay Central to OrangeHRM)
Only the standard pay codes you agree with us during implementation are synchronized.
| BizPay Central field | OrangeHRM field | Notes |
| Employee ID | Personal Details - Employee ID | Used to match the employee |
| Payroll Code | Manage Salary Components - Component Name | |
| Category | Manage Salary Components - Type | |
| Calculation Method | Manage Salary Components - Value Type | |
| Amount | Salary - Amount / Percentage | |
| Rate | Salary - Amount / Percentage | |
| Suspend | If a payroll code is suspended in BizPay Central, the salary component is not created in OrangeHRM |
Master data (OrangeHRM to BizPay Central)
| OrangeHRM | BizPay Central |
| Sub Unit ID and Sub Unit Name | Department Code and Department Name |
| Job Title ID and Job Title Name | Job Title Code and Job Title Name |
| Employment Status ID and Employment Status Name | Employee Category Code and Employee Category Name |
Guidelines for Successful Synchronization
To ensure employee information is synchronized correctly between OrangeHRM and BizPay Central, follow these guidelines.
- Maintain employee information in OrangeHRM. Make all employee-related changes in OrangeHRM. Avoid updating employee details directly in BizPay Central, as changes made there will not be reflected in OrangeHRM.
- Maintain master data in the appropriate systems. Add new sub units, job titles, and employment statuses in OrangeHRM. These values are automatically synchronized to BizPay Central. Other master data values required by both systems must be configured in each system before they are assigned to employees.
-
Complete all required employee fields. Ensure that every employee record contains the following information: Employee ID, first name, last name, payroll name, date of birth, joined date, sub unit, job title, gender, employment status, address 1, NIS, and TRN.
If your organization does not use NIS, leave this field blank. Do not enter placeholder values such as "N/A". Please inform us during the implementation so that we can configure the NIS field as not required. -
Follow the required data formats. Ensure that employee information follows the required formats accepted by BizPay:
- NIS: One uppercase letter followed by six digits (e.g., X123456).
- TRN: Nine digits.
- Gender: M or F.
- Mobile number: (XXX) XXX-XXXX
- Review the daily synchronization email notification. Check the notifications for details of any employee records that failed to synchronize. Address the reported issues promptly to ensure the affected records can be synchronized successfully.
Salary data
Salary data is synchronized from BizPay Central to OrangeHRM and displayed in the Salary tab of the employee profile. Only standard payment codes are synchronized from BizPay.
During implementation, please specify which salary components should be synchronized to OrangeHRM. If you require salary data to be synchronized from OrangeHRM to BizPay Central, please inform us during implementation so that the required configuration can be completed.
Attendance pay hours
If you use the OrangeHRM Attendance module, pay hours are transferred to BizPay Central through a CSV file rather than automatic synchronization. At the end of each pay period, generate the Pay Hours report in OrangeHRM and import the exported CSV file into BizPay Central. The pay codes included in the report are mapped to the corresponding BizPay Central pay codes during implementation. Therefore, you do not need to enter pay hours manually in BizPay Central.
Synchronization Email Notifications
OrangeHRM sends daily synchronization email notifications in either summary or detailed format to the email addresses configured for your integration. These notifications provide information about successfully synchronized records and any records that failed to synchronize.
Checking sync status and fixing errors
OrangeHRM sends daily integration error logs to the email addresses configured for your integration.
You can also check the synchronization status at any time in OrangeHRM. Admin users can access the BizPay Integration - Audit Report to view the synchronization status of each record and identify any errors.
If an error is identified in the report or an error notification email, follow these steps to resolve it:
- Open the employee's profile in OrangeHRM and correct the relevant data.
- Navigate to the BizPay Integration - Sync Information tab within the employee's profile.
- After a few minutes, check the tab to verify that the latest synchronization was successful.
BizPay Integration - Sync Information tab
Each employee profile has a BizPay Integration - Sync Information tab. It shows:
- The date and time of the last sync
- Whether the last sync succeeded or failed
- The reason for the failure, if the last sync failed
- Skip-sync, which you can use if an employee does not need to be synced to BizPay Central
- Re-sync Employee, which you can use when an employee’s data needs to be synced again
Common errors and how to fix them
If a synchronization failure is reported, locate the relevant employee or master data record in OrangeHRM, identify and correct the issue using the guidance in the table below
| What you see | Why it happens | What to do |
|---|---|---|
| A new employee or update does not reach BizPay Central and an error message is received. | A required field is blank | Open the employee in OrangeHRM, complete the required field indicated in the email, and save |
| A record fails and the email points to NIS, TRN, or mobile number | The value is not in the format BizPay Central accepts | Correct the value to the required format (NIS X123456, TRN nine digits, mobile (XXX) XXX-XXXX) and save |
| A record fails because of a job title, sub unit, or employment status | The value on the employee does not match what BizPay Central holds. Job titles are matched by name | Check that the value exists in OrangeHRM master data with the same name you expect in BizPay Central, correct the employee record, and contact support if it still fails |
| An employee appears twice or will not match between systems | The same person has a different Employee ID in each system | Make the Employee ID identical in both systems. Contact support if you are not sure which record is correct |
| A change is not yet visible in BizPay Central | The change has a future effective date. Job title, sub unit, employment status, and joined date changes are sent on that date | No action needed. Check the effective date you entered |
| A change made in BizPay Central is missing in OrangeHRM, or a new master data value is not appearing | Employee data and master data only flow from OrangeHRM to BizPay Central | Make the change in OrangeHRM instead |
| A pay slip is missing from the employee’s Salary tab | The payroll cycle has not been closed in BizPay Central, or the daily sync has not run yet | Confirm the cycle is closed in BizPay Central, then check again after the next daily sync |
| A salary component is missing from the Salary tab | The component is not on the list agreed for synchronization, its payroll code is suspended in BizPay Central, or the weekly sync has not run yet | Ask your BizPay Central administrator to check the payroll code. To add a component to the sync, contact support |
| Pay hours do not import correctly, or land under the wrong pay code | A pay code in the OrangeHRM export is not mapped to the right BizPay Central pay code | Contact support to review and update the pay code mapping, then re-run the import |
| Nothing is syncing at all (on-site hosting only) | The connection is blocked, for example after a VPN or firewall change | Check that the OrangeHRM and BizPay Central IP addresses provided during implementation are still whitelisted, then contact support |
Need help?
If an error is not covered in the guidance above or persists after you have made the necessary corrections, please contact your OrangeHRM support representative or email goldsupport@orangehrm.com
When contacting support, include the relevant Employee ID and attach the latest synchronization email notification to help the support team investigate the issue more efficiently.