PaySpace API

1. Import payroll companies.
2. Import payroll company groups.
3. Import or update payroll employees Information.
4. Import pay run period setup in PaySpace.
5. Generate payroll export hours.
6. Store history of the exported hours to payroll with result and identification codes.
7. API Logs
8. Application Service Options

Run the API application by clicking on the Eco PaySpace API shortcut on the desktop or running the application called PaySpaceAPI32 or PaySpaceAPIMs.

1. Select the Settings - PaySpace Tab on the Eco Time PaySpace API Client :

   

   1. Server: The API server URL or IP address and port number as supplied by the client. The current default is the current PaySpace standard.
   2. Authentication Server: The API server URL or IP address and port number as supplied by PaySpace. The current default is the current PaySpace standard.
   3. Client Code: The client code supplied and generated in the customer's PaySpace system.
   4. Client Secret: The client secret supplied and generated in the customer's PaySpace system.
   5. Authorization Token: The token is provided after successful authentication by PaySpace using the client ID and client secret.
   6. API Scope: Leave the default as api.full_access.
   7. Receive Format: The receive format is json and for information purposes only.
   8. Working Company ID: The current selected company's employee payroll hours will be exported to PaySpace. This is a lookup field. Most customer have one in PaySpace. The companies table is populated when the Authentication API is run.
   9. Payroll Period: The current selected payroll period for which employee payroll hours will be exported to PaySpace. This is a lookup field. The Pay Runs table is populated when the Pay Runs API is run.
   10. Stop timed events: This stops time based events. Typically, useful when doing fault finding or analysing data on the client response screen. The generate payroll hours and upload payroll hours is always a manual event, requiring user input via the web interface or desktop application.
   11. A web interface option is available. More information can be found here.
        
2. Select the Settings - API Tab on the Eco Time PaySpace API Client

   

   1. Client API Type: This setting defaults to "PaySpace". and cannot be changed.
   2. Client API Mode: The Production option sets the api to interface with the customer's live PaySpace data. The QAS option sets the api to interface with the customer's test PaySpace data. Please note, each mode has its own settings.
   3. Client API Status: The two options are Enabled or Disabled. The setting has to be "Enabled" to make the PaySpace options avilable in Eco Time's Web Browse menu.
   4. Version Number: This is the API version and cannot be changed,
   5. Log History Records: The log history will be truncated at this number of records (default 2000).
   6. Employee Identifier: Set to identify if the employees in PaySpace are identified by Eco Time's employee number or payroll number.
       
3. Select the Settings - Syncronise Tab on the Eco Time PaySpace API Client

   

   1. Last Sync Date: The last date all companies, frequencies, pay runs and employees were synced.
   2. Last Sync Time: The last time all companies, frequencies, pay runs and employees were synced.
   3. 1st Sync Time: The 1st time of day all companies, frequencies, pay runs and employees will be synced.
   4. 2nd Sync Time: The 2nd time of day all companies, frequencies, pay runs and employees will be synced.
   5. Purge Unverified Employees after (Days) : Employees in the list, which were not found in the PaySpace system, will be removed after this number of days.

1. After the API Client has been configured, run the application and select the Authentication tab.

   

2. A web interface option is available. More information can be found here.

3. Please Note that the "Stop timed events" check box is enabled by default on a new API installation. There is no point running timed events until the configuration has been completed.

4. Select the API button on the bottom right. This will open the API Client window.

   

5. Now Press the Post (POST) button
6. The request window is now populated with text.

   

7. To verify the connection, select the response tab.

   

8. If the response is very short, then there are the following possible errors:

   1. Server connection cannot be opened: The PaySpace server connection details are incorrect or a firewall is blocking the connection.
   2. 403 Unauthorized: The API operator does not have privilege to view the monitored items.
   3. 400 Bad Request: The response at the bottom will indicate {"error":"invalid_client"} which means cleintid or client secret is wrong.
