What Data is Needed to Integrate Earned Wage Access with Timekeeping, Payroll, and ERP?

What Data is Needed to Integrate Earned Wage Access with Timekeeping, Payroll, and ERP?

To integrate Earned Wage Access with timekeeping, payroll, and ERP, businesses need at least five data groups: employee records, approved work hours, payroll periods and rules, adjustments or deductions, and early wage access transactions. All must use a unified employee ID, include status, update timestamps, data versioning, and audit logs. A good architecture not only transmits data quickly but also prevents duplicate payments, handles late data corrections, and reconciles each transaction.

> Note: This article presents a reference architecture for an Earned Wage Access (EWA) system. Field names, statuses, approval flows, and actual accounting methods need to be confirmed by Nhan Kiet and the business during the integration survey phase.

> Terminology Explanation: EWA (earned wage access) · HRIS/HRM (human resource information system) · ERP (enterprise resource planning) · payroll (salary calculation) · API (application programming interface) · batch (batch processing) · SFTP (secure file transfer protocol) · idempotency (deduplication: sending multiple times results in one outcome) · UAT (user acceptance testing) · go-live (official operation) · rollback (reversion) · webhook/callback (automatic notifications between systems) · token (data replacement code) · data dictionary · system of record · retry · timeout.

Why Must EWA Connect Simultaneously with Timekeeping, Payroll, and ERP?

EWA needs to answer three questions before allowing a worker to receive money:

1. Is this person currently working and part of the program?

2. Up to the current time, how much eligible wage have they generated?

3. After previous transactions and necessary withholdings, how much can they still receive?

HR systems typically confirm identity and employment status. Timekeeping systems record the number of approved work hours. Payroll holds wage rules, payroll periods, and adjustments. ERP or accounting systems serve for recording, reconciliation, and settlement. Payment systems provide the final transfer status.

If only one source is connected, EWA might see the worker but not know the approved work hours; or see the hours but not know if the payroll period is closed; or know the money has been transferred but payroll hasn't received the transaction for reconciliation. Therefore, the most important point is not just “connecting the API,” but establishing a consistent data chain from completed work to settled transactions.

1. Overall Data Architecture

A reference architecture can be organized as follows:

flowchart TD
    A["HRIS: employee"] --> D["Integration layer"]
    B["Timekeeping: approved hours"] --> D
    C["Payroll: periods and rules"] --> D
    D --> E["EWA limit calculation engine"]
    E --> F["EWA application"]
    F --> G["Payment system"]
    G --> H["Payroll, ERP, and accounting reconciliation"]
    H --> E

Each data domain should have one system of record. HRIS, payroll, and EWA should not modify the same attribute in three different ways.

2. Minimum Employee Data List

Do not synchronize the entire HR record just because “it might be needed.” The appropriate principle is to collect and transmit only the necessary data for the defined purpose.

Full account numbers should only exist in domains that truly need them for payments, with appropriate permissions and protection. Test environments should use dummy or masked data, not replicate production data.

3. Timekeeping Data and Approval Status

EWA should not just receive a “total monthly hours” figure. The system needs enough information to know which data has been confirmed and which can still change.

Commonly needed fields include:

• employee_id: unified employee ID;

• work_date: work date;

• shift_id: shift code, if managed by shifts;

• regularhours, overtimehours: regular and overtime hours;

• attendance_status: present, on leave, absent, or corresponding status;

• approval_status: pending, approved, rejected, adjusted, or locked;

• approvedby, approvedat: approver and approval time if policy requires;

• sourceupdatedat, record_version: timestamp and record version;

• source_system: data source system.

Why is the “approved” status important?

A swipe card entry does not necessarily mean valid work hours. Employees might forget to clock out, register the wrong shift, or have adjustments after manager approval. Businesses need to clearly define which status counts towards the EWA limit (see What is Approved Work?).

Example of a sample record:

{
  "employee_id": "EMP-000123",
  "work_date": "2026-08-18",
  "shift_id": "SHIFT-A",
  "regular_hours": 8,
  "overtime_hours": 0,
  "approval_status": "APPROVED",
  "source_updated_at": "2026-08-19T02:15:30Z",
  "record_version": 3
}

This is a safe data sample for illustration, not the official API specification for Earned Wage Access.

4. Payroll Data and Adjustments

Payroll data helps convert “approved work hours” into “eligible wage portions.” The dataset typically includes:

• payroll period ID payperiodid and start, end times;

• payroll group and pay cycle;

• wage calculation basis or unit price needed for agreed formulas;

• income code earning_code;

• related adjustments, withholdings, or deductions;

• work hour closing date and payroll lock time;

• payroll period status: open, processing, locked, or settled;

• currency and rounding rules;

• applied formula/policy version.

Not every component on the payslip is counted towards the EWA limit. Basic salary, allowances, overtime, bonuses, or commissions have different certainty levels and approval times. Businesses must establish a rule table specifying which items are counted, from which status, and with what limits.

What Columns Should a Rule Table Have?

Actual values in this table must be confirmed by the business and the implementing unit. Do not infer from item names.

5. Early Wage Access Transaction Data

Each early wage access request should be an independently traceable transaction.

