Disbursement Create

Overview

Your organization might use Branch to pay employees or 1099 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.

This guide walks you through the steps for paying a worker.

Disbursements

When a job is confirmed and ready for payment, your org 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. See an outline of this sequence of events in the following diagram:

Disbursement Failures

• In the event a disbursement fails, your org is responsible for taking the appropriate action to ensure workers receive payment.
• Disbursements may fail for various reasons. See the list of Disbursement Failed Reason Codes.

Invoicing and Paybacks

Your org will provide a funding account to Branch in order to pay back all disbursements.

• Branch will initiate a priority ACH transfer from the designated account on file to cover any disbursements paid out from the previous ACH window.
• The account and routing numbers for the funding accounts need to be entered into the organization before your org can utilize the disbursements function.

ACH Pull Schedule

• Invoices created before 10:45 AM CT cutoff will pull funds same-day
• Invoices created after cutoff will pull funds next banking day
• Banking days are every day except weekends and bank holidays

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

{
  "employee_id": "123456",
  "external_id": "7de69037-c2ca-4214-99a7-fc76a73642c1",
  "type": "Paycheck",
  "amount": 500,
  "description": "Deposit Test",
  "retry": true,
  "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

API Endpoints

For complete details about each endpoint see the Branch API reference section.

Note the following when making API calls:

• All API calls expect values to be trimmed with no pre-pended or trailing whitespace, unless noted otherwise.
• All creation requests for wallets and disbursements are idempotent and support handling duplicate request attempts.

Note the proper handling of HTTP response codes:

• 200/2XX OK The request was received and was processed by Branch.
• 500/5XX 5xx The system experience an issue and did not complete the processing of the request.
• If a call receives an error response code or encounters a timeout, the caller should retry the request until a 200 OK response is received.

Create Disbursement

API Documentation

See API docs for specifications: Create Disbursement

Disbursement FAILED Reason Codes

Search Disbursements

API Documentation

See API docs for specifications: Search Disbursements