Fidelity Payroll Web Services Documentation

Third Party Integration with Fidelity Payroll

Entering the same data in multiple systems takes time and costs money which is why Fidelity Payroll provides a service that enables the other systems you use to send data to Fidelity Payroll. Through a web services API using SOAP or REST protocols, once data is entered into the third party application it is sent to Fidelity Payroll and is updated "near real time".

  How it works

Employee level transactions are entered into applications such as HR or Benefits systems. Once submitted in the source system, this data is sent to Fidelity in XML or JSON format "near real time". If the data passes validations for data structure and business rules, it is updated in Fidelity Payroll. If the data does not pass the validations, the source system receives an error.

  

Web Service Diagram

Authentication

All Web Service calls to Fidelity Payroll systems are authenticated for security purposes by the Fidelity's Enterprise Service Gateway (ESG). ESG mandates usage of Two-Way SSL mutual authentication, which means that the client (or HR Vendor) application, verifies the identity of the server application (Fidelity's ESG) and then the server verifies the identity of the client application. The Two-Way SSL authentication requires an exchange of SSL certificates between the HR Vendor and the Fidelity's ESG.

Fidelity Payroll will be working with the HR Vendors facilitating the Web Service Integration with the Fidelity's Payroll System via the secured gateway.

SSL Certificate

It is recommended that the HR Vendor obtain a SSL certificate from a well-know Certificate Authority. The details in the SSL certificate will be used for determining the HR Vendor name and his/her identity in a Web Service transaction.

ESG URL

ESG requires that the client application construct the URL of the Web Service end point per below guideline. URL has three parameters, viz. target, query, and the enviroment.

ESG Endpoint:

https://{fidelity-esg-hostname}/wss/proxy?TARGET={Web Service Path}&QUERY={URI Encoded Query Parameters}&ENV={Payroll System Environment}

Parameter Description Example
TARGET

The value of this parameter corresponds to the path on the REST (or SOAP) transaction.

For GET-PayrollMasterData in REST, it is /fprExtWS/ws/rest/PayrollMasterData

QUERY

The value of this parameter is URI Encoded concatinated string of the query parameters of the REST transaction.

For GET-PayrollMaster in REST, if query parameters are EmpNo=123456, ClientID=9876, & PayGroup=ABC Weekly, then value of this parameter is EmpNo%3D123456%26ClientID%3D9876%26PayGroup%3DABC%20Weekly

ENV

The value of this parameter corresponds to the enviroment of the payroll system.

For QA payroll system, the value is fprExtWS.uat


Example of a complete URL for GET-PayrollMasterData:

https://{fidelity-esg-hostname}/wss/proxy?TARGET=/fprExtWS/ws/rest/PayrollMasterData&QUERY=EmpNo%3D123456%26ClientID%3D9876%26PayGroup%3DABC%20Weekly&ENV=fprExtWS.uat

Authorization

In order to succesfully perform a Web Service transaction, the HR Vendor should be authorized in the Fidelity Payroll System to perform such a operation (or call) on behalf of their mutual payroll / hr client. Such authorization is granted based on agreement between or among the HR Vendor, Fidelity Payroll and their mutual client.

Authorization is granted at a transaction level per client basis. It means that if a HR Vendor has multiple clients with the payroll, then it is possible that the extend of access may be different for each client. The details in the HR Vendor's SSL Certificate are used in his/her identification to determine or grant access to the Payroll transactions.

Transaction Types

Fidelity Payroll supports these eight transaction types:

  • Personal Information
  • Job Information
  • Status Updates
  • Salary and Wage Changes
  • Earnings (recurring)
  • Deductions (recurring)
  • New Hire/Re-hire
  • Emergency Contacts
Get Operation

A Get Web Service call returns an employee's information on each of the transaction. For Get Operation:

  • pass either employee's Employee Number or SSN as a key field, along with the employee's organization identifier and pay group
  • in REST, use GET Http Method
  • in SOAP, use GetPayrollMasterData Method
  • expect to return only the datafields of the authorized transaction in the system
Change Operation

A Change Web Service call will update or insert an employee's information on each of the transaction. For Change Operation:

  • pass either employee's Employee Number or SSN as a key field, along with the employee's organization identifier and pay group
  • in REST, use POST Http Method
  • in SOAP, use ChangePayrollMasterData Method with Action as "Change"
  • expect to return the status and errors if any in the response
  • below validations are performed
    • required (a required "Yes" means that the data field cannot be set to an empty value)
    • length
    • data format and it character contents
    • simple business rules
    • complex or combinational business rules
Hire Operation

A Hire Web Service call will process a hire or re-hire of an employee along with other transactions. For Hire Operation:

  • pass employee's SSN as a key field, along with the employee's organization identifier and pay group
  • in REST, use PUT Http Method
  • in SOAP, use ChangePayrollMasterData Method with Action as "Hire"
  • expect to return the status and errors if any in the response
  • below validations are performed
    • required (a required "Yes" means that the data field must be sent)
    • length
    • data format and it character contents
    • simple business rules
    • complex or combinational business rules