9. The features to the API methods which are available to the API operator are controlled by the PaySpace user privileges. Eco Time needs the following API methods for integration:
   1. Companies and Company Groups
   2. Frequencies
   3. Component Codes
   4. PayRuns
   5. Employees
   6. EditPaySlip
10. The "Do Not Process Reponse" disables any results processing. No tables will be populated. This is typically used for fault finding and in cases where you want to inspect the request packet and result packet.
11. Once you have established and tested that the PaySpace API Client is successfully communicating with the PaySpace API Server, the PaySpace API Client must be loaded with the API information in the following sequence.
    1. Companies and Company Groups. The authentication API populates both.

       

    2. NB!! - The Working Company ID on the Settings - PaySpace Tab must now be set.
    3. Frequencies are for reference purposes only, but they are required for the API upload of the payroll export.

       

    4. A web interface option is available. More information can be found here.
    5. Updating the frequencies displays the following update form:

       

       1. Company ID: The company ID populated by the API (read only).
       2. ID: The GL code as populated by the API (read only).
       3. Description: The GL code description as populated by the API (read only).
       4. Frequency: The frequency description  populated by the API (read only).
       5. Employee group: The Eco Time employee group for this frequence / payroll roll rule. Only the employees' times in this group will be uploaded to payroll, firstly filtered by the company employee group and then by this employee group. 
       6. Setting the employee group at the company level will limit the API's employee import and verification to this specific Eco Time group. This is useful in cases where a company has staff, such as executives, recorded in Eco Time, but they do not use time and attendance clocks. In this scenario, you can create and assign an employee group called for example "Time and Attendance" to the applicable employees. By updating the API's company employee group to this, executives will be excluded from the API processing .
       7. A web interface option is available. More information can be found here.
    6. Component Codes are for reference purposes only. Although it is important that the frequency of the component codes being exported must be the same as the Pay Runs' frequency.

       

    7. Input Type Codes are for reference purposes only. It is important that the correct of input code description must be assigned to the payroll export settings. The input type codes will be exported with each component code and will be visible in the export hours browse.

       

    8. NB!! - The Pay Runs must now be assigned an Eco Time payroll date. How to do this can be found here.
    9. NB!! - The Pay Periods on the Settings - PaySpace Tab must now be set.
    10. Employees
12. Updating a company's employee group:

    
    Select the change button on the companies browse opens the companies update form above.

    1. Employee Group: The Eco Time employee group for this company. Only the employees' times in this group will be uploaded to PaySpace. This is an optional field.
    2. Status: Enables or disables the company will exclude all it and all its employees in Eco Time when generating export payroll hours and uploading these to PaySpace if this company is selected as the working company.
    3. A web interface option is available. More information can be found here.

       

    4. Override Export Settings: When enabled, the Export settings Tabs will override the payroll export codes and settings configured in Eco Time. This allows for different export settings for different payroll companies at one site.
    5. Input Codes: The default input code description for component codes are hours. These fields can be changed, without having to enable the Override Export Setting. The available input code descriptions can be seen here.

