Disbursement Create

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


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 Create Flow

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 same-day ACH 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:

Disbursements paid out

  • Before 11am CT will be pulled via ACH by 5pm CT
  • Before 7pm CT will be pulled via ACH by 6am CT the following day
  • ACH does not run on weekends

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.

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

The adjustments metadata object fields metadata, 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.

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

Reason Code Description
worker_not_found A worker with the provided id does not exist in our system
worker_not_matched A user is not associated with the provided id, though the ID is on the roster. (User hasn’t signed up basically)
wallet_not_found The user associated with the provided ID does not have a wallet.
wallet_suspended The user associated with the provided ID’s wallet is suspended and not payable
amount_too_large The amount you are attempting to pay exceeds the single payout limits (by default $10k)
card_expired The card associated with this disbursement and employeeId is expired
card_invalid The card associated with this disbursement and employeeId is no longer valid
retry_period_elapsed The disbursement failed too long ago for it to be retried
unexpected_error The exact reason for failure cannot be determined automatically

Get Disbursements

API Documentation

See API docs for specifications: Get Disbursements