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.

Let's discuss these scenarios:

• 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.

To check the eligibility of an employee with Available Net amount for advance request and hours worked:

1. Query the employee to know the assignmentId value.
2. Perform a POST operation on this URL, providing the assignmentId and effectiveDate attributes in the request body.
3. 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:

1. Query the employee to know the assignmentId value.
2. Perform a POST operation on this URL, by providing the assignmentId, effectiveDate, and the amount attributes in the request body.
3. 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"
                          }
              }