1. Start by populating the following lists in order by pressing the API button on the respective tabs:
   1. Employees- Get Employees: The API button brings up the following popup menu:

      

      Select the "Get Employees" option by clicking on this item.

      
      The api employee table contains all the captured employees on the PaySpace system
      The following api employees table fields will be populated

      1. ID: Internal PaySpace Employee ID code
      2. Employee Number: Employee number captured in PaySpace.
         1. This field is used to match the Eco Time employee number and if a match is found, the Eco Time fields will be populated.
         2. If an Emp Number is not imported, no matching attempt will be made.
         3. If an Emp Number is imported, the corresponding Eco Time details will be populated in the api employee table:
            1. Eco Emp Number
            2. Eco Emp First Name
            3. Eco Emp Last Name
         4. If an Emp Number is imported, the API validates the employee surname and employee number.
            1. If employee name and surname do match, an image will appear next to the employee.
            2. If and Eco Time employee is not found in PaySpace, an error image will appear next to the employee.
            3. If employee surname does not match, an error image will appear next to the employee.
            4. The AP tries to match first names. If the first names do not match, the API tries to resolve initials or initials in combination with first names. But if this fails a warning image will appear next to theEmployee.
            5. You can mark the match indicator (see next paragraph). An exempted employee will display the exempted image .
            6. You can override the employee match indicator.
      3. firtName: Employee first name captured in PaySpace.
      4. lastName: Employee last name captured in PaySpace.
      5. Gender: Gender of employee captured in PaySpace.
      6. ID Number: Employee ID or Passport number.
      7. Eco Emp Number: Eco Time employee number matched with PaySpace.
      8. Eco First Name: Eco Time employee firstname matched with PaySpace.
      9. Eco Last Name: Eco Time employee last name matched with PaySpace.
      10. Verified Date: Date verified between API Employee's and PaySpace. If the verified date is older than today's date, then that employee does not exist in PaySpace anymore.
      11. Import Date: Date added to the API Employee's table.
      12. A web interface option is available. More information can be found here.
           
   2. Updating an employee's matching status:

      
      Select the change button on the Employees browse opened the employe update form above.
      
      The user can override the employee's match status. Select Exempt if you will not export this employees hours to payroll and do not require a match to be performed in the future for this employee. Select OK to save your changes.
      
      A web interface option is available. More information can be found here.

   3. Pay Runs

      
      The api Pay Runs table contains all the payroll periods setup in PaySpace.
      The following apipayrollruns table fields will be populated

      1. Description: Payroll Period Description.
      2. Is Main Run: For Eco Time reference, but PaySpace internal use only.
      3. Pay Hours Date: This field must be updated by changing the record and entering Eco Time's corresponding payroll hours date for the payroll run. NB!!. This is a prerequisite in order to generate payroll hours and upload these to PaySpace.
      4. PayDate: For Eco Time reference, but PaySpace internal use only.
      5. Period Start Date: For Eco Time reference, but PaySpace internal use only.
      6. Period End Date: For Eco Time reference, but PaySpace internal use only.
      7. RunStatus: For Eco Time reference, but PaySpace internal use only.
      8. Run Type: For Eco Time reference, but PaySpace internal use only.
      9. Value: For Eco Time reference, but PaySpace internal use only.
      10. Frequency: For Eco Time reference, but PaySpace internal use only.
      11. A web interface option is available. More information can be found here.
           
   4. Updating a payrun record with an Eco Time Payroll date:

      
      Select the change button on the companies browse opens the update companies form above.
      
      The user MUST assign an Eco Time payroll hours date to a PayRun record. The PaySpace API uses this date to generate a payroll export hours and display history for the selected payroll run period. If this date is NOT SET, no hours will be generated or uploaded.
      
      A web interface option is available. More information can be found here.

1. Payroll Export:

   
   The API Client will generate the payroll hours to be uploaded by selecting the Generate Export button.
   The export is generated form Eco Time's payroll hours for the selected pay run's payroll date.
   The Generate Export button can be used multiple times as it will clear the last generated export and recalculate the export from EcoTiem's current payroll hours.
   Select the API button to upload the Export Hours to PaySpace.

   1. Payroll Hours: This is Eco Time's payroll hours date as setup in the Payroll Period (Pay Run) current selected.
   2. Request ID: An internal incremental rerefernce ID created by Eco Time, which is used to upload the payroll hours to PaySpace and match reponses from PaySpace to the transaction.
   3. Payroll No: Eco Time's payroll number. Depending on the Identifier type selected in the settings tab, this can be Eco Time's payroll number or employee number.
   4. First Name: Eco Time's employee First Name.
   5. Surname: Eco Time's employee Surname.
   6. Component Code: Payrol code as configure in Eco Time's time category setup .
   7. Input Type:The default is "Hours" but can be changed in the company's export settings form.
   8. Input Value: Totals payroll hours for the time category in decimal format.
   9. Cost Centre Code: PaySpace required field. Not supported by Eco Time.
   10. Activity Code: PaySpace required field. Not supported by Eco Time.
   11. A web interface option is available. More information can be found here.
        
