Skip to main content

Employee Create

This guide walks you through the steps for onboarding a worker using the Branch Employee Create functionality.

For an outline of the roadmap and timing, see the Intro page, and the diagram below on this page.

Testing

Simulate Webhooks​

You can use the Branch sandbox environment to manually trigger and test webhooks as you integrate them with your system. For details see Webhook Sandbox Testing.

Employee Create API​

When a worker selects Branch as their Payment Method, your organization calls the Employee Create endpoint to create a roster record in Branch. After the roster record is created, your org surfaces a Branch deep link for workers to KYC and complete setup via the Branch app. Your org will listen for the ACCOUNT_VERIFIED_AS_WORKER and WALLET_ACTIVATED webhooks to determine when Branch setup is complete. Sequence of events outlined below:

employee create flow

All screens are subject to Branch review. View or download a PDF of onboarding screen examples with Branch-approved copy here.

Disbursements​

Disbursement Create​

When a job is confirmed and ready for payment, your organization calls the Disbursement Create endpoint to post earnings to the worker’s Branch Wallet. When successfully processed, funds are immediately available to spend, transfer, or withdraw. Your org may review detailed disbursement processing reports via the Pay Admin portal. Sequence of events outlined below:

alt_text

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.
  • Disbursements paid out before 7pm CT will be pulled via ACH by 6am CT the following day.
  • ACH does not run on weekends.

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

Employee Create

Wallet Get

Disbursement Create

Disbursement FAILED Reason Codes​

Reason CodeDescription
worker_not_foundA worker with the provided id does not exist in our system
worker_not_matchedA user is not associated with the provided id, though the ID is on the roster. (User hasn’t signed up basically)
wallet_not_foundThe user associated with the provided ID does not have a wallet.
wallet_suspendedThe user associated with the provided ID’s wallet is suspended and not payable
amount_too_largeThe amount you are attempting to pay exceeds the single payout limits (by default $10k)
card_expiredThe card associated with this disbursement and employeeId is expired
card_invalidThe card associated with this disbursement and employeeId is no longer valid
retry_period_elapsedThe disbursement failed too long ago for it to be retried
unexpected_errorThe exact reason for failure cannot be determined automatically

Webhook Events​

Wallet webhook events are sent asynchronous to notify on updates to wallet status.

EventDescriptionSuggested ActionExample
ACCOUNT_VERIFIED_AS_WORKERWe have verified a match on user provided information.Check account_number and routing_number. If values are not null, the account is fundable. If values are null, no action needed.
    {
    "event": "ACCOUNT_VERIFIED_AS_WORKER",
    "client_type": "ORGANIZATION",
    "client_id": int,
    "data": {
        "employee_id": String,
        "account_number": String (null if N/A),
        "routing_number": String (null if N/A)
    }

}

WALLET_ACTIVATEDUser has passed Fraud checks and the wallet is fundable.Log event for troubleshooting

Perform any account updates necessary for user notification and/or customer support.

    {
  "event": "WALLET_ACTIVATED",
  "client_type": "ORGANIZATION",
  "client_id": int,
  "data": {
    "employee_id": String,
    "account_number": String,
    "routing_number": String,
    "onboarding_link": String,
    “is_claimed”: boolean
  }
}

WALLET_CLOSEDThe wallet is closed and the user may recreate another account.Suspend payouts. Ensure the user has the ability to create another account in the future if needed.
    {
  "event": "WALLET_CLOSED",
  "client_type": "ORGANIZATION",
  "client_id": int,
  "data": {
    "employee_id": String,
    "account_number": String,
    "routing_number": String
  }
}
WALLET_DEACTIVATEDThe wallet is closed due to fraud or user initiated account closureCheck reason codes (see below)
    {
  "event": "WALLET_DEACTIVATED",
  "client_type": "ORGANIZATION",
  "client_id": int,
  "data":   
    {
    "employee_id": String,
    "account_number": String,
    "routing_number": String,
    "reason": String,
    "reason_code": String,
    “is_claimed”: boolean
  }
}