User Onboarding
Overview of the user onboarding flow from wallet creation to KYC completion.
Before You Start
Read the following guides before proceeding:
| Guide | Why |
|---|---|
| Getting Started | Platform overview and setup |
| Api Basics | Required headers and request configuration |
| Authentication | How to obtain access tokens |
| Wallet Deployment | Smart Wallet deployment |
| Webhooks | Receive status notifications |
Overview
User onboarding in Wirex BaaS follows a three-step process:
- Create Smart Wallet — Deploy an Account Abstraction wallet on-chain
- Register User — Create a user record in Wirex via API
- Complete KYC — Verify user identity through one of the available flows
Step 1: Create Smart Wallet
Deploy an Account Abstraction wallet for the user and register it in the Wirex Accounts contract.
Requirements:
- Deploy Smart Wallet with required modules (executor + policy)
- Call
createUserAccountWithWalleton the Accounts contract - Wait for
/v2/webhooks/walletswebhook confirmation
See Wallet Deployment for implementation details.
Step 2: Register User
After wallet confirmation, create a user record in Wirex by calling the registration API.
Endpoint: POST /api/v2/user
The request payload varies based on your chosen onboarding flow (see Step 3).
Important: The wallet_address parameter must be the user's EOA address (the signer), not the Smart Wallet address.
Step 3: Complete KYC
Choose an onboarding flow based on your integration requirements:
| Flow | Use Case | Guide |
|---|---|---|
| Wirex Hosted KYC | You collect basic data; user completes KYC in Wirex-hosted flow | Wirex Hosted KYC |
| Sharing Data Through SumSub | User already verified via SumSub; share verification with Wirex | Sharing Data Through SumSub |
| Reliance | You handle full KYC; provide complete verified data to Wirex | Reliance |
Flow Comparison
| Aspect | Wirex Hosted | SumSub Shared | Reliance |
|---|---|---|---|
| KYC responsibility | Wirex | You (via SumSub) | You |
| Data required at registration | Email + country | Sharing token + email | Full profile + address + documents |
| User interaction | Hosted KYC widget or SumSub SDK | None (already verified) | None (already verified) |
| Setup complexity | Low | Medium (3-sided agreement) | High (requires Wirex approval) |
Webhooks
Wirex sends webhook notifications as onboarding progresses.
Wallet Confirmation
After on-chain registration completes:
Endpoint: POST {your_webhook_base_url}/v2/webhooks/wallets
See Wallet Deployment - Webhooks for payload details.
User Status Updates
After API registration and during KYC verification:
Endpoint: POST {your_webhook_base_url}/webhook/users
Note: This is a legacy webhook format that will be replaced with a v2 model in a future release.
See Webhooks for payload details and verification status values.
Verification Statuses
| Status | Description |
|---|---|
None | No verification submitted |
Applied | User has unfinished steps in SumSub SDK, or incomplete data was provided during Shared/Reliance flows |
Pending | Verification checks are being executed on Wirex side |
InReview | Verification checks are being executed on Wirex side |
Approved | Verification approved — user is ready to use all features |
Canceled | Verification was rejected — contact Wirex support to resolve |
Rejected | Verification was rejected — contact Wirex support to resolve |
What Happens Next
Available immediately after wallet deployment:
- Withdraw crypto to external wallets
Available after KYC approval:
- Issue virtual or physical cards
- Make card payments
- Transfer funds via SEPA or ACH
Updated 8 days ago