Wallet Create

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

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

Testing

Simulate Onboarding using Test SSNs

During implementation, Branch provides test scenarios and test SSNs to simulate various worker onboarding scenarios and trigger a common set of Wallet Create responses and webhooks.

Test SSNs are supported in both SandBox and Production environments.

You can use the following curl command for testing in Sandbox:

curl --location --request POST 'https://sandbox.branchapp.com/v1/organizations/{orgid}/employees/{employee-id}/wallets' \
--header 'apiKey: {api-key}' \
--header 'X-Test-Mode: true' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Tester",
    "middle_name": null,
    "last_name": "McTester",
    "create_employee": true,
    "email": "test+employee-id@branchapp.com",
    "date_of_birth": "2000-01-01",
    "phone_number": "(612) 222-3333",
    "ssn": "445454450",
    "address": {
        "address_1": "123 Main St",
        "city": "Minneapolis",
        "state": "MN",
        "postal_code": "55555",
        "country": "US"
    },
    "order_card": false
}'

Important items to note:

The header 'X-Test-Mode: true' must be included and set to true to trigger test SSN handling.
If a non-test SSN is provided and the test flag is set to true, Branch returns a bad request.
Test cases are triggered by the SSN provided. Other PII will not affect test output.
Test SSNs are meant for functional testing only, not for API performance testing.
Wallets in test mode are stateless. This means that GET requests, Pay Admin reporting, disbursements, etc. are not supported.

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.

System Workflows

Worker Onboarding

Wallet Create API

When a worker selects Branch as their Payment Method, your organization calls the Create Wallet endpoint. Your system listens for a series of responses and webhooks, displaying relevant information in your Branch app. Branch generates an onboarding link to complete the claiming process. Your org then provides the onboarding link to the worker and listens for the WALLET_CLAIMED webhook to enable disbursements. See an outline of this sequence of events in the following diagram:

alt_text

All screens are subject to Branch review.

Disbursements

Disbursement Create

When a job is confirmed and ready for payment, your org will call 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. You may review detailed disbursement processing reports via the Pay Admin portal. See an outline of this sequence of events in the following diagram:

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

Create Wallet

API Documentation

See API docs for specifications: Create Wallet

Wallet Statuses - Suggested Actions

Status	Description	Suggested Action
CREATED	The wallet has been created and initial KYC checks have passed. The Branch system will begin the Fraud detection process, however this will not prevent the user from signing up. Fraud processing should be 10-15 seconds.	Temporary status - hold until status moves. Ignore onboarding_link. Wait to receive in the WALLET_ACTIVATED webhook.
PENDING	The wallet has not been created. The user is required to access the onboarding link and complete KYC in the Branch app.	Share onboarding_link with user to complete KYC.
FAILED	The wallet has not been created yet due to a non-recoverable failure.	Check FAILED reason codes table below and suggested action
ACTIVE	This only occurs if the user provided SSN is already assigned to an active wallet This means the user has a pre-existing wallet and should be approved to receive payouts	Notify user to sign-in to existing org/Branch account. No authentication or onboarding_link required as user is already active in Branch system
UNCLAIMED	This only occurs if the user provided SSN is already assigned to an unclaimed wallet	Prompt user to download Branch/org app and authenticate (through SSO or onboarding link).
CLAIMED	The user has already claimed the wallet	Notify user to sign-in to existing org/Branch account. No authentication or onboarding_link required as user is already active in Branch system
CLOSED	A wallet may be closed by the user or Branch. Users may close wallets to end their relationship with Branch. \ \ Branch may close wallets for confirmed fraud, ToS violations, inactivity, and customer requests A wallet that transitions from CREATED to CLOSED will be due to the inability to pass fraud checks	Verify that the user should have a closed account Take appropriate wallet closure action on the org App side

FAILED Status Reason Codes - Suggested Actions

Reason Code	Description	Suggested Action
CONFIRMED_FRAUD	The wallet is deactivated due to the user failing fraud checks	Log reason_code for troubleshooting Mark user account as ineligible for Branch account.
DENIED	The user has been denied access to the platform from a previous attempt.	Log reason_code for troubleshooting Mark user account as ineligible for Branch account.
ERROR	Unexpected error: [ id ] The id field represents the onboarding session id	Log and report to Branch for remediation with [ id ] Retry WALLET_CREATE with same information

Get Wallet

API Documentation

See API docs for specifications: Get Wallet

Webhooks

Webhook Events

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

