Reuse a customer’s existing Sumsub verification with a share token instead of re-collecting their KYC.
Sumsub token sharing is only available for Consumer Card Programs.
Sumsub token sharing works in both sandbox and production. Run this flow twice, once for sandbox and once for production.
Your Sumsub environment must match Rain’s environment. Tokens generated from a production Sumsub instance will not work in Rain’s sandbox, and vice versa. Ensure you are using the correct Sumsub environment for the Rain environment you are integrating with.
This flow has two phases: connect your Sumsub account to Rain once per environment (steps 1-4), then generate and send a share token for each applicant you verify (steps 5-6).
1
Request a donor key
Contact Rain to request a donor key for the desired environment (sandbox or production).
Sandbox and production environments require separate donor keys. Request a sandbox key first to test the integration, then request a production key when you are ready to go live.
The key will look something like eyJ....
2
Switch your Sumsub instance to the right environment
In your Sumsub dashboard, toggle the environment from Production to Sandbox. A yellow banner indicating “You’re in Sandbox mode” appears when sandbox is active. Remember the key needs to match the environment.
The yellow banner indicates you are in sandbox mode
3
Add Rain as a recipient
Navigate to Reusable Identity > Partners > Recipients in your Sumsub dashboard
Click Add recipient
Enter the donor key that Rain provided
Click Continue to complete the setup
The Recipients page in Sumsub
Enter the donor key in the Add recipient dialog
4
Turn on the required fields
Your Sumsub instance must be configured to collect the following fields for Rain to process the consumer application.
Sumsub field
Description
firstName
The person’s first name
lastName
The person’s last name
birthDate
The person’s birth date
tin
The person’s national ID (9-digit SSN if country of issue is US)
countryOfIssue
The country that issued the national ID
email
The person’s email address
phoneNumber
The user’s phone number (ITU-T E.164 format)
address.line1
Address line 1
address.city
City
address.region
State or region
address.postalCode
Postal code
address.countryCode
Country code (ISO 3166-1 alpha-2 format)
Make sure all required fields are enabled in your Sumsub applicant data settings before generating share tokens. Missing fields will cause the application to fail.
5
Generate a share token
Generate a share token in your Sumsub for each applicant you want to verify with Rain. A share token is single-use and looks like _act-sbx-j.... You can generate one in two ways:
Use the Sumsub endpoint to generate a share token. Pass in Rain’s client ID raincards.xyz_43942 in Sumsub’s forClientId field.
Generate it directly from the Sumsub website
Open a production or sandbox applicant in Sumsub
Click the three-dot menu (⋮) in the top-right corner
Select Generate share token
Click Generate to create the token
Copy the token.
Select Generate share token from the menu
Copy the generated share token
6
Use the share token in your application
When creating a consumer application, use the share token you generated in Step 5 and pass it in through Rain’s sumsubShareToken field. You must still submit other required fields, such as the user’s occupation, salary, and phone number, but most of the user fields can be omitted. The endpoint reference lists every required field.
If you encounter the error “Token is invalid, make sure you generate a new one each time, because the old ones are invalidated upon usage”, check for these common causes:
Issue
Solution
Token already used
Share tokens can only be used once. Generate a new token for each application submission.
Wrong environment
Make sure you are in the desired environment. If testing in sandbox, switch the toggle from Production to Sandbox in your Sumsub dashboard. You should see the yellow “You’re in Sandbox mode” banner at the top.
Missing required fields
Ensure all required fields are filled in the Sumsub application before generating the token.
