CryptoOnramp SDK: Example App KYC Step-Up Flow by mliberatore · Pull Request #6217 · stripe/stripe-ios

mliberatore · 2026-03-17T16:50:04Z

Summary

Adds step-up flow logic to the demo app for errors encountered related to expected L0 KYC-related errors.

When creating an onramp session, we respond to certain error codes returned from the backend and collect more KYC information as needed.

L0 → L1: We collected L0 fields from the user after auth, but the transaction requires L1. We present the KYC form with only SSN and DOB fields to complete L1.
L1 → L2: We collected L0 fields from the user after auth, and potentially later collected L1 fields in the scenario above. However, the transaction requires L2 (identity document verification). We present the Identity flow to complete L2.
L0 → L2: We collected L0 fields from the user after auth, but the transaction requires L2. We present the KYC form with only SSN and DOB fields, and then we push the identity flow afterwards to step up to L2.

Motivation

https://docs.google.com/document/d/1PAjI3bl3S_h3630TpZ012-wn4k6lQJlFyxaX3cmTRhE/edit?tab=t.0#heading=h.lnqfcyy21mit

Testing

Tested the step-up flow by disabling the livemode requirement, and enabling the L0 KYC mode introduced in #6198, then getting to the payment screen, and attempting to create onramp sessions. Note that checkout will fail in livemode under these conditions, but starting the onramp session at least allows us to respond to appropriate errors when we provide large transaction $$ amounts.

Level 0 → Level 1 step-up, in response to crypto_onramp_missing_identity_verification with L0 fields attached:

Simulator.Screen.Recording.-.iPhone.17.-.2026-03-17.at.12.54.14.mov

Level 1 → Level 2 step-up, in response to crypto_onramp_missing_document_verification with L1 fields attached:

Simulator.Screen.Recording.-.iPhone.17.-.2026-03-17.at.12.55.00.mov

Level 0 → L2 step-up, in response to crypto_onramp_missing_document_verification with L0 fields attached. (Note that this scenario is simulated, as the backend is returning crypto_onramp_missing_identity_verification incorrectly at the moment. I swapped the error check to force this scenario to test the 2-step step-up process.):

Simulator.Screen.Recording.-.iPhone.17.-.2026-03-17.at.12.59.24.mov

Changelog

N/A, SDK is in Alpha

…ry error handling