2. Export History

   
   Once the payroll export has been uploaded to PaySpace, the PaySpace will respond to each component uploaded.
   The hours uploaded and the PaySpace response is stored in the API's Export History table.
   Note: You will on see the export history for the current selected payroll run period. To see previous payroll run's history, select the appropriate payroll run period from the settings tab.

   1. Payroll Date: This is Eco Time's payroll hours date as entered for the pay run currently selected in the settings tab .
   2. Request ID: An internal incremental reference ID created by Eco Time, which is used to upload the payroll hours to PaySpace and match reponses from PaySpace to the transaction. This wil match the component's ID uploaded to PaySpace.
   3. PaySlip ID: For Eco Time reference, but PaySpace internal use only.
   4. Request ID: An inte
   5. Sucess: A Yes if the upload was successful or a No if not. This is a response from PaySpace.
   6. Error: If the upload was NOT successful, this reason field will be populated. This is a reason response from PaySpace.
   7. Employee No: Eco Time's employee number. Stored for history of the original upload.
   8. Payroll No: Eco Time's employee payroll number. Stored for history of the original upload.
   9. First Name: Eco Time's employee first name. Stored for history of the original upload.
   10. Surname: Eco Time's employee Surname. Stored for history of the original upload.
   11. Component Code: Payrol code as configure in Eco Time's time category setup . Stored for history of the orrginal upload.
   12. Input Type:The default is "Hours" but can be changed in the company's export settings form. Stored for history of the original upload.
   13. Input Value: Totals payroll hours for the time category in decimal format. Stored for history of the original upload.
   14. Cost Centre Code: PaySpace required field. Not supported by Eco Time. Stored for history of the original upload.
   15. Activity Code: PaySpace required field. Not supported by Eco Time. Stored for history of the original upload.
   16. Date Added: The date the payroll export was uploaded and a PaySpace response was received.
   17. Date Updated: If the Payroll Export was regenerated, and uploaded, this date will be updated when a PaySpace response was received.
   18. A web interface option is available. More information can be found here.
        

Important: The PaySpace Api client must be running at the same location as Eco's Web Server.
The webserver passes API requests to the API client, which in turn will process the request and send a response back to the webserver.

1. Payroll Options in the Web

   

   1. When the PaySpace API is enabled in the Desktop Client settings tab, the PaySpace menu will become available in the web's Browse Menu.
   2. Not all the API configuration settings is available in the web in an effort to keep the user experience streamlined. Use the desktop for to change advanced settings.
   3. All changes made in the web are reflected in the desktop API and the other way around.
   4. The settings tab allows the user to set the payroll run period and working company.
   5. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
2. Employees Check in the Web

   

   1. The employee check browse contains all the captured employees on the PaySpace system.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
3. Updating Employees in the Web

   

   1. The user can override the employee's match status. Select Exempt if you will not export this employee's hours to payroll and do not require a match to be performed in the future for this employee. Select OK to save your changes..
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
4. Payroll Companies in the Web

   

   1. The payroll companies browse contains all the captured employees on the PaySpace system.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
5. Updating Payroll Companies in the Web

   

   1. The user may assign an Eco Time employee group. This employee group will used to limit the employees in Eco Time when generating export payroll hours and uploading these to PaySpace. This is an optional field.
   2. Disabling the company will exclude all it and all its employees in Eco Time when generating export payroll hours and uploading these to PaySpace if this company is selected as the working company.
   3. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
6. Frequencies / Payroll Rules in the web

   

   1. The Frequencies browse should contains all the captured frequencies / payroll rules on the PaySpace system and must be manually added.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
