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:
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. |
|
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 |
|
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. |
|
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. |
|
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. |
|
WALLET_DEACTIVATED | The wallet is closed due to fraud or user initiated account closure | Check reason codes (see below) |
|
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 11 days ago