Skip to main content

​
Onboarding state machine

A Sumvin user moves through a defined sequence of onboarding steps. Each step represents work the user has to complete (or that the platform chooses to skip) before they can be considered fully onboarded. The state machine is linear, idempotent, and observable through the Platform API.

​
The steps, in order

created
  → phone_verification
  → kyc_verification
  → byo_safe        (cohort: BYO_SAFE)
  → safe_deploy     (cohort: USER_SIGNED_DEPLOY)
  → open_banking
  → card_setup
  → feature_selection
  → complete
Any gated step can be skipped per user via platform configuration — for example, an integration that doesn’t issue cards would skip card_setup and open_banking. Steps that are skipped still appear in the state machine, marked as skipped rather than incomplete. kyc_verification is the exception: it cannot be skipped per partner. The SIS kyc feature is always-required (see Always-required features). What the partner can configure is the verification mode — surfaced on the step’s meta.kyc_mode field as websdk, hybrid, or document_only — which the resolver picks per-environment with a Statsig dynamic-config fallback (kyc_verification_mode, default websdk).

​
Wallet-cohort steps

byo_safe and safe_deploy are mutually exclusive — a single user is in one of three cohorts based on the SIS environment’s feature flags:
AI_AGENTUSER_SIGNED_DEPLOYWhat runsDescription
enableddisabledneither — agent-signed Safe creationSumvin’s signing service deploys the Safe with an agent signer attached.
disabledenabledsafe_deployThe user signs an ERC-4337 UserOp themselves; Sumvin sponsors gas via Pimlico.
disableddisabledbyo_safeThe user submits the address of a Safe they already control on-chain.
Both flags enabled at the same time is rejected at the SIS feature-write API with SIS-409-008 (Feature Mutex Violation) — see SIS feature mutex. Users without an org_id skip both steps.

​
Who drives transitions

DriverTransition
PartnerSubmits the current step when the user finishes it
SumvinAdvances automatically on approval, Safe deployment, and other asynchronous completion events
Partner-driven transition: Submitting the same step twice is a no-op, not an error — onboarding tolerates retries. A submission that enqueues background provisioning work (creation flow, KYC completion) returns 202 Accepted; purely synchronous transitions return 200 OK.

​
How to observe the current state

curl /v0/user/me/onboarding/steps \
  -H "x-juno-jwt: <token>" \
  -H "x-juno-orgid: <your-org-id>"
The response returns the current step, every step’s status, and a boolean is_complete. When is_complete is true, current_step is "complete".

​
See also

​
Referenced from