…-onramp-l0-kyc`

…-modes

…mliberatore/crypto-onramp-l0-kyc

This helps to determine if we’re at level 1 when the mode is level 0 (i.e. the user chose to fill the optional SSN + DOB fields).

…uting' into mliberatore/crypto-onramp-l0-kyc # Conflicts: # Example/CryptoOnramp Example/CryptoOnramp Example/CryptoOnrampExampleView.swift # Example/CryptoOnramp Example/CryptoOnramp Example/CryptoOnrampFlowCoordinator.swift # Example/CryptoOnramp Example/CryptoOnramp Example/KYCLevel.swift

… various scenarios

…d properties

mliberatore · 2026-03-17T17:20:59Z

    }
 }

-extension CustomerInformationResponse {


These changes were moved (and expanded upon) to an extension in the same file as the type (above), since we make use of these convenience properties from PaymentView as well now.

mliberatore · 2026-03-17T17:21:41Z


 /// Represents progressively stronger customer verification completeness.
-enum KYCLevel {
+enum KYCLevel: String, Identifiable {


Identifiable was added for the .sheet API used in PaymentView.

mliberatore · 2026-03-17T17:29:23Z

+                let errorDescription = error.localizedDescription
+                let fallbackAlert = Alert(title: "Failed to create onramp session", message: errorDescription)
+
+                if errorDescription.hasPrefix("HTTP 400"), shouldFetchCustomerInfoForRecovery(from: errorDescription) {


Note that the StripeError / StripeAPIError types are not exposed publicly, so our error identification is a bit rudimentary here in the demo app, matching the HTTP status, and then searching the body for the error code from the error description.

Just for my own understanding, should we expose these types eventually?

Not to my knowledge. They live outside of our framework, and are Stripe private types.

However, thank you for bringing this up. When beginning to explain more about StripeError and how we propagate errors back to the client, I realized that since this is using our example app's API client, not Stripe's, we're in complete control of the error type returned.

Will refactor this now to parse the error information more appropraitely.

Updated. The error handling here is much more robust, with JSON-parsed error bodies → associated values in our custom error type.

(lldb) po code crypto_onramp_missing_identity_verification

(lldb) po error ▿ APIError ▿ httpError : 3 elements - status : 400 - message : "Identity verification is required for this transaction." ▿ code : Optional<String> - some : "crypto_onramp_missing_identity_verification"

Thanks, looks great!

# Conflicts: # Example/CryptoOnramp Example/CryptoOnramp Example/CryptoOnrampFlowCoordinator.swift # Example/CryptoOnramp Example/CryptoOnramp Example/KYCLevel.swift

mliberatore · 2026-03-17T21:53:27Z

 		0B44B40C2E57702B00B58655 /* StripeCameraCore.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 0B44B40B2E57702B00B58655 /* StripeCameraCore.framework */; };
 		0B44B40D2E57702B00B58655 /* StripeCameraCore.framework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 0B44B40B2E57702B00B58655 /* StripeCameraCore.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
+		0B8EB14A2F68947200D3C114 /* StripeIssuing.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 0B8EB1492F68947200D3C114 /* StripeIssuing.framework */; };
+		0B8EB14B2F68947200D3C114 /* StripeIssuing.framework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 0B8EB1492F68947200D3C114 /* StripeIssuing.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };


The lack of inclusion of this framework was causing device builds to fail in Xcode. I’ve updated the README as well to now include this.

jeanregisser

LGTM 👍
cc @mats-stripe since I don't have much context yet.

jeanregisser · 2026-03-17T21:41:46Z

+                let errorDescription = error.localizedDescription
+                let fallbackAlert = Alert(title: "Failed to create onramp session", message: errorDescription)
+
+                if errorDescription.hasPrefix("HTTP 400"), shouldFetchCustomerInfoForRecovery(from: errorDescription) {


Just for my own understanding, should we expose these types eventually?

jeanregisser · 2026-03-17T22:53:14Z

+                    }
+                }
+        }
+        .loadingOverlay(isVisible: isLoading.wrappedValue)


Non-blocking UX thought: do we want to avoid a full-screen loading overlay during async operations here? It can feel pretty heavy since it removes context and blocks the whole screen, whereas inline progress or disabling only the relevant action might feel smoother. Also, since this is an example app, there’s some risk that integrators take this as a recommended pattern. Totally fine if there’s context I’m missing.

That's great feedback. Thus far, integration of the SDK has been to existing apps, but I do want to make sure we're putting best practices/patterns forward for folks in need of more context and assistance when building from scratch.

Since this would be a sweeping change (noting that we're using this loading modal across the entire example app experience), it will make sense to tackle this in isolation from these changes. We have a few priorities left on this feature, but we can chat more in our sync about these improvements and plan them out. Some Views might be trickier, with a lot of potential user interaction, and not-yet a good solution for cancelation of operations (if we were to leave the UI enabled) so I think it will make sense to think this through holistically.

jeanregisser · 2026-03-17T23:11:35Z

+
+    private func finish() {
+        dismiss()
+        onSuccess()


nit: since dismiss() hides the sheet with an animation, could this cause issues if onSuccess() wanted to trigger another sheet?

I‘m not experiencing an issue with sequential presentation in practice here. We currently present an alert upon dismissal in onSuccess(). To be more certain, I’ve wired up a test sheet to confirm an issue does not occur, and confirmed there's no console logs to suggest an issue with presentation occurring during the dismissal, nor a second presentation occurring while already presenting.

Presentation-after-kyc-flow-dismissal.mov

jeanregisser · 2026-03-17T23:14:29Z

+        // Note that the `isKycVerified` check is currently disabled.
+        // We're waiting on a backend change that properly reports `verified` when a user
+        // has collected at least L0. Instead, right now it reports `not_started`.
+        guard providedKYCLevel.includesLevel0, isPhoneVerified /*, isKycVerified*/ else {


This backend change was resolved, so I removed the temporary workaround and retested.

mats-stripe

LGTM - I'm generally peaceful with changes to the example app 👍

## Summary This makes two minor changes that were requested for testing out L0 KYC Mode 1. `livemode` is no longer required to be enabled to select L0 KYC Mode. While onramp session creation will fail in test mode when providing only L0 KYC info, this was requested to assist in testing the flow. 2. Removes the requirement of `phone_verified` status when determining KYC level. ## Motivation Requests from Xuhui in Lickability slack: https://lickability.slack.com/archives/C094P3BRBL1/p1773937514217369?thread_ts=1773760441.342059&cid=C094P3BRBL1 (To open in Stripe slack, paste/send this link to Slackbot, and it should convert it appropriately.) ## Testing Repeated the tests from #6217, without the need to apply a local workaround to enable L0 KYC Mode in test mode. ## Changelog  N/A, Alpha SDK and these changes only affect the example app, not the SDK.

mliberatore added 30 commits March 4, 2026 14:53

Adds the basics for supporting L0 KYC. Error/field diffing to come.

bcb81f2

Adds kyc level determination to skip L0 info collection after auth

c8d2307

Minor copy tweaks for KYC levels

f94a789

Adds the ability to show KYC and identity “just in time” with tempora…

a83fcce

…ry error handling

Extracts loading view to work in modal flow

29d7ba1

Updates LoadingOverlayView to offer a modifier

7ebd195

Slight cleanup of KYC levels and convenience getters

544029d

Merge branch 'master' into mliberatore/crypto-onramp-l0-kyc

02734ef

Merge branch 'master' into mliberatore/crypto-onramp-l0-kyc

c90b8ec

Allows for collecting only SSN + DOB to go from L0 to L1

0d4e579

Restores original mode to support non-livemode, non-l0-kyc collection

136b6e3

Extracts UI and only necessary model changes from `mliberatore/crypto…

