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

Wallet Create Flow

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


Reason Codes for FAILED Status - Suggested Actions

Reason Code Description Suggested Action
Basic Reason Codes
ADDITIONAL_DOCS_REQ Branch was not able to confirm identity with the information provided. The user will have to provide additional documentation, like a driver's license, in order to get a wallet on Branch.
FRAUD_CHECK_REQ Branch is performing checks to ensure that the user is not linked to fraudulent activity. Once the checks are completed the user wallet will be activated and can then be funded. Wait for checks to finish and Wallet Status to update.
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.

v1.01 Reason Codes
KYC_SSN_INVALID KYC verification failed due to invalid social security number. Inform user that they provided an invalid SSN.

Retry WALLET_CREATE with corrected information.

KYC_PII_SSN_MISMATCH KYC verification failed due to invalid personal information (name, birthdate). Inform user that they may have an error in their PII that does not match the SSN.

Retry WALLET_CREATE with corrected information.

KYC_DECEASED KYC verification failed due to person reported deceased. Inform user that the information they provided does not match a living person.

Retry WALLET_CREATE with corrected information.

KYC_PO_BOX_NOT_ALLOWED KYC verification failed due to PO Box address. Inform user to provide a non-PO Box address.

Retry WALLET_CREATE with corrected information.

KYC_ERROR Unexpected error occurred during KYC step. Log reason_code for troubleshooting.

Retry WALLET_CREATE with same information.

ACCOUNT_SUSPENDED Wallet account was suspended due to failed KYC fraud checks. Verify account should be suspended.

Work with Branch support to resolve.

ACCOUNT_WITH_EMAIL_EXISTS Another Branch account already uses the same email. Check email address and verify it is correct. If incorrect, retry WALLET_CREATE with corrected information. If correct, contact Branch support to assign the email address to the new wallet.
EMPLOYEE_NOT_FOUND Employee was not found. Inform user that the EmployeeID provided does not match an employee in their Organization.

Retry WALLET_CREATE with corrected information.

EMPLOYEE_UNDER_AGE Employee was not of the minimum age to create an account. Check the DOB and verify it is correct.

If incorrect, retry WALLET_CREATE with corrected information.

EMPLOYEE_ALREADY_LINKED Employee was already linked to another user account. Safe to ignore.

Update the record state on Employer side to make sure that record isn’t stuck in a loop.

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