Payroll

Overview

Payroll APIs enable businesses to submit, track, and manage payroll payment requests efficiently, simplifying salary disbursements and payroll processing operations.

These APIs support employee salary payments, recurring payroll cycles, scheduled salary disbursements, and other payroll-related payment workflows. They provide capabilities to submit payroll requests, retrieve processing statuses, and cancel eligible scheduled payroll transactions.

Processing behavior may vary depending on the selected bank, payroll configuration, transaction status, and applicable settlement requirements.

Available services

• Process Payroll – Submit a payroll payment request to the bank for processing.
• Payroll Enquiry – Retrieve the latest processing status of a submitted payroll request, where supported by the applicable bank and API.
• Cancel Payroll – Request cancellation of an eligible payroll transaction at least 24 hours before its scheduled value date, subject to the applicable bank's cancellation rules.

Payroll APIs provide greater visibility, control, and traceability throughout the payroll lifecycle while accommodating bank-specific processing, cancellation, and settlement requirements.

Payroll processing lifecycle

The payroll processing lifecycle consists of the following steps:

1. Process Payroll – Submit the payroll payment request to the bank.
2. Payroll Enquiry – Retrieve the latest processing status after the payroll request has been submitted, where supported.
3. Cancel Payroll – Request cancellation of an eligible scheduled payroll transaction at least 24 hours before its value date.

The Payroll Enquiry service supports tracking payroll requests for banks that provides a dedicated enquiry mechanism.

The Cancel Payroll service enables users to request cancellation of eligible payroll transactions before the applicable cancellation deadline.

Important: The initial Process Payroll response may not provide immediate confirmation of the final payment outcome. Similarly, submitting a cancellation request does not necessarily confirm that the payroll has been cancelled. Refer to the latest API response definitions and bank-specific integration requirements to determine the applicable processing and cancellation behavior.

When to perform payroll enquiry

The timing and frequency of payroll enquiries depend on the payroll payment type, the response returned by the Process Payroll API, and the applicable bank's processing behavior.

Initial enquiry

• Do not perform Payroll Enquiry when the Process Payroll response returns StatusCode: Failed.
• If the response returns StatusCode: Processing or StatusCode: Request_Timeout, perform the first Payroll Enquiry 30 minutes after the payroll request was submitted.
• Follow the applicable bank's API response definition if it specifies different status-handling or enquiry requirements.

Same-day payroll

For same-day payroll payments:

• Start the enquiry process 30 minutes after submission when the initial status is Processing or Request_Timeout.
• Perform subsequent enquiries at hourly intervals.
• Continue enquiries for up to 24 hours.
• Stop routine polling when the applicable final status, Completed or Failed, is received, while accounting for the recommended reversal-monitoring period.

Scheduled payroll

For scheduled payroll payments:

• Perform Payroll Enquiry once per day at end of day (EOD) until the payroll value date approaches.
• On the value date, switch to hourly enquiries.
• Continue hourly enquiries for up to 24 hours until Completed or Failed is received.
• Follow any additional bank-specific processing instructions where applicable.

If a scheduled payroll needs to be cancelled, use the Cancel Payroll service within the permitted cancellation window rather than relying on the enquiry process to stop the payment.

Cancelling a payroll transaction

The Cancel Payroll API allows users to request cancellation of an eligible payroll transaction before its scheduled value date.

Cancellation requirements

• Submit the cancellation request at least 24 hours before the payroll value date.
• Ensure that the payroll transaction is eligible for cancellation under the applicable bank's rules.
• Submit the cancellation request using the Cancel Payroll API.
• Check the API response to determine whether the cancellation request was accepted or rejected.
• Where supported, use Payroll Enquiry to verify the resulting payroll status.

Cancellation handling

A cancellation request may be rejected if the cancellation deadline has passed, the payroll has already entered a non-cancellable processing stage, or the applicable bank's requirements are not satisfied.

Important: Submitting a cancellation request does not, by itself, confirm that the payroll has been cancelled. The integration should rely on the applicable API response and subsequent status confirmation, where supported, to determine the outcome.

If cancellation is rejected, review the response and follow the applicable bank's procedures. Do not assume that the payroll has been stopped unless the cancellation outcome is confirmed.

Detecting payroll payment reversals

A payroll payment may initially appear successful and subsequently be reversed because of a bank-side processing issue or another applicable rejection or reversal scenario.

To help identify potential reversals, it is recommended to perform an additional Payroll Enquiry at EOD on the third and fourth day after the payroll value date, where the bank supports status updates through the enquiry service.

