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

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

Updated 23 days ago