# Payroll integrations (PaySpace, SimplePay)

> How Timed connects to PaySpace and SimplePay to sync employees and leave, and to push approved hours to PaySpace. Covers setup, linking by payroll number, and the nightly schedule.

Timed connects to your payroll vendor so you don't have to re-enter employee changes or worked hours in two systems. Currently supported:

| Vendor | What Timed can do |
|---|---|
| **PaySpace** | Import companies, employees, pay periods and component codes; keep linked employees up to date nightly; import incidents as disciplinary records; push selected employee documents; push approved payroll hours. |
| **SimplePay** | Link existing Timed employees to SimplePay by payroll number, and import leave. SimplePay's public API doesn't accept hours pushed back in, so payroll hours can't be pushed to SimplePay. |

Sage is not supported yet.

Set up the connection under **Integrations → Payroll Settings** (also reachable from **Payroll → Payroll Settings** in the sidebar). You need the **Manage Settings** permission.

## Configuration

In **Payroll Settings**, under **API Connection**:

| Field | What it is |
|---|---|
| **Vendor** | PaySpace or SimplePay. |
| **API Key** | Issued by your vendor. For PaySpace this is the client ID; for SimplePay it's your API key. |
| **API Secret / Client Secret** | PaySpace only. |
| **API URL** | The vendor's API address. Leave the default unless your vendor tells you otherwise. |
| **Auth URL** | PaySpace's sign-in address, normally `https://identity.yourhcm.com/connect/token`. |
| **Company ID** | Your company identifier at the vendor. |
| **Company import scope** | Import every company on the account, or restrict to a single company. |

Click **Save Settings**, then **Test Connection**. Timed signs in to the vendor and shows whether it worked, or the error it got back.

## What gets imported

### Companies

Click **Refresh Companies** to bring in the companies on your payroll account. They appear under **Payroll Companies**. For PaySpace, this is also where each company gets its pay codes. Do this before importing employees.

### Component codes (PaySpace)

When editing a payroll company or pay frequency, choose which PaySpace component code Timed should use for normal hours, overtime 1.5×, overtime 2×, unpaid leave, paid leave and public holidays. Use **Refresh codes from PaySpace** if a code you need isn't listed.

### Pay periods (PaySpace)

On the **Payroll Runs** page, click **Sync Runs** to bring in PaySpace's pay periods so Timed knows the cut-off dates.

### Employees

Click **Import Employees**. Timed reads the employee list from your vendor and **links** existing Timed employees whose payroll number matches the vendor's employee number. For PaySpace, it also **creates** employees that don't exist in Timed yet. For SimplePay, employees without a matching payroll number are skipped, so add them in Timed first.

### Keeping employees up to date (PaySpace)

With **Employee changes** ticked under **PaySpace sync controls**, Timed updates existing linked employees from PaySpace every night at 21:20. This nightly sync never creates new employees, so a fix made in PaySpace won't unexpectedly add people to Timed.

### Incidents (PaySpace)

With **Incidents** ticked, Timed imports PaySpace incidents as disciplinary records every night at 21:30. This is one-way: edits made in Timed are not sent back to PaySpace.

### Attachments (PaySpace)

With **Attachments** ticked, you can click **Sync Attachments** to push selected employee documents (such as FICA documents and contracts) from Timed to PaySpace.

Remember to click **Save Controls** after changing any of the PaySpace sync controls.

## The nightly schedule

| Time | What happens |
|---|---|
| 21:00 | Leave for the current month is imported from PaySpace or SimplePay. See [Importing leave from payroll vendors](https://timed.co.za/docs/leave-imports). |
| 21:20 | PaySpace only: linked employees are updated from PaySpace. |
| 21:30 | PaySpace only: incidents are imported as disciplinary records. |

You can also run the employee, incident and attachment syncs on demand from **Payroll → Sync Dashboard**.

## Linking by payroll number

Timed matches its employees to vendor employees by **payroll number**. Both systems need to use the same number for the same person. If a PaySpace employee has number `EMP0123` but the Timed employee is `123`, they won't match, so fix one or the other before importing.

**Payroll → Sync Dashboard** shows the latest sync times, how many employees are linked, and any errors for each vendor.

## Pushing hours to PaySpace

Payroll hours are prepared on the **Payroll Runs** page (**Payroll → Payroll Runs**):

1. Open the pay period and calculate the entries from Timed's clock data.
2. Review the totals per employee, grouped by component code (normal, 1.5×, 2×, unpaid and so on), then approve the run.
3. Do a dry run to check what would be sent.
4. Click **Push live to PaySpace** to send the approved hours into the PaySpace pay period.

Live pushing is off by default. To allow it, tick **Live push of payroll hours to PaySpace** under **Payroll Settings → PaySpace sync controls** and click **Save Controls**. While it's off, you can still calculate, approve and dry-run payroll runs, but nothing is written to PaySpace. Hours can't be pushed into a period that is already closed in PaySpace.

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| Test Connection fails with an authentication error | The API key or secret is wrong, or the API URL points at the wrong environment. |
| Import shows 0 employees but your vendor has many | The Company ID is wrong, or your API key doesn't have access to that company. |
| Employees imported but hours don't push | Component codes aren't set. Choose them on the payroll company or pay frequency. Also check that **Live push** is switched on. |
| Incidents aren't syncing | **Incidents** isn't ticked under PaySpace sync controls. Tick it and click **Save Controls**. |
| Linked count says 0 | Timed payroll numbers and vendor employee numbers don't match. Check both for leading zeros, spaces or different prefixes. |

If a sync keeps failing, check **Payroll → Sync Dashboard** for the error. If something still doesn't work after following this guide, contact Timed support.