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
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 remittanceDEDUCTION_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"
}
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.