8b511a4

…-onramp-l0-kyc`

Merge branch 'master' into mliberatore/crypto-onramp-l0-kyc-info-view…

3f3637d

…-modes

Merge branch 'master' into mliberatore/crypto-onramp-l0-kyc

d37c09a

Merge branch 'mliberatore/crypto-onramp-l0-kyc-info-view-modes' into …

fb80e55

…mliberatore/crypto-onramp-l0-kyc

Adds switch to enable/disable low kyc

bc91582

Routes to appropriate KYC collection

c971dc9

Small logic and documentation cleanup

bc91d30

Reintroduces identity verification into flow coordinator

22c1fb4

Cleans up comments and conditional logic for kyc + identity

2da8fe8

Initial KYC routing to optionally work with L0 post auth

9195ea1

Derives collected kyc level based on mode + actual fields submitted

747a09f

This helps to determine if we’re at level 1 when the mode is level 0 (i.e. the user chose to fill the optional SSN + DOB fields).

Restores original copy on identity view

5c5922d

Small adjustments to convenience properties

5c4441d

Cleans up sprawling state in PaymentView

c253409

First draft at step-up error logic

cf92b54

Added constants for error codes, and added comments to better explain…

9ec36ea

… various scenarios

Fixes doc-comment style

511ba7c

Dedupes fallback alerts

c753da6

mliberatore added 2 commits March 16, 2026 15:41

Adds StripeIssuing dependency

804d620

Adds phone verification check, and disambiguates two kycLevel compute…

8a751a6

…d properties

mliberatore added the Crypto Onramp SDK label Mar 17, 2026

Adds comment about commented-out code

5c9f802

mliberatore commented Mar 17, 2026

View reviewed changes

Re-documents KYCRecoveryFlowView declaration to include multi-step-up

666d168

mliberatore marked this pull request as ready for review March 17, 2026 17:26

mliberatore requested review from a team as code owners March 17, 2026 17:26

mliberatore commented Mar 17, 2026

View reviewed changes

mliberatore requested a review from mats-stripe March 17, 2026 17:29

Base automatically changed from mliberatore/crypto-onramp-l0-kyc-setting-and-initial-routing to master March 17, 2026 21:17

mliberatore added 2 commits March 17, 2026 17:21

Merge branch 'master' into mliberatore/crypto-onramp-l0-kyc

8afdb41

# Conflicts: # Example/CryptoOnramp Example/CryptoOnramp Example/CryptoOnrampFlowCoordinator.swift # Example/CryptoOnramp Example/CryptoOnramp Example/KYCLevel.swift

Updates README to include newly missing framework

b672825

mliberatore commented Mar 17, 2026

View reviewed changes

jeanregisser previously approved these changes Mar 17, 2026

View reviewed changes

Better demo backend error parsing

a746bdc

mliberatore dismissed jeanregisser’s stale review via a746bdc March 18, 2026 15:33

mliberatore requested a review from jeanregisser March 18, 2026 15:44

Re-adds isKycVerified check now that backend has deployed

d2baf82

mats-stripe approved these changes Mar 18, 2026

View reviewed changes

mliberatore merged commit 040c8dc into master Mar 18, 2026
7 checks passed

mliberatore deleted the mliberatore/crypto-onramp-l0-kyc branch March 18, 2026 18:57

mliberatore mentioned this pull request Mar 19, 2026

CryptoOnramp SDK: Example App Requested Changes for L0 KYC Mode #6226

Merged

Conversation

mliberatore commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Testing

Changelog

Uh oh!

mliberatore Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mliberatore Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeanregisser left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mats-stripe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mliberatore commented Mar 17, 2026 •

edited

Loading

mliberatore Mar 17, 2026 •

edited

Loading

mliberatore Mar 17, 2026 •

edited

Loading