Proposal: SEP-?? - WebView-Based KYC Flow (Alternative to SEP-12)

[ydag]

Summary

We are proposing SEP-??, a WebView-based KYC flow as an alternative to SEP-12’s API-based approach. This does not replace SEP-12 or SEP-24 but provides an optional way for wallets and anchors to handle KYC using an interactive WebView.

Rationale

Many local anchors we work with require users to submit KYC every time they initiate their first transaction. When integrating SEP-6, we found that replacing SEP-12 with an interactive WebView was a better alternative for several reasons:

• Simplified Implementation: Some anchors struggle to implement SEP-12’s API-based approach, sometimes taking years to finalize it. WebView-based KYC eliminates these complexities.
• Better UX: Many financial platforms already use WebView-based KYC before processing transactions.
• Anchor Flexibility: Some anchors have tiered KYC, where additional KYC is needed above certain limits. A WebView allows this to be handled more dynamically.
• No Changes to SEP-24: SEP-24 remains unchanged. SEP-?? is specifically useful for cases where SEP-6 is used, and SEP-12 would otherwise require API-based integration.

How SEP-?? Works

1. User chooses to deposit/withdraw via an anchor.
2. Wallet checks if the user is KYC’d. If not, it fetches a WebView URL.
3. User completes KYC in the WebView (e.g., SumSub, other KYC providers).
4. Once KYC is completed, the user can continue their transaction via SEP-6.

Full SEP-?? Proposal

Abstract

This SEP defines a standard for Stellar clients to complete KYC verification through a WebView-based flow, providing an alternative to SEP-12’s API-based submission. It enables a seamless user experience while ensuring interoperability between wallets and anchors. The standard supports authentication via SEP-10. Anchors implement a WebView-based KYC flow, while wallets open and interact with it, ensuring compatibility across services.

Key Points of SEP-??

• No Changes to Existing SEPs: SEP-24, SEP-12, and SEP-6 remain unchanged. No anchor is required to modify their current implementation.
• Optional Adoption: SEP-?? is completely optional for anchors and wallets that prefer a WebView-based KYC flow.
• Minimal Changes from SEP-12: SEP-?? closely follows SEP-12 with minor modifications to support an interactive WebView approach.

Prerequisites

An anchor must define the location of its KYC_WEBVIEW_SERVER in its stellar.toml file if it supports WebView-based KYC. This allows client apps to locate the anchor’s WebView-based KYC service.

Anchors and clients must support at least one of SEP-10 or SEP-45 for web authentication and use it for all WebView-based KYC interactions.

Customer GET

This endpoint allows clients to:

1. Retrieve the KYC WebView URL for new customer registration

If the server does not have a registered customer matching the provided parameters, it should return the WebView URL where the user can complete their KYC.

2. Check the KYC status of an existing customer

This allows clients to verify whether a customer’s KYC is accepted, rejected, not needed, or still needs more info. If additional or updated KYC information is required, the response should include the WebView URL where the user can complete or update their KYC process.

GET [KYC_WEBVIEW_SERVER]/customer?id=<id>&type=<type>
GET [KYC_WEBVIEW_SERVER]/customer?memo=<memo>&type=<type>
GET [KYC_WEBVIEW_SERVER]/customer?type=<type>&asset_code=<asset_code>&amount=<amount>&payment_type=<payment_type>

Request

Name	Type	Description
id	string	(optional) The ID of the customer as returned in the response of a previous GET request. If the customer has not been registered, they do not yet have an id.
memo	string	(optional) the client-generated memo that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's sub value, it must match this parameter value. If a muxed account is used as the JWT's sub value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. If the account is a C... account, the memo must not be specified. See the Shared Accounts section for more information.
type	string	(optional) the type of action the customer is being KYCd for. See the Type Specification below.
asset_code	string	(optional) The asset involved in the transaction, specified using its Stellar asset code (e.g., USDC). Required if the KYC process is asset-specific.
amount	string	(optional) The amount involved in the transaction. Used if KYC requirements depend on the transaction value. Should be a string representation of a decimal number
payment_type	string	(optional) The type of payment associated with the KYC process. Such as bank, credit_card, or other anchor-specific values.
lang	string	(optional) Defaults to en. Language code specified using ISO 639-1. Human readable descriptions, choices, and messages should be in this language.

Response

Name	Type	Description
id	string	(optional) ID of the customer, if the customer has already been created previously.
status	string	Status of the customer's KYC process.
url	string	(optional) The WebView URL provided by the anchor where the customer can complete the KYC process. The wallet should open this URL in a WebView to allow the user to submit their KYC information interactively.
message	string	(optional) Human-readable message describing the current state of the customer's KYC process.

Customer Statuses

Status	Description
ACCEPTED	Interactive KYC have been accepted and the customer has been validated for the type passed. It is possible for an accepted customer to move back to another status if the KYC provider determines it needs more info at a later date, or if the customer shows up on a sanctions list.
PROCESSING	KYC process is in flight and client can check again in the future to see if any further info is needed.
NEEDS_INFO	More info needs to be provided to finish KYC for this customer. The url entry is required in this case.
NOT_NEEDED	The anchor does not require KYC for this request. The user can proceed without submitting KYC.
REJECTED	This customer's KYC has failed and will never succeed. The message must be supplied in this case.