A reference transaction lifecycle includes: CREATED → VALIDATING → PROCESSING → SUCCEEDED or FAILED. If the payment result is unclear, the transaction should be in UNKNOWN or equivalent status for tracing; it should not default to failure and automatically transfer money again. The system also needs refund and reconciled statuses when business arises.

6. Choosing API, File Batch, or Manual Synchronization?

There is no one-size-fits-all method for every business. Multiple methods can be combined based on the maturity of each system.

If using HTTP API, businesses can describe the integration contract using OpenAPI Specification to agree on endpoints, data structures, and responses. OpenAPI is a standard for describing HTTP APIs; it is a useful technical choice, not a mandatory condition for implementing EWA.

7. Identification and Duplicate Data Prevention

Incorrect identification is one of the most dangerous risks. Emails, phone numbers, or account numbers can change, so they are unsuitable as primary employee keys.

Recommendations:

• use an immutable employee_id within a business;

• combine with employerid or legalentity_id if the platform serves multiple units;

• do not reuse codes of former employees for new ones;

• maintain a mapping table when HRIS and payroll use different code sets;

• record effective dates for changes in payroll group, unit, and employment status;

• check duplicates by business key, not just by similar content.

With file batches, each file should have a batch code, creation timestamp, total record count, and checksum. With APIs, each transaction creation request should have an idempotency_key.

8. Idempotency and Reconciliation: Two Different Layers of Protection

Idempotency ensures that a request sent multiple times results in only one business outcome. For example, an application times out after sending a money transfer command. When resent with the same idempotency_key, the system should return the old transaction or its status, rather than creating another payment.

Reconciliation checks whether systems record the same transaction (linked to the Earned Wage Access process from timekeeping to reconciliation). A suitable model is three-way reconciliation:

1. transaction in the EWA platform;

2. result from the bank or payment unit;

3. payroll/ERP data or approved settlement records.

Reconciliation reports should at least indicate:

• fully matched transactions;

• present in EWA but no payment result yet;

• payment result exists but missing in payroll/ERP;

• discrepancies in amount, fee, recipient, or payroll period;

• refunded transactions not yet updated;

• duplicate records or out-of-order updates.

Each discrepancy needs an owner, processing status, and closure evidence.

9. Error Handling, Retry, and Alerts

Not all errors should be automatically retried.

Every request should have a correlation_id for cross-system tracing. Alerts need to contain transaction ID, error type, timestamp, source system, and next processing step, but should not include full passwords, API keys, or sensitive data in logs.

10. Sample API Request Illustration

{
  "idempotency_key": "ewa-demo-20260818-0001",
  "employee_id": "EMP-000123",
  "pay_period_id": "2026-08",
  "requested_amount": 1000000,
  "currency": "VND",
  "source_data_version": "attendance-v18_payroll-v6",
  "requested_at": "2026-08-18T09:20:00+07:00"
}

Responses should indicate whether the request is accepted, rejected, or requires further processing; and return transactionid, status, reason code, and correlationid. Full account data or unnecessary information should not be returned.

API specifications should clearly define:

• authentication and authorization methods;

• API versioning and change policies;

• date-time format, time zone, and currency unit;

• money precision and rounding rules;

• error code catalog;

• timeout and retry policies;

• callback/webhook signature/verification;

• load limits;

• idempotency rules;

• status and log retention time.

11. Security and Data Protection by Design

Employee data, payroll, recipient accounts, and transaction histories are highly sensitive. Integration design should include:

• role-based access and least privilege principle;

• data encryption in transit and at rest;

• centralized secret management, no access keys in source code or logs;

• separate development, testing, and production environments;

• dummy or masked test data;

• access and configuration change logs;

• data retention periods, deletion processes, and data subject request handling;

• supplier evaluation and data sharing scope;

• incident response, notification, and investigation plans.

In Vietnam, design and operation need legal review under the Personal Data Protection Law No. 91/2025/QH15 and Decree 356/2025/ND-CP, both effective from January 1, 2026. Records, messages, and electronic documents also need consideration under the Electronic Transactions Law 2023 and related sectoral regulations.

12. UAT Checklist Before Go-Live

UAT should not just check “file received” or “API returns 200” (included in the 90-day EWA pilot plan). It needs to test enough business scenarios and operational errors.

Employee and Participation Conditions

• [ ] Employee is working and eligible.

• [ ] New employee not yet effective.

• [ ] Employee on leave or terminated.

• [ ] Employee changes legal entity, payroll group, or employee ID.

• [ ] Change recipient account through correct verification flow.

Timekeeping and Limits

• [ ] Pending work hours are not counted if policy requires approved hours.

• [ ] Approved work hours correctly change the limit.

• [ ] Adjusted or revoked approved hours are recalculated correctly.

• [ ] Older data arriving after newer data does not overwrite wrong versions.

• [ ] Work hour closing date, time zone, and overnight shifts are handled correctly.

Transactions and Payments

• [ ] Resending with the same idempotency_key does not create two transactions.

• [ ] Insufficient limit returns the correct reason.

• [ ] Payment system timeout and unclear results do not cause a second transfer.

