Create Disbursement

post

https://api.branchapp.com/v2/organizations/{orgId}/workers/{workerId}/disbursements

Creates a disbursement for a worker. A disbursement is an initiation of payment to a worker. In sandbox, providing a value from this table to metadata.mock_response will return a mock disbursement with a corresponding reason_code, status, and HTTP Response Code.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

orgId

int32

required

Organization ID

workerId

string

required

Worker ID

Body Params

amount

int64

required

≥ 0

Amount, in cents, to be disbursed to the worker.

external_id

string

required

length between 0 and 64

Allows the custom specification of a unique ID that correlates back to your own records.

type

string

enum

required

TIP: Disbursement for a tip earned by worker

TRIP: Disbursement for a trip made by worker

MILEAGE: Disbursement for miles driven by worker

PAYCHECK: Disbursement for income earned by worker

MISCELLANEOUS: Disbursement to worker for miscellaneous reasons

DEVICE: Disbursement for a worker’s device

DELIVERY: Disbursement for a delivery made by worker

DEPOSIT: Disbursement for a generic purposes

REWARD: Disbursement for a reward earned

PER_DIEM: Disbursement for per diem reimbursement

BONUS: Disbursement representing a non-usual payment

worker_group

string

length between 0 and 150

A grouping for the worker. This could be anything that is used by your organization in order to group workers: store id, worker tier, region code, etc.

display_header_label

string

length between 0 and 32

The primary label of the disbursement. This will be displayed to the worker in the application. If left blank, will default to the disbursement type or a template value configured in organization settings

display_sub_label

string

length between 0 and 32

The sub label of the disbursement. This will be displayed to the worker in the application. If left blank, will default to the organization name or a template value configured in organization settings

description

string

required

length between 0 and 256

The description of the disbursement. This will be displayed in PayAdmin, and is not visible to the worker

retry

boolean

Defaults to false

If a disbursement with matching external_id and type exists, and status != COMPLETED, will retry instead of skipping.

metadata

object

Accepts custom JSON. Format definition

time_scheduled

date-time

Date and time at which the specified amount will be disbursed to the worker.

Responses

200Returned if the disbursement already exists and an additional attempt to disburse funds was not made. This can occur if the disbursement was already complete or if the resulting status is in [ CANCELED | SKIPPED | REVERSED ]

201Returned if an attempt to disburse funds was successful. This can occur if the disbursement is new or if it already exists and is retried successfully.

202Returned if an attempt to disburse funds was unsuccessful. This can occur if the resulting status is in [ FAILED | PENDING ]. Additional information can be found via reason_code.

400Returned if the request does not adhere to the API specification. Can also be returned if the disbursement cannot be created due to improper invoicing setup.

429Returned if the request is throttled. Throttling can occur based on requests/min or if you have reached your organization's daily disbursement limit.

500If persistent, contact your Branch representative.

504Gateway Timeout. An intermittent failure caused by a timeout from a dependency of Branch's systems on both the initial attempt and the automatic fallback retry. Poll to reattempt the payout.