Deduct Worker Advances in Payroll Remittance

Overview

Earned Wage Access (EWA) is a way that Organizations can give Workers access to their earnings before the usual pay date. When an Advance is provided to a Worker, that amount should be deducted from their wages to prevent paying that amount twice when invoicing your Organization for Disbursements and Advances at the end of the pay cycle. This process is called 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 Workers. This can be done by the following these 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

API Reference: Search Remittances

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

API Reference: Search Remittance Requested Deductions

Now that you have the remittance ID get the amounts that are being requested to be deducted for each Worker. 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 Worker Deductions

Using these requested deduction amounts, perform the EWA deductions. Your Organization does this step outside of your Branch account, so note how much you deducted for each Worker 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 Worker 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 Organization deducted $70 for Worker 12345 and $30 for Worker 54321 so you make two calls to Branch, one for each Worker:

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

API Reference: Complete Remittance Deduction

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

PATCH /organizations/100/remittances/3

{
  "status": "COMPLETED"
}

You should get a 200 response if successful.

✍️

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.