Important: Even when a payroll payment has reached an apparently final successful status, the additional third- and fourth-day enquiries are recommended to account for potential reversal scenarios. A reversal may cause a payment that was initially reported as Completed to subsequently become Failed.

Possible post-submission failures

A payroll request may fail after it has been successfully submitted to the bank. Possible scenarios include:

• Technical errors at the bank – The bank encounters an issue while processing the payroll request.
• Insufficient balance – The bank rejects a payroll payment because sufficient funds are not available.
• Payroll payment rejection – One or more payroll payments are rejected during bank-side validation or processing.
• Payment reversal – A payment initially reported as successful is subsequently reversed because of a bank-side or settlement-related issue.

Therefore, a successful initial submission or an interim successful status should not automatically be treated as the definitive outcome of every payroll payment. Follow the applicable enquiry process and bank-specific status-handling requirements.

Cancellation is a separate operation from payment failure. A payroll cancellation request must be handled according to the Cancel Payroll API response and the applicable bank's rules.

Expected processing timeline

Same-day payroll payments may be processed within an average of approximately 30 minutes to 1 hour. However, the actual processing and settlement time, as well as the time required to receive a final status, can vary by bank and settlement cycle.

For example, Saudi National Bank (SNB) may provide a status update after 8:00 PM, following settlement.

Payment reversals may also affect the final status several days after the payroll value date.

These scenarios mean that the final payroll payment status may take longer than the typical 30-minute processing window.

For scheduled payroll cancellations, the cancellation request must be submitted at least 24 hours before the value date. The time required to receive cancellation confirmation may vary according to the bank's processing behavior.

Processing timelines are indicative and should not be treated as guaranteed settlement or cancellation commitments. Refer to the applicable bank's processing guidelines for the latest requirements.

Final payroll payment status

The following statuses should be handled according to the applicable API response definition:

• StatusCode: Failed in the Process Payroll response, treat the payroll request as failed and do not perform an enquiry, unless bank-specific documentation specifies otherwise.
• StatusCode: Completed in the Payroll Enquiry response, treat the relevant payment as completed, subject to the applicable reversal-monitoring requirements.
• StatusCode: Failed in the Payroll Enquiry response, treat the relevant payment as failed.

Cancellation outcome

The outcome of a Cancel Payroll request must be determined using the response definition provided for that API.

• Cancellation accepted – Handle the request according to the cancellation response and verify the resulting payroll status where supported.
• Cancellation rejected – Review the response and follow the applicable bank's requirements.
• Cancellation outcome not confirmed – Do not assume the payroll has been cancelled; use the supported status-verification mechanism or follow the bank's prescribed process.

A cancellation response and a payment status represent different aspects of the payroll lifecycle. Do not interpret cancellation acceptance as proof that funds have been returned or that a previously completed payment has been reversed.

Important: A payroll payment initially reported as Completed may subsequently be reversed. Where supported, additional enquiries at EOD on the third and fourth day after the value date are recommended to identify potential reversals.

Recommended payroll handling approach

For reliable payroll processing, implement the following sequence:

1. Submit payroll: Submit the payroll request using the Process Payroll API.
2. Handle submission failure: If the response is Failed, handle the request as failed and do not perform an enquiry, subject to the applicable bank-specific rules.
3. Start status enquiries: If the response is Processing or Request_Timeout, wait 30 minutes before performing the first enquiry, where applicable.
4. Track same-day payroll: Perform enquiries hourly for up to 24 hours.
5. Track scheduled payroll: Perform enquiries once daily at EOD until the value date.
6. Monitor on the value date: Perform enquiries hourly for up to 24 hours, where applicable.
7. Cancel eligible payroll: If a scheduled payroll needs to be cancelled, submit a Cancel Payroll request at least 24 hours before the value date.
8. Verify cancellation: Check the cancellation response and verify the resulting payroll status through Payroll Enquiry, where supported.
9. Monitor potential reversals: Perform additional enquiries at EOD on the third and fourth day after the value date, where supported.
10. Establish the outcome: Stop routine polling once the applicable final status has been established, while retaining any required reversal-monitoring checks.

Payroll status handling summary

API updates and announcements

The introduction or enhancement of Payroll APIs reflects changes in bank-side payroll processing capabilities. As banks introduce new services or change their processing behavior, SingleView may update the corresponding API documentation.

Where a bank-side change does not require a modification to the existing API contract, the change may be communicated separately through email announcements so that existing users are aware of relevant bank or processing changes.

Integrators should review the latest API documentation and bank-specific announcements before implementing changes to payroll submission, enquiry frequency, cancellation eligibility, status interpretation, or reconciliation processes.