EWA Remittance

Earned wage access (EWA) is a way that organizations can give employees or workers access to their earnings before the usual pay date.

Viewing Employee Advances

At any point in time you can view the unpaid advances that your employees have taken by calling GET /organizations/{orgId}/advances. To view advances at an organization for a specific employee, query the prior endpoint passing the employee's ID to the employee_id query parameter.

Example

Get the advances for organization 100

GET /organizations/100/advances

Example

Get the advances for employee 12345 at organization 100

GET /organizations/100/advances?employee_id=12345

:::note

Due to changes that can occur over time these advances should not be taken as the source of truth for how much to deduct from each employee, which comes from the requested deductions in step 2 in Performing The Remittance below.

:::

Advance Statuses

  • OUTSTANDING Advance has not been paid back and there are no unsettled requested deductions on an active remittance
  • DEDUCTION_REQUESTED Advance has an unsettled requested deduction on an active remittance

Remittance

On the day you run payroll (a date you provided to Branch) you need to perform the remittance by deducting the amounts requested from your employees. This can be done by the following the steps.

For this example, the organization ID is 100, today is 2021-04-21 and the next regular pay date is 2021-04-23.

1. Get The Remittance

The first step in the process is to get the ID from the current active remittance, to use it as the remittanceId in the path for the calls in the subsequent steps. To get only active remittances (those on which action needs to be taken to make deductions for employees) make a call to GET /organizations/{orgId}/remittances?status=STARTED.

If multiple remittances are returned, you can find the current one by looking at the pay_date to match the next pay date that your org provided to Branch.

Example

Get the remittances that have STARTED status and are ready for us to perform the remittance:

GET /organizations/100/remittances?status=STARTED

Now look at the response data and match up the response with the next pay date, 2021-04-23, and see that the remittance ID to use in the following steps is 3

{
  "content": [
    {
      "id": 3,
      "pay_date": "2021-04-23",
      "remittance_date": "2021-04-21T17:09:59.743Z",
      "requested_amount": 10000,
      "status": "STARTED"
    }
  ],
  "page_number": 1,
  "size": 1,
  "total_number_of_elements": 1,
  "total_pages": 1
}

2. Get The Remittance Requested Deductions

Now that you have the remittance ID get the amounts that are being requested to be deducted for each employee. To do this, call GET /organizations/{orgId}/remittances/{remittanceId}/requested_deductions.

Example

Request and response for getting the requested deductions

GET /organizations/100/remittances/3/requested_deductions

{
  "content": [
    {
      "amount": 7000,
      "employee_id": "12345"
    },
    {
      "amount": 3000,
      "employee_id": "54321"
    }
  ],
  "page_number": 1,
  "size": 1,
  "total_number_of_elements": 2,
  "total_pages": 1
}

3. Perform Employee Deductions

Using these requested deduction amounts, perform the EWA deductions. Your org does this step outside of your Branch account, so note how much you deducted for each employee because you will need those amounts for the next step.

Example

Looking at the requested deductions from the previous step, we deduct $70 for employee 12345 and $30 for employee 54321

4. Report Employee Deductions

For each employee, report to Branch how much you deducted, even if $0, by calling POST /organizations/{orgId}/remittances/{remittanceId}/deductions and passing the employee ID and the amount deducted in step 3 (in cents).

Example

Your org deducted $70 for employee 12345 and $30 for employee 54321 so you make two calls to Branch, one for each employee:

POST /organizations/100/remittances/3/deductions

{
  "employee_id": "12345",
  "amount": 7000
}

POST /organizations/100/remittances/3/deductions

{
  "employee_id": "54321",
  "amount": 3000
}

5. Complete The Remittance

Once you are finished making and reporting each employee's deductions, complete the remittance process by calling PATCH /organizations/{orgId}/remittances/{remittanceId} passing a request body of:

Ex.

PATCH /organizations/100/remittances/3

You should get the response:

{
  "status": "COMPLETED"
}

:::note

Completing the remittance will mark any unsettled or unreported requested deductions as deductions of $0 and no further deductions will be allowed to be submitted for the remittance. Any not deducted or partially deducted advances will roll over to the next remittance.

:::

Updated 5 months ago