• [ ] Failed, refunded, and reversed transactions are updated correctly.

• [ ] Limits before and after transactions match the transaction log.

File Batch and API

• [ ] Duplicate files, out-of-order files, and duplicate records are detected.

• [ ] Some record errors do not lose track of processed records.

• [ ] API expired authentication, missing permissions, and load limit breaches return correct errors.

• [ ] Fake or incorrect signature callbacks are rejected.

• [ ] Retry complies with limits and maintains deduplication key.

Payroll, ERP, and Reconciliation

• [ ] Open, locked, and settled payroll periods are handled correctly.

• [ ] EWA transactions are included in payroll period reconciliation records per approved process.

• [ ] Three sources EWA – payment – payroll/ERP match amounts and statuses.

• [ ] Discrepancies trigger alerts and have a processing flow until closure.

• [ ] Reports can trace back from accounting entries to transactions and source data.

Security and Operations

• [ ] Unauthorized personnel cannot view or modify data.

• [ ] Logs do not contain secrets or full sensitive data.

• [ ] Access keys can rotate without prolonged disruption.

• [ ] There is a person on duty, alert channels, and incident handling procedures.

• [ ] There is a rollback plan if go-live encounters serious errors.

13. Technical Documentation Both Parties Need to Finalize Before Implementation

A minimum integration documentation set should include:

1. architecture diagram and responsibility boundaries;

2. data dictionary for each field;

3. mapping table for employee IDs, payroll periods, units, and item codes;

4. API or file specification;

5. status and error code catalog;

6. approved limit calculation rules;

7. deduplication, retry, and late-arriving data handling rules;

8. reconciliation flow and discrepancy report template;

9. access control matrix and security requirements;

10. UAT, cutover, rollback, and post-go-live support plans.

Parties should also conduct data contract testing. When a system changes field names, data types, status catalogs, or business meanings, the pipeline must alert before changes cause incorrect limits outside the production environment.
## 14. Data Nhan Kiet Needs to Supplement Before Official Publication

To accurately reflect the actual capabilities of Earned Wage Access, the Product/IT team needs to confirm:

• supported timekeeping, payroll, or ERP systems;

• current integration methods: API, SFTP, sample files, or other methods;

• actual synchronization cycle and service commitments;

• list of endpoints, data fields, statuses, and error codes allowed for public disclosure;

• authentication, idempotency, webhook, and reconciliation mechanisms in use;

• handling flow for unclear, failed, and refunded transactions;

• limit calculation rules and eligible payroll components;

• technical report templates with personal data removed;

• responsibilities of Nhan Kiet, businesses, and payment partners;

• contact point for integration documentation and UAT support.

Do not disclose partner names, processing times, SLA, or technical features without documented confirmation.

-->

Frequently Asked Questions

Is Real-Time Integration Mandatory for EWA?

No. Businesses can use near real-time APIs, scheduled file batches, or controlled manual processes in pilots. The frequency should match the limit calculation method, data change speed, and operational capability of source systems.

Is Timekeeping Data Alone Sufficient to Calculate EWA Limits?

Usually not. Additional data is needed, such as employee status, payroll periods, wage calculation rules, related adjustments, and EWA transaction history. Recorded work hours also need a clear approval status.

Why Use the Same Employee ID?

A unified identifier helps avoid attributing work hours, wages, or transactions of one person to another. If systems use different codes, businesses need a controlled mapping table with effective dates.

Is Idempotency the Same as Duplicate Transaction Checking?

Related but not entirely the same. Idempotency ensures resending the same request does not create a new business outcome. Duplicate checking can also use other business keys to detect two different codes that are actually one transaction.

Should a Payment Command Be Resent Immediately After Timeout?

A new payment command should not be resent without determining the result of the old one. The system should maintain an unclear status, query by reference code, and only proceed according to the defined process to avoid double payments.

Who Is Responsible for EWA Reconciliation?

Responsibilities must be defined in the operational matrix. Typically, it involves the EWA operations unit, payroll, accounting/finance, IT, and payment partners. Each discrepancy type needs a specific owner.

Conclusion

Integrating Earned Wage Access is not just about pulling a timekeeping file and calculating a percentage. A reliable system requires employee data, approved work hours, payroll rules, and transactions linked by a unified identifier; along with data versioning, idempotency, payment status, reconciliation, and error handling processes.

If your business is evaluating the possibility of connecting Earned Wage Access with existing timekeeping, payroll, or ERP systems, prepare a system diagram, a data dictionary with personal data masked, and business scenarios needing support, then explore Earned Wage Access for businesses to discuss technical integration documentation and suitable pilot scope.

References

• OpenAPI Initiative – OpenAPI Specification

• OpenAPI Specification on GitHub

• Personal Data Protection Law No. 91/2025/QH15

• Decree 356/2025/ND-CP guiding the Personal Data Protection Law

• Electronic Transactions Law No. 20/2023/QH15

---

Author: Ngô Nhã Kỳ — Editor, Nhan Kiet Manpower Supply Co., Ltd.

Earned Wage Access Solutions for Businesses: Hotline 0937.022.655 · Email info@nhankiet.vn · Earned Wage Access for businesses