Payroll APIs V1 vs V2: What's Changed?

Overview

Payroll V2 introduces an enhanced version of the SingleView Payroll APIs, with updated endpoint URLs, improved request and response structures, clearer response and error handling, and better performance.

This page outlines the key differences between Payroll V1 and V2 to help developers understand the changes and prepare their integrations for the updated APIs.

Payroll V2 covers the following operations:

• Process Payroll: Submit payroll payment requests for processing.
• Payroll Enquiry: Retrieve the latest available status and processing details of submitted payroll transactions.
• Cancel Payroll: Submit cancellation requests for eligible scheduled payroll transactions.

Key Improvements in V2

Updated API Endpoints

Payroll V2 introduces updated endpoint URLs for payroll operations. Integrations using V1 must be updated to use the corresponding V2 endpoints.

Enhanced Request and Response Structure

Payroll V2 introduces an improved structure for request and response payloads, making payroll information more consistent and easier to process.

Developers should review the updated payload formats and adjust their request-building and response-parsing logic accordingly.

Clearer Response and Error Handling

V2 provides improved clarity in transaction responses and error details, helping developers identify processing statuses, understand failures, and implement appropriate error-handling logic.

Use the Payroll Enquiry API to retrieve updated payroll transaction statuses where supported.

Improved Performance

Payroll V2 includes performance optimizations designed to make API interactions more efficient and provide a smoother integration experience.

API Comparison

Quick Links

Payroll V2

• Process Payroll V2
• Payroll Enquiry V2
• Cancel Payroll V2

Payroll V1

• Process Payroll V1
• Payroll Enquiry V1
• Stop Payroll V1

Migration Considerations

Before migrating an existing integration from V1 to V2, review the following:

1. Update endpoint URLs: Replace the V1 endpoint paths with the corresponding V2 endpoint paths.
2. Review request payloads: Update request-building logic to match the V2 structure and mandatory field requirements.
3. Update response parsing: Ensure your application reads the correct response objects and fields returned by V2.
4. Review error handling: Update logic to interpret V2 status codes, error codes, and descriptive messages.
5. Validate payroll workflows: Test payroll submissions, enquiry responses, failed requests, and cancellation scenarios in the sandbox environment.
6. Verify integration settings: Confirm endpoint URLs, authentication headers, and other required headers against the relevant V2 documentation.

Recommendation

New integrations should use Payroll V2. Existing V1 integrations should be reviewed and updated to accommodate the new endpoint URLs and revised request and response structures before switching to V2.

Refer to the individual API reference pages for the latest specifications, mandatory fields, status definitions, and applicable bank-specific requirements.