EWA Remittance

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.

Ex. get the advances for organization 100

GET /organizations/100/advances

Ex. get the advances for employee 12345 at organization 100

GET /organizations/100/advances?employee_id=12345
note

Due to the remittance process, and changes that can occur, these advances should not be taken as the source of truth for how much to deduct from each employee. The source of truth for how much to deduct from each employee 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

Performing The Remittance

On the day that you provided Branch indicating when you run payroll, you will need to perform the remittance by deducting the amounts requested from your employees. This can be done by following the simple steps below.

For example purposes for the following steps we will say we are working with organization 100, that today is 2021-04-21 and that the next pay date for the organization is 2021-04-23.

1. Get The Remittance

The first step in the process is to get the ID from the current active remittance; this ID should be used for the remittanceId in the path for the calls in the subsequent steps. In order to get only the active remittances, ones in which action needs to be taken to make deductions for employees, make a call to GET /organizations/{orgId}/remittances?status=STARTED. If there are multiple remittances that are returned you can find the current one by looking at the pay_date to match the next pay date that was provided to Branch.

Ex. get the remittances that are STARTED, and are ready for us to perform the remittance

GET /organizations/100/remittances?status=STARTED

Ex. now we look at the response data and match up the response with our next pay date, 2021-04-23, and see that the remittance ID we will 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's 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.

Ex. 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

With the amounts that are being requested to be deducted from each employee from the prior step, perform the actual deductions themselves. This step is outside of Branch, but keep track of how much you deducted for each employee as you will need those amounts for the next step.

Ex. 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 actually deducted, even if $0, by calling POST /organizations/{orgId}/remittances/{remittanceId}/deductions and passing the employee's ID and the amount that was actually deducted from step 3 (in cents).

Ex. we deducted $70 for employee 12345 and $30 for employee 54321 so we will make two calls, 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 all 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
{
"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 un-deducted or partially deducted advances will rollover to the next remittance.