Looking for Feedback

We’d love to hear the Stellar community’s thoughts on SEP-??. If there’s general support, we can move forward with formalizing SEP-??. Looking forward to your thoughts! 🚀

[kaning]

Unfortunately, I have only one vote I would have voted for this twice

As an anchor implementing KYC for SEP 6 and SEP 24 transactions, this would be really useful. If we had an interactive KYC process, we can leverage already existing provider SDKs etc to make a SEP 6 transaction a lot more seamless. It could even be used ahead of a SEP 24 transaction, because at the moment, we "bake" SEP 12 into 24 but if it's separated like this, both processes can be cleanly segregated.

Also this saves the anchor implementation details such as binary upload logic, and file processing if we already have the KYC providers doing that work, we can just leverage it.

[JakeUrban]

Thanks for writing the proposal @ydag, I think my primary question is "Instead of adding an interactive webview prior to the SEP-6 flow, why not use SEP-24?".

If its because SEP-24 requires a webview for every transaction, rather than just the first time, should we consider making the webview in SEP-24 an optional step?

[kaning]

Are you suggesting a potential two step process for SEP24...

• Optional WebView SEP 12
• WebView SEP 24
  ?

[ydag]

Hey @JakeUrban! Thanks for your response. There are a few reasons we didn’t go with that approach:

No control over when KYC happens in SEP-24

Right now, we can’t decide when the user completes KYC if we rely on SEP-24. They’d have to go through the SEP-24 flow at least once, and only then could we navigate them to SEP-6. That’s not a great user experience—it’s confusing and unnecessary.

Forcing SEP-6 anchors to implement SEP-24

Some anchors only want to support SEP-6, but under this approach, they’d have to also implement SEP-24 just for KYC. That makes things way too tightly coupled (as @kaning mentioned) and forces extra work on anchors who don’t even need SEP-24 otherwise.

More flexibility for wallets

Keeping KYC separate makes it much easier for wallets to handle things cleanly. Instead of dealing with SEP-24-specific flows, they can just integrate KYC however makes the most sense for them.

Not just for anchors—other players need KYC too

Some companies, like Kulipa, aren’t anchors but still need to verify users. They prefer handling KYC via WebView, and SEP-24 doesn’t apply to them at all. Having a separate KYC standard (SEP-46) makes it easier to ask them to follow Stellar standards without unnecessary SEP-24 overhead.

Bottom line: Keeping KYC separate makes everything cleaner, avoids unnecessary dependencies, and keeps things flexible for both wallets and anchors.

[philipliu]

Have we considered supporting something like SEP-12's transaction_id parameter? This would replace the asset_code, amount, and payment_types parameters. It would allow anchors to request additional KYC information beyond these fields without changes to the SEP.

[ydag]

Hi @philipliu, thanks for your message.

SEP-24 already ties KYC to a transaction, but SEP-6 doesn’t require this. If we switch to transaction_id in SEP-46, it means anchors must always create transactions before KYC. But some users complete KYC before initiating a transaction, so this approach might be too restrictive. Do we expect all KYC to be tied to an anchor transaction upfront, or should we allow independent KYC like SEP-12?

[lijamie98]

Echoing @JakeUrban comments, SEP-6 is designed for API flow which also includes the KYC. Having a WebView for KYC, it creates a mix of API flow and interactive WebView flow. On the surface, we may benefit from both flows, we also suffers from the hassle of handling both flows.

If an anchor already has WebView for KYC, I think it would be natural to use WebView for creating transactions if necessary. The SEP-24 create transaction call has most of the SEP-6 request parameters covered. It would be an easy modification to make the interactive url optional.

However, making the url optional` may break some of the wallet implementations that expect to open a web view in SEP-24 flow.

[kaning]

As it stands now... the WebView for KYC is tightly coupled with our 24 view because there's no standard way a wallet can trigger just SEP 12 so we had to "shim" it in somewhere. I guess it would be good to have a "decoupled" KYC process that's not only non-interactive...

[ydag]

Echoing @JakeUrban comments, SEP-6 is designed for API flow which also includes the KYC. Having a WebView for KYC, it creates a mix of API flow and interactive WebView flow. On the surface, we may benefit from both flows, we also suffers from the hassle of handling both flows.

Hey @lijamie98. Good points, but I believe we can benefit from this even more because both anchors and wallets must implement SEP-12 for KYC in order to use SEP-6. This adds extra development and maintenance efforts for both wallets and anchors, which can be tricky. Instead, they could leverage specialized KYC frameworks like Sumsub and provide a much better UX via WebView.

Since the proposed SEP is fully optional, it won’t break any existing wallet or anchor implementations.

I also agree with @kaning that having a decoupled KYC process could bring even more benefits.