7. Updating Frequencies / Payroll Rules in the web

   

   1. The Frequencies update form allowed the employee group to be assinged or changed..
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
8. Pay Run Periods in the Web

   

   1. The Pay Run browse contains all the pay run periods setup in PaySpace.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
9. Updating Pay Run Periods in the Web

   

   1. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
10. Payroll Export in the Web

    

    1. The Payroll Export browse contains generated hours extract for the current selected pay run period which can be uploaded to PaySpace.
    2. This mimics the behaviour and rules of the desktop interface which can be seen here.
    3. Note: The Generate and Upload button schedules that processes on a sperate thread for processing by the PaySpace API Desktop Client.
    4. Press the refresh button to update the progress and values in the Payroll Export Browse.
        
11. Payroll Export History in the Web

    

    1. The hours uploaded and the PaySpace response is stored in the API's Export History table and displayed in this browse.
    2. This mimics the behaviour and rules of the desktop interface which can be seen here.

1. An API call can be manually triggered at any time by pressing the API button at the bottom of each browse.
2. An API call triggered will depend on the current tab selected (eg Events).
3. All manually triggered API calls are not automated. This means the API Client Request Window will open and you would manually have to press the Res (Get) button. Afterwards press the close button to exit the API call.
   1. API Client Request Window Request:
      
   2. API Client Request Window Response:
      
4. The API Status message at the bottom left of the browse will be updated with the current action or process.
5. Manually triggering an API is used during the configuration and setting up phase of the API.
6. It is also very helpful when doing fault finding. See the FAQ for more details about this.

1. Timed events are automated events trigger either by time or an interval duration, in other words automated API calls.
2. During timed events the API Client Request Window is hidden but the API status message is updated.
3. There are three timed events:
   1. The API is authenticated with every timed event.
   2. The employees list is synced twice a day. Once at 1am and once at 1pm.
   3. The Frequencies list is synced twice a day. Once at 1am and once at 1pm.
   4. The Pay Run list is synced twice a day. Once at 1am and once at 1pm.
4. Timed events can be disabled be selecting the "Stop timed events" check box on the PaySpace API Window.

1. The logs browse displays general information about the API requests, responses and processes.

   

2. The log display information about:
   1. Details about the API event.
   2. If the API event was processed or rejected. If rejected, it provides a reason.
   3. When manual or timed API events were triggered.

1. In which Eco Time version is this feature available?
   From version 2024.07.20 onwards.
    
2. What information must the customer provide to setup the API?
   1. Client ID
   2. Client Secret
   3. The Eco Time employee group for who the payroll hours will be uploaded to PaySpace.
       
3. What process must the customer follow on a regular basis before payroll?
   1. The match discrepancies in the employee browse must be resolved on a regular basis .
       
4. What process must the customer follow to upload payroll hours?
   1. Important: The match discrepancies in the employee browse must be resolved.
   2. Select the correct Pay Run Period.
   3. Generate Export.
   4. Upload Payroll Hours.
       
5. I want to supress some of Eco Time Time Categories being exported.
   You can supress the time category from being exported in the API by disabling the applicable time category's "Export to Payroll" setting in Eco Time.
    
6. Some of the component codes (payroll codes) are incorrect. Where can these be changed?
   You can change the component code exported by the API by changing the applicable time category's "Payroll Code" setting in Eco Time.
    
7. What is a Pay Run or Pay Run period.
   This is the terminology used by Pay Space indicating their pay period start and end date. Eco Time must update each pay run to indicate the payroll end date in Eco Time that matches each pay run.
    
8. My Pay Run API upload returns a large number of invalid component code errors.
   The component codes are linked to a frequency. Refer to the Component Codes' browse to verify that the Pay Run frequency matches that of the component code's frequency. It is most likely that the Pay Run frequency is set incorrectly in PaySpace and now does not include the correct component code group.
    
9. I am trying to assign or select a pay run, but my pay run period is not in the lookup.
   Pay runs will only be available in the lookup if an Eco Time payroll date has been allocated. Select the Pay Runs browse and update the applicable pay run.
    
