Skip to content

Enhance KYC sharing documentation #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tierriMonteiro wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Enhance KYC sharing documentation #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions docs/kyc-sharing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,28 +8,46 @@ To improve the onboarding experience, we provide multiple ways to empower our bu

By receiving KYC details, Topper can reduce the amount of information requested from users, resulting in a faster and smoother KYC process.

Of the two approaches below, **KYC shareable tokens** is the recommended path. The **KYC sharing API** is an alternative for partners who do not use Sumsub or prefer a manual REST integration.

## KYC shareable tokens

:::tip
**Recommended approach** — use this whenever your KYC provider is Sumsub.
:::

When starting a Topper session, partners can provide a KYC shareable token, which will be used to ingest all available information for the required scopes.

Currently, we only support tokens from **Sumsub** provider.

:::note
Only applicants with a valid identity will be able to be ingested through the shareable token.
The Sumsub shareable token flow is only initiated when the user has a valid Sumsub identity **and** Topper requires identity (or related personal-data scopes) for the current session. If identity is not needed, the token is ignored.
Copy link
Copy Markdown
Contributor

@andregoncalvesdev andregoncalvesdev Jun 1, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Sumsub shareable token flow is only initiated when the applicant has a valid Sumsub identity and Topper requires identity for the current session. If identity is not needed, the token is ignored.

:::

:::info
To use KYC shareable tokens please see [crypto on-ramp](./flows/crypto-onramp.mdx) or [crypto off-ramp](./flows/crypto-offramp.mdx) flows documentation.
:::

### User experience

When the share token is accepted, the user sees their partner-provided identity document already marked as accepted in Topper and only needs to complete a fresh liveness check rendered by the Sumsub SDK.
Copy link
Copy Markdown
Contributor

@andregoncalvesdev andregoncalvesdev Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user will be presented with a KYC onboarding screen, where they will be required to capture a selfie as part of a liveness check to securely share their personal data. The Sumsub SDK will be initiated, allowing the user to clearly see the information they are about to share while guiding them through the liveness verification process. Once the selfie is successfully submitted, the user will either proceed to transact or, if necessary based on their country, be prompted to provide additional KYC details.

Copy link
Copy Markdown
Contributor

@andregoncalvesdev andregoncalvesdev Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And update images with the KYC onboarding screen, the initial screen after the SDK has been initiated, the steps screen, and the pre-initiate liveness check step.


| Identity already accepted | Sumsub liveness check |
|---------------------------|-----------------------|
| <img src="/images/kyc-sharing-identity-accepted.png" alt="Topper showing the identity document already accepted via the share token" width="300"/> | <img src="/images/kyc-sharing-liveness-check.png" alt="Sumsub SDK liveness check rendered inside Topper" width="300"/> |

## KYC sharing API

:::info
**Alternative approach** — use this only if you cannot integrate via Sumsub or prefer a manual REST integration.
:::

There is a REST API where partners can check user KYC details and share information regarding current missing or expired/outdated scopes.

Currently, we support the following scopes: **email**, **profile**, **address**, **phone**, and **identity**.

For more details, see the [KYC sharing documentation](https://developer.uphold.com/rest-apis/core-api/kyc/introduction).

:::info
To use the KYC sharing API, business customers need to complete a compliance check and be approved before gaining access.
To use the KYC sharing API, business customers must be reviewed and approved by Compliance to be authoritative for the shared scopes before gaining access.
:::
Binary file added static/images/kyc-sharing-identity-accepted.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/kyc-sharing-liveness-check.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading