Sharing Sumsub Verification
If you use Sumsub to verify your customers, you can share that verification with Swapped. The customer then skips the identity verification (ID document and liveness check) and the address verification steps that Sumsub already approved for you.
KYC sharing works with Sumsub only. If you use a different provider, or if Swapped cannot use the shared verification, the customer completes the standard verification in the widget.
How It Works
Your backend requests a share token from Sumsub for the customer.
Your backend adds the customer's email and the share token to the widget URL, and signs the URL.
The customer opens the widget and signs in with the email code that Swapped sends.
Swapped imports the approved verification steps from Sumsub. The widget asks the customer only for the steps that are missing.
Before You Start
Enable KYC sharing. Contact Swapped to enable KYC sharing for your account. Send us your Sumsub client ID.
Link the Sumsub accounts. Ask your Sumsub account manager to enable Reusable KYC between your Sumsub account and the Swapped Sumsub account. If the accounts are not linked, Sumsub rejects every share token.
Get customer consent. You share the customer's personal data with Swapped. Make sure that the customer agrees to this before you generate a share token.
Sign your widget URLs. This page uses the URL signature from iFrame Initialization.
Step 1: Generate a Share Token
Your backend requests a share token from Sumsub for the customer. Authenticate the request with your own Sumsub app token and secret key, and sign it as Sumsub requires (X-App-Token, X-App-Access-Ts, and X-App-Access-Sig headers). Refer to the Sumsub documentation. These credentials are secret, so send this request from your server only. Never send it from code that runs in the browser.
applicantId: The Sumsub applicant ID of the customer. This is the ID that Sumsub gives the applicant, not yourexternalUserId.forClientId: The Swapped Sumsub client ID. Always usebitinvestor_aps. Only Swapped can use the token.ttlInSecs: The time, in seconds, that the token stays valid. We recommend 600 or more. Refer to Token Rules.
Sumsub returns the token in the token field:
Step 2: Build the Widget URL
Build the widget URL as described in iFrame Initialization, then:
Add the
emailandkycShareTokenparameters to the URL. Theemailmust be the email on the Sumsub applicant.Create the signature from the query string.
Add the signature as the last parameter in the query string.
When the URL contains both email and kycShareToken, the widget locks the email field. The customer cannot change the email.
Example iFrame URL
What the Customer Sees
The widget opens with the email already filled in and locked.
The customer requests a sign-in code and enters it.
The widget skips the verification steps that Swapped imported from Sumsub. If Swapped imported all steps, the customer goes directly to the order.
The customer must sign in with the email code. If the customer signs in with Google, Swapped does not use the share token.
What Swapped Receives
Swapped accepts each verification step that Sumsub approved for your customer:
Proof of ID and Liveness Check: Sumsub must approve both steps. The customer then skips identity verification. If your Sumsub level does not include a liveness check, Swapped cannot import identity verification.
Proof of Address: Sumsub must approve this step. The customer then skips address verification.
Swapped copies the customer's name, date of birth, country, and address from the Sumsub applicant. If the applicant is approved for only some steps, the widget asks the customer only for the missing steps.
A share token can increase a customer's verification level. A share token cannot decrease it.
Token Rules
Two time limits apply. The Sumsub token expires
ttlInSecsafter you generate it. Separately, the customer must sign in within 5 minutes of opening the widget. Generate the token immediately before you open the widget, and setttlInSecsto 600 or more, so that the Sumsub token does not expire before the customer signs in.One token per widget open. You can use a share token only once. Generate a new token each time you open the widget. If you open the widget again for the same customer, the new token replaces the previous one.
Bound to the email and your API key. The token works only with the email in the signed URL, and only in a widget opened with your API key. The email match is not case-sensitive.
When Swapped Does Not Share the Verification
If Swapped cannot use the shared verification, the customer completes the standard verification flow. The widget does not show an error. This occurs in these conditions:
KYC sharing is not enabled for your account, or your Sumsub client ID is not set up with Swapped.
The token expired, or it was already used. For example, the widget was opened two times with the same URL.
The customer signed in with Google instead of the email code, or with a different email.
The Sumsub applicant has no email, or has an email that is different from the
emailparameter.The applicant has no approved identity step and no approved address step.
Sumsub rejects the reuse. For example, the applicant's document type is not accepted for Swapped, or the ID or address document is out of date.
The customer already has full verification with Swapped.
The applicant is already linked to a different Swapped account, or the customer's Swapped account is already linked to a different Sumsub applicant.
Swapped does not support the customer's country of residence, or that country requires a manual review.
Troubleshooting
The widget does not show why a shared verification was not used. To investigate a case, contact Swapped support with the customer's email and the approximate time that the customer opened the widget.
Last updated