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 Get Started, 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": "[email protected]",
    "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,
    "debug_fail_kyc_inquiry": 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:

Create Wallet

API Documentation

See API docs for specifications: Create Wallet

Wallet Statuses - Suggested Actions

Reason Codes for FAILED Status - Suggested Actions

Get Wallet

API Documentation

See API docs for specifications: Get Wallets

Webhooks

Webhook Events

Wallet webhook events are sent asynchronous to notify on updates to wallet status. Below we provide information about webhooks related to wallets. For more details about webhooks see the Webhook Reference Docs

{
"event": "ACCOUNT_REVIEW",
"client_type": "ORGANIZATION",
"client_id": int,
"data": { 
 "employee_id": String,
 "onboarding_link": String
 }
}

{
 "event": "KYC_FALLBACK_FAILED",
 "client_type": "ORGANIZATION",
 "client_id": int,
 "data": {
   "employee_id": String
 }
}

{
"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
 }
}

{
"event": "WALLET_CLAIMED",
"client_type": "ORGANIZATION",
"client_id": int,

"data": {
 "employee_id": String
 }
}

{
"event": "WALLET_CLOSED",
"client_type": "ORGANIZATION",
"client_id": int,
"data": {
 "employee_id": String,
 "account_number": String,
 "routing_number": String
 }
}

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