The user lifecycle
The URID account states and how a single KYC flow moves a user from Tourist to Live.
To access the full range of core banking operations, a user must hold a URID in the Live state. Onboarding is a single KYC flow that takes a newly minted URID from Tourist (minted, before KYC) to Live (KYC passed). This page describes the account states, how a user moves between them, and what your platform is responsible for along the way.
For what UR verifies during KYC and the methods it uses (questionnaire, proof of address, NFC scan, liveness, AML screening), see KYC & compliance.
User states
Every URID carries an on-chain account status, and that status controls what the user can do. The values are the AccountStatusV2 enum; for the on-chain mapping, see Smart contracts. The states are the following:
Na
0
New user; URID not yet minted
Nothing yet
Tourist
2
URID is minted, before KYC
Receive partner off-ramp and inbound P2P (up to 250 USD/EUR); cannot move funds externally, hold an IBAN, or send
Live
5
Completes KYC and passes compliance review
All banking features: external deposits (IBAN), external payouts, send and receive P2P, FX, card
SoftBlocked
1
An ongoing task (CRS, ongoing KYC, or EDD) passed its deadline
Money features locked until the open task is completed; recoverable to Live
Blocked
3
A compliance action freezes the account
Account frozen
Closed
4
The account is closed
Terminal; no access
Tourist is not a KYC stage the user completes. It is the state a URID is minted into before KYC. There is one KYC flow, and passing it moves the user straight to Live. Functions for any non-Live status are restricted on-chain.
State transitions
A URID is always minted in Tourist and promoted to Live once KYC passes; there is no direct path from Na to Live.
A user whose KYC is rejected stays in Tourist and cannot access core banking features. Blocked and Closed can also be reached from other states by a compliance action.
What you handle vs UR
Onboarding responsibilities split as follows:
KYC verification
Identity checks, screening, compliance review
Presenting KYC components in your app (UR webview or Sumsub SDK)
Wallet creation
Minting the URID NFT, provisioning the wallet (Managed Custody Mode)
Mapping your user ID to their URID
State changes
Transitioning the URID between statuses
Listening for webhooks, updating your UI accordingly
KYC prompt
Nothing; you decide when
Prompting the user to complete KYC when they attempt an action that requires Live
The onboarding flow
A URID moves from Tourist to Live through a single KYC flow. The steps run in this order:
Proof of identity
The user completes the passport or national ID NFC scan and a liveness check through the Sumsub flow. See KYC components for the mobile NFC requirement.
Your backend tracks progress through a KYC status field whose exact values depend on the integration path: kycFlow.currentStep on the UR main stack (see the External Wallet Access Mode API reference), or the session state in the partner-managed SDK path (see the Managed Custody SDK KYC reference).
Webhooks you receive
You receive the following onboarding webhooks. For money-movement and other events, see the full event catalog.
sumsub_kyc_result
A Sumsub review completes (Pass or Rejected)
All KYC paths
kyc_status
UR returns the compliance decision (Pending, Pass, Rejected, ManualReview, or Error)
All KYC paths
fma.account.result
Partner-managed onboarding ends (activated or rejected)
Partner-managed (FMA) KYC only
fma.penny_drop.result
A penny-drop attempt resolves (verified or failed)
Partner-managed (FMA) KYC only
fma.kyc.retry_required
UR ops request a partner-driven retry
Partner-managed (FMA) KYC only
The definitive Tourist → Live signal is kyc_status with status: "Pass" on the UR main stack, or fma.account.result with status: "activated" for partner-managed KYC. Only raise the user's access level on that signal.
KYC components
The KYC flow collects four components, presented in the order shown in The onboarding flow. Depending on your integration mode, you present them through the UR webview or the Sumsub SDK.
Proof of address. UR uses the GPS method to confirm the user's residential address. UR can show this through a webview or iFrame pointing to the UR web app (get.ur.app). The user must be signed in.
Questionnaire. Questions about the user, including eligibility screening, source of income, and monthly income. For a lightweight integration, UR can show the questionnaire through a webview or iFrame pointing to get.ur.app. The user must be signed in.
Proof of identity (passport or national ID NFC scan).
NFC scanning is only available on a mobile app. If your platform uses the Sumsub SDK directly (External Wallet Access Mode), the NFC scan step is only supported in the Sumsub mobile SDK (iOS/Android); it is not available in the Sumsub web SDK. You must expose this step through your mobile app. Web-only platforms cannot complete this step through the Sumsub SDK. If your platform has no mobile app, email support@ur.app to discuss alternatives.
Scenario A1 (iOS): UR returns a QR code and link to its NFC scanning provider. When the user taps it, an iOS App Clip opens, the user completes the NFC scan, then returns to your app.
Scenario A2 (Android): UR returns a QR code and link to its NFC scanning provider. The user downloads a separate app to perform the NFC scan, then returns to your app.
Agreement (Form A) signing. Form A contains the information the user filled in during KYC, so the user must complete the proof of address and questionnaire first and the data must exist in UR's database before UR can generate the form. The user signs Form A with the embedded wallet that holds their URID. UR can show Form A through a webview pointing to get.ur.app. The user must be signed in.
Last updated