Event	Description	Suggested Action	Example
ACCOUNT_REVIEW	The user has been flagged for manual review This will take up to 1 business day to process After manual review user will be APPROVED or DECLINED APPROVED will result in a WALLET_ACTIVATED event DECLINED will result in WALLET_DEACTIVATED event	Log event for troubleshooting Notify user that their account is being reviewed and may take up to 1 business day to complete. Ignore onboarding_link.	`{ "event": "ACCOUNT_REVIEW", "client_type": "ORGANIZATION", "client_id": int, "data": { "employee_id": String, "onboarding_link": String } }`
KYC_FALLBACK_FAILED	User has attempted to complete signup and has failed step up verification. This wallet is not payable and user should see a blocker in the app.	Log event for troubleshooting Hide Wallet payment option	`{ "event": "KYC_FALLBACK_FAILED", "client_type": "ORGANIZATION", "client_id": int, "data": { "employee_id": String } }`
WALLET_ACTIVATED	User has passed Fraud checks and wallet is ready to be claimed by user	Log event for troubleshooting Perform any account updates necessary for user notification and/or customer support. Share onboarding_link with the user.	`{ "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_CLAIMED	This indicates that the user has completed onboarding The wallet is active and the user account is fully functional	Log event for troubleshooting The user and wallet are now fully functional. Perform any account updates necessary for user notification and/or customer support.	`{ "event": "WALLET_CLAIMED", "client_type": "ORGANIZATION", "client_id": int, "data": { "employee_id": String } }`
WALLET_CLOSED	The 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_DEACTIVATED	The wallet is closed due to fraud or user initiated account closure	Check 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 } }`

Webhook Reason Codes: WALLET_DEACTIVATED

Reason Code	Description	Suggested Action
CONFIRMED_FRAUD	The wallet is deactivated due to the user failing fraud checks or if fraudulent activity is confirmed on the active wallet.	Log reason_code for troubleshooting Hide Wallet payment option, assess user risk profile
TERMS_OF_SERVICE_VIOLATION	The wallet is deactivated due to a violation of the terms of service	Log reason_code for troubleshooting Hide Wallet payment option
USER_REQUESTED	The wallet is deactivated due to inactivity and/or the user requested it to be closed.	Close user account. Ensure the user has the ability to open a new account in the future if needed.

Webhook Retries

There might be times when a notification can’t be delivered to your listener endpoint (for example, if your endpoint is offline while undergoing a software upgrade). In the event of a delivery failure, Webhooks v3 automatically schedules delivery attempts based on the following timetable:

Webhook Event Failure Scenario

The following describes an example failure flow that ultimately results in a stored failed event.

First failure, waits [ X ] seconds (currently 5 minutes)
If the second delivery attempt fails wait [ X^2 ]
If the third delivery attempt fails wait [ X^3 ]
.. configurable number of retries…
If delivery can’t be made after [ R ] retries, give up and assign the event failure state
Failed events can be requested via retry API up to [ D ] days after which the event is permanently removed from event store

Accepted Retry Frequency

Failures will retry after

First Failure: 30 seconds
Second Failure: 60 seconds
Third Failure: 5 minutes
Fourth Failure: 30 minutes
Fifth Failure+: 60 minutes, repeating 60 minutes till 7 days

Testing

Simulate Onboarding using Test SSNs​

Simulate Webhooks​

System Workflows

Worker Onboarding​

Wallet Create API​

Disbursements​

Disbursement Create​

Disbursement Failures​

Invoicing and Paybacks​

ACH Pull Schedule:​

API Endpoints​

Create Disbursement​

API Documentation​

Disbursement FAILED Reason Codes​

Get Disbursements​

API Documentation​

Create Wallet​

API Documentation​

Wallet Statuses - Suggested Actions​

FAILED Status Reason Codes - Suggested Actions​

Get Wallet​

API Documentation​

Webhooks​

Webhook Events​

Webhook Reason Codes: WALLET_DEACTIVATED​

Webhook Retries​

Webhook Event Failure Scenario​

Accepted Retry Frequency​

Simulate Onboarding using Test SSNs

Simulate Webhooks

Worker Onboarding

Wallet Create API

Disbursements

Disbursement Create

Disbursement Failures

Invoicing and Paybacks

ACH Pull Schedule:

API Endpoints

Create Disbursement

API Documentation

Disbursement FAILED Reason Codes

Get Disbursements

API Documentation

Create Wallet

API Documentation

Wallet Statuses - Suggested Actions

FAILED Status Reason Codes - Suggested Actions

Get Wallet

API Documentation

Webhooks

Webhook Events

Webhook Reason Codes: WALLET_DEACTIVATED

Webhook Retries

Webhook Event Failure Scenario

Accepted Retry Frequency