Request Pay Advance
With the introduction of the Anytime Pay functionality, you can provide your employees with immediate access to a portion of their pay. It's a form of Early Wage Access, based on the number of hours an employee has worked in the current payroll period.
For employees, this functionality provides a simple way to access their available net pay and submit a request, and assures that the funds will be remitted to their account in a timely manner.
As for employers, it offers a completely automated process that calculates the appropriate tax withholdings and remits the payment to the employee. Being fully integrated into the payroll system, it also ensures that the employees' pay calculation is fully regularized at the end of the pay period, in accordance with various regulations. A number of configuration options are built in to give employers greater flexibility. These options let you control when and to whom this capability is to be made available, how to compute the available net, and limit the number of requests an employee can make in a year.
The payAdvances
REST resource provides you with the ability to use the Anytime Pay logic with your own personalized user interface.
Take a look at this image to understand the overall Pay Advance flow.
The prerequest phase consists of performing a number of validations to ensure successful processing of the request. If those conditions are satisfied, then a QuickPay is calculated and it returns the number of hours already worked in the current pay period, as well as the Available Net. This information is then displayed on the Pay Advance page. The employee can then enter the request amount (up to the Available Net). Once the request is submitted, an element entry is automatically created and a flow is submitted to process the individual request.
- Check employee's eligibility for a pay advance
- Process a pay advance request
Check Employee's Eligibility for a Pay Advance
Let's say that Mary Franco wants to request a pay advance, and you need to find out whether she satisfies all the conditions for the advance to be paid on a specific date. If she is eligible, then you also need to find out her Available Net.
- Query the employee to know the
assignmentId
value. - Perform a POST operation on this URL, providing the
assignmentId
andeffectiveDate
attributes in the request body. - Verify the details returned in the response.
Example URL
Use this resource URL format.
POST
hcmRestApi/resources/11.13.18.05/payAdvances/action/checkEligibility
Example Request
Here's an example of the request body in JSON format.
{
"assignmentId" :300100068226459,
"effectiveDate" : "2021-05-27"
}
Example Response
Here's an example of the response body in JSON format.
{
"result": {
"Amount": "1021.50",
"Message": null,
"DisplayMinimumRequestAmount": "10",
"DisplayAmount": "1,021.5",
"MinimumRequestAmount": "10",
"CompanyPolicy": "Plan Information provided by Company",
"CurrencyCode": "USD",
"MessageType": "S",
"CurrencySymbol": "$",
"NextPayCheckDate": "6/1/21",
"HoursWorked": "0"
}
}
Process a Pay Advance Request
You have established that Mary Franco is entitled to request an advance for a maximum of $1021.50. Mary submits a request for $300.
To request an advance for an employee:
- Query the employee to know the
assignmentId
value. - Perform a POST operation on this URL, by providing the
assignmentId
,effectiveDate
, and theamount
attributes in the request body. - Verify the details returned in the response.
Example URL
Use this resource URL format.
POST
hcmRestApi/resources/11.13.18.05/payAdvances/action/requestAdvance
Example Request
Here's an example of the request body in JSON format.
{
"assignmentId" : 300100068226459,
"effectiveDate" : "2021-05-27",
"amount" : 300
}
Example Response
Here's an example of the response body in JSON format.
{
"result": {
"Message": "Your request was submitted successfully. (PAY-1636570)",
"MessageType": "S"
}
}