Wagestream

Start streaming in less than 5 minutes

Wagestream makes it easy to connect your HR & Timekeeping system to our platform.

Follow our Quick Start guide to see what a minimal integration looks like, or view the full API Reference.

Get Started

Two Phase Quick Start

A note about GDPR

Under GDPR, there are six lawful bases for sharing personal data of data subjects. This guide is for employers who use the lawful basis of Legitimate Interest or Consent to share their employees' bank accounts with payroll providers and other third parties.
If your company's lawful basis is either Contract, please see the simplified Quick Start guide.

You are the CEO of ACME Ltd, maker of fine anvils since 1903.

You would like to integrate with Wagestream so that your hard-working anvil-makers can pay themselves whenever they want.

This involves several steps:

  1. Tell Wagestream some basic information about your employees
  2. Find out which employees have requested to enroll in Wagestream
  3. Tell Wagestream some additional information about enrolled employees
  4. Tell Wagestream about the shifts of enrolled employees
  5. Activate enrolled employees

Tell Wagestream some basic information about your employees

The employees endpoint is how you tell Wagestream about your staff. It's a single API that handles both INSERTs and UPDATEs. Simply send a list of employees as a JSON array, like so:

{
  "employees": [
    {
      "employee_id": "0001",
      "name": "Wile E. Coyote",
      "email": "wec@acmeltd.co"
    },
    {
      "employee_id": "0002",
      "name": "Bugs Bunny",
      "email": "bb@acmeltd.co"
    },
    {
      "employee_id": "0003",
      "name": "Porkey Pig",
      "email": "pp@acmeltd.co"
    }
  ]
}

When you POST that to the employees endpoint, you will receive a response like this:

{
  "ok": true,
  "rows": 3,
  "api_key": "...",
  "txn_id": "..."
}

Note the txn_id. You will want to save it, because if you ever need to get any info about the request, or check the status, or see how long it took to process, you'll need that unique transaction ID.

That's it! Wagestream now knows about your three employees.

Find out which employees have requested to enroll in Wagestream

When an employee starts using Wagestream, they will be in a "pending activation" state. The employee will not be able to stream any wages until the employer (you!) activates their account.

The endpoint /activations will return a list of all the employees who have requested to enroll in Wagestream.

{
  "pending_activations": [
    {
      "employee_id": "0001",
      "requested_on": "2018-01-03",
      "wagestream_sort_code": null,
      "wagestream_account_nubmer": null
    },
    {
      "employee_id": "0002",
      "requested_on": "2018-01-03",
      "wagestream_sort_code": null,
      "wagestream_account_nubmer": null
    }
  ]
}

What you can see here are two employees (Wile and Bugs) requested activation on 03 January.

Note that for both employees the Wagestream banking details are null. This is because the employees are still missing some critical information required to complete Wagestream enrollment: namely, Wagestream doesn't yet know their personal bank accounts!

Next we'll need to tell Wagestream that information, but only about the two employees who have requested enrollment.

Tell Wagestream some additional information about enrolled employees

The employees endpoint is used again, but this time to UPDATE additional data for these two employees. Send the following:

{
  "employees": [
    {
      "employee_id": "0001",
      "personal_sort_code": "200001",
      "personal_account_number": "XXXXXXXX"
    },
    {
      "employee_id": "0002",
      "personal_sort_code": "200002",
      "personal_account_number": "XXXXXXXX"
    }
  ]
}

There are a few important points to note here:

  • You are only sending data for two out of three employees (the 2 that have requested enrollment)
  • You do not need to send information that has already been sent (name and email). Only the employee_id and the new fields (personal_sort_code and personal_account_number) are required.

As usual, when you POST to this endpoint, you will receive a response like:

{
  "ok": true,
  "rows": 2,
  "api_key": "...",
  "txn_id": "..."
}

Tell Wagestream about the shifts of enrolled employees

The shifts endpoint is how you tell Wagestream that an employee has worked and earned some wages. The wages that you pass to this endpoint are the gross wages earned. And please note that all currencies in this API are expressed in pennies. So £90.00 would be 9000 and £45.75 would be 4575.

Now, recall that Porkey Pig has not enrolled, so we won't send information for him, only for Wile and Bugs. You might send the following:

{
  "shifts": [
    {"currency": "GBP", "employee_id": "0001", "worked_on": "2018-01-01", "hours": 8, "wages": 9000},
    {"currency": "GBP", "employee_id": "0001", "worked_on": "2018-01-02", "hours": 8, "wages": 9000},
    {"currency": "GBP", "employee_id": "0002", "worked_on": "2018-01-01", "hours": 5, "wages": 4575},
    {"currency": "GBP", "employee_id": "0002", "worked_on": "2018-01-02", "hours": 5, "wages": 4575},
  ]
}

Note that you are sending multiple records for each employee, one per shift.

The response is similar to the employees endpoint...

{
  "ok": true,
  "rows": 4,
  "api_key": "...",
  "txn_id": "..."
}

You've now told Wagestream about the employees, and given their bank details, and how much they have earned, but your employees won't be able to use Wagestream yet because they haven't been activated.

Activate enrolled employees

We now return to the /activations endpoint from above. This endpoint will now return a slightly difference response, because the two employees who requested enrollment now have complete information, including banking.

Here is what will be returned:

{
  "pending_activations": [
    {
      "employee_id": "0001",
      "requested_on": "2018-01-03",
      "wagestream_sort_code": "040058",
      "wagestream_account_nubmer": "XXXXXXXX"
    },
    {
      "employee_id": "0002",
      "requested_on": "2018-01-03",
      "wagestream_sort_code": "040058",
      "wagestream_account_nubmer": "XXXXXXXX"
    }
  ]
}

Note that wagestream_sort_code and wagestream_account_number are no longer null.

As CEO of ACME Ltd, you will need to update your payroll system with these bank details so that their paycheck is deposited in the correct place.

There is no need to keep their old bank details in your payroll system; those bank details are securely encrypted and stored with Wagestream.... any payments sent to their Wagestream bank will automatically and instantly forward to their personal bank account.

When each employee is updated in payroll, the final step is to send a POST to /activations?employee_id={employee_id} for each, which will allow the employee to start using the Wagestream platform.

Two Phase Quick Start


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.