10. What is an unverified employee.
    This is an employee which was added to the employee browse from the PaySpace system in the past, but in more recently compares between this list and the PaySpace system, the employee was not found in the PaySpace system anymore.
    This typically happens if an employee is removed from the PaySpace system or allocated a new PaySpace employee record.
     
11. I am manually trying to use the API to populate the Pay Runs table, but the API windows does not appear.
    The Frequencies table must be populated first. The Pay Runs API will not run if there are no entries in this browse.
     
12. What is an authentication token?
    An authentication token is a digital credential used to verify the identity of a user, application, or device trying to access a system, service, or resource. It is often generated after successful authentication and can be used to maintain a session or grant access to specific resources without needing to re-authenticate repeatedly.
    
    The token expires after 2 hours, requiring the authentication API to be run again to obtain a new token.  If the token has expired, any API call wil be retun an Invalid Token or Unauthorised error.
     
13. Do I have to request an API Server URL and Authentication Server URL for customer?
    No. PaySpace's URLs are the same for all customers. The default URLs provided will be correct. NOTE: The Production and QAS URLs are different - but provided as defaults for each mode.
     
14. How can the API Client Request Window be used for fault finding?
    1. This window displays the request link in the server fields. You can use his value to determine if the correct link is being used during the call.
    2. Consider selecting the "Do Not Process Response" disables any results processing. No tables will be populated. This is typically used for faulty finding and is used in cases where you want to inspect the request packet and result packet.
    3. The PaySpace API Server response is displayed in the response window's text field. This response is the raw unprocessed data from the PaySpace API Server and represents the true data transmitted and received by the API Client.
    4. The response packet is json and is unformatted (one long string) and is in the body of the response. Copy this body to your clipboard and use an online formatter like https://jsonformatter.org/ to make the response easier to read.
    5. By inspecting the raw formatted json response, you can validate the values eventually stored in Eco Time and the PaySpace API Client.
        
15. How do you configure the PaySpace API Server for API Access?
    The tutorial can be found here: Creating API credentials for integration
     
16. What is the difference when setting the employee group at company and frequency / payroll rule level?
    1. Setting the employee group at the company level will limit the API's employee import and verification to this specific Eco Time group. This is useful in cases where a company has staff, such as executives, recorded in Eco Time, but they do not use time and attendance clocks. In this scenario, you can create and assign an employee group called "Time and Attendance" to the applicable employees. By updating the API's company employee group to this, executives will be excluded from the API processing.
    2. You can assign an Eco Time employee group to each frequency or payroll rule. If the frequency or payroll rule applies to wages staff, you could assign the employee group for wage employees to that frequency. Typically, you would assign an employee group to a frequency or payroll rule to separate wages, salaried, and casual employees when selecting the applicable payroll run to upload employee times. Only the employees' times in this group will be uploaded to payroll, first filtered by the company employee group, and then by this specific employee group.
        
17. What is it important to assign the correct Eco Time employee group to the frequency / payroll rule level?
    1. In PaySpace, the Payroll Run Periods are created for each frequency or payroll rule, such as wages and salaries.
    2. Assigning the incorrect employee group to the applicable frequency or payroll rule could result in salaried employees' time being uploaded to a payroll run meant for wages. Since wage and salaried payroll runs have different component codes (pay codes), employees not belonging to the applicable pay run will trigger an error: "Invalid Component Code."
        
18. The Desktop Server API Settings has an API Mode selection option for Production or QAS. What is the difference between the two modes?
    1. PaySpace offers a default option (upon request) to create a duplicate of the customer's live data on their staging (QAS) server. This data will be accessible when the API's QAS option is selected and the settings are configured accordingly.
    2. The two modes allow the user to have two different settings for testing and live, and removes the requirement to change settings continuously if the user toggles between the testing and the live system.
    3. QAS is for Testing the PaySpace system and Production for the current live PaySpace system.