Create a Disbursement

Overview

Your Organization might use Branch to pay Workers more quickly, or simply to streamline your payment processes. Whether this means a paycheck, tips/mileage, or automatic payouts right after completing a shift, all of these payments are considered Disbursements by Branch.

Disbursements

When a job is confirmed and ready for payment, your Organization will call the Create Disbursement endpoint to post earnings to the Worker’s Branch Wallet. When successfully processed, funds are immediately available to spend, transfer, or withdraw. You may review detailed Disbursement processing reports via the Pay Admin portal.

Disbursement Failures

In the event a disbursement fails, your Organization is responsible for taking the appropriate action to ensure workers receive payment. Follow the Disbursement Error Handling guide to understand which response values to check during implementation.

Disbursement Testing

Generate Mock Responses and perform Sandbox Debit Card integration tests to verify correctness of Disbursement Error Handling.

Disbursement Adjustments

You can add Disbursement Adjustments to the API request body as metadata.
The Worker can view these adjustments by clicking into the Disbursement details in-app, and designated admins can view them in the Branch Pay Admin Portal.

The Disbursement's metadata field allows any valid JSON, but has special handling if an adjustments key is present at the top level. The adjustments metadata object fields adjustments, name, and amount are fixed and must be used as shown in the example. Their paired values can be whatever you choose, as long as they adhere to these restrictions:

• The name value has a 50-character limit.
• Deducted amounts are negative integer cent values, with no currency specified. For example -684
• Added amounts are positive integer cent values with no currency specified. For example 200

Branch will not do any calculations to validate the net versus the base pay. Branch will take the Disbursement amount as net and sum the inverse of all deduction values, positive or negative, to display as a base pay amount. Any discrepancies in that value will be the customer's responsibility.

Branch displays the adjustments in the order that they were provided in the API request body.

Example Disbursement Request Body with Adjustments

{
  "worker_id": "123456",
  "external_id": "7de69037-c2ca-4214-99a7-fc76a73642c1",
  "type": "PAYCHECK",
  "amount": 500,
  "description": "Deposit Test",
  "metadata": {
    "adjustments": [
      {
        "name": "401k",
        "amount": -1000
      },
      {
        "name": "Insurance",
        "amount": -684
      },
      {
        "name": "Union Dues",
        "amount": -21
      },
      {
        "name": "Cell Phone",
        "amount": 200
      }
    ],
    "custom-key": {
      "custom-data": "custom-value"
    }
  }
}

The base pay displayed from the example data would be calculated as follows:

Summed Adjustments = -1000 + -684 + -21 + 200 = -1505

Base Pay = Disbursement Amount - Summed Adjustments = 500 - (-1505) = 2505 = $25.05