# Sumsub Reusable KYC



If your users have already completed KYC verification through Sumsub with your platform, you can import their verification data to Paytrie. This eliminates the need for users to complete identity verification again.

## Overview [#overview]

Sumsub's Reusable KYC feature allows identity verification data to be shared between platforms. As a "Donor" platform, you generate a share token for a user's verification data, which Paytrie then imports as the "Recipient" platform.

## Prerequisites [#prerequisites]

* Your platform must be integrated with [Sumsub](https://sumsub.com/)
* The user must have completed KYC verification on your platform
* You must have API access to generate Sumsub share tokens
* The user must already exist in Paytrie under your API key — create them first using `POST /v2/users` with the same API key you'll use for the import
* The Sumsub applicant must be verified in a level that meets Paytrie's [verification level requirements](#verification-level-requirements)

## Verification level requirements [#verification-level-requirements]

Sumsub only allows a share token to be reused when the applicant's level on your side covers every step of the recipient (Paytrie) level, so the level you verify applicants in must include both of these steps:

1. **Identity document** — capture method `File upload`, accepting any of: driver's license, ID card, residence permit, passport
2. **Selfie** — selfie type `Advanced liveness check`

The applicant must have completed and passed both steps before you generate the share token. Applicants who only have profile data (name, date of birth, address) and are still waiting to upload a document or selfie will be rejected on import.

This is what the level looks like in the Sumsub dashboard:

<ImageZoom src="/images/integrations/sumsub-verification-level.png" alt="Sumsub verification level with an Identity document step (file upload; driver's license, ID card, residence permit, passport) and a Selfie step (advanced liveness check)" width="1266" height="1219" />

See Sumsub's guide on [configuring verification levels](https://docs.sumsub.com/docs/configure-verification-levels) for how to set this up in your dashboard.

## Integration flow [#integration-flow]

<Steps>
  <Step>
    ### Create API user in Paytrie [#create-api-user-in-paytrie]

    Register the user in Paytrie first using `POST /v2/users` and note the returned user ID — the import writes the KYC data to that user.
  </Step>

  <Step>
    ### Generate share token [#generate-share-token]

    Use the Sumsub API to generate a share token for the user's verification data from an applicant verified in a level that meets the requirements above.
  </Step>

  <Step>
    ### Submit to Paytrie [#submit-to-paytrie]

    Send the share token to the Paytrie import endpoint.
  </Step>

  <Step>
    ### User verified [#user-verified]

    If successful, the user is automatically verified on Paytrie without additional KYC.
  </Step>
</Steps>

## Quick start [#quick-start]

### 1. Create the user in Paytrie [#1-create-the-user-in-paytrie]

Create the Paytrie user first:

```bash
curl -X POST "https://api.paytrie.com/v2/users" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "dob": "1990-01-15",
    "phone": "4165551234",
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "Toronto",
    "province": "on",
    "postalCode": "M5V1A1",
    "occupation": "Software Engineer",
    "pep": false,
    "tpd": false
  }'
```

<Card title="API Reference: Create a new user" href="/v2/api-reference/users/createUser" icon="arrow-right-left">
  View complete request parameters and response schema
</Card>

### 2. Generate a share token (Sumsub API) [#2-generate-a-share-token-sumsub-api]

Use the Sumsub API to generate a share token for a specific applicant that is
verified in a Sumsub level that meets the [requirements above](#verification-level-requirements):

```bash
curl -X POST "https://api.sumsub.com/resources/accessTokens/shareToken" \
  -H "X-App-Token: your-sumsub-token" \
  -H "X-App-Access-Sig: your-signature" \
  -H "X-App-Access-Ts: timestamp" \
  -d '{
    "applicantId": <applicant Id value>,
    "forClientId": <partner client id>
  }'
```

See the [Sumsub documentation](https://docs.sumsub.com/reference/generate-share-token) for complete details.

<Callout type="info">
  **Paytrie's partner ID (client ID) is `paytrie_147641`.** Use it as the
  `forClientId` (recipient client ID) shown above when generating the share
  token so the verification is shared with Paytrie as the recipient platform.
</Callout>

<Callout type="warn">
  **The applicant's level must cover Paytrie's verification level
  requirements.** Sumsub rejects share tokens on import when the applicant has
  not completed both an identity document and an advanced-liveness selfie. See
  [Verification level requirements](#verification-level-requirements).
</Callout>

### 3. Import to Paytrie [#3-import-to-paytrie]

Submit the Sumsub share token to import the user's verification, using the `userId` returned when you created the user in step 1.

```bash
curl -X PUT "https://api.paytrie.com/v2/users/{userId}/kyc" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer eyJhbGciOiJI...." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sumsub",
    "payload": {
      "shareToken": "_act-sb-jwt-eyJHGCi........tN0."
    }
  }'
```

<Card title="API Reference: Import KYC data for a user" href="/v2/api-reference/users/importUserKyc" icon="arrow-right-left">
  View complete request parameters and response schema
</Card>

## Common errors [#common-errors]

| Error                                                                             | Description                                                                                                        | Solution                                                                                                                                                        |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Token expired                                                                     | The share token has expired                                                                                        | Generate a new share token                                                                                                                                      |
| Token invalid                                                                     | The share token is malformed                                                                                       | Verify the token format                                                                                                                                         |
| Applicant not found                                                               | The applicant doesn't exist in Sumsub                                                                              | Verify the applicant ID                                                                                                                                         |
| `The applicant has not completed the verification steps Paytrie requires...`      | The applicant is missing the identity document or the liveness selfie                                              | Configure your level per [Verification level requirements](#verification-level-requirements), have the applicant complete both steps, then generate a new token |
| `The share token is not valid for Paytrie's Sumsub verification level...`         | The share token comes from a level that doesn't cover Paytrie's requirements                                       | Configure your level per [Verification level requirements](#verification-level-requirements), then generate a new token                                         |
| `The applicant has not been approved in Sumsub yet...`                            | The applicant's review on your side hasn't reached an approved state                                               | Wait for Sumsub to approve the applicant, then generate a new token                                                                                             |
| `Email is required: the Sumsub share token does not carry an email...`            | Your Sumsub applicant doesn't have `applicantIdentifiers.email` set, and you didn't include `email` in the request | Pass the user's email in the request body (the same email you used when creating the user with `POST /v2/users`)                                                |
| `Email in request does not match the email on the Sumsub applicant.`              | The `email` you sent and the email Sumsub has on the applicant differ                                              | Send the email that matches the applicant on Sumsub, or create the user with `POST /v2/users` using the email Sumsub holds before importing                     |
| `Unable to import: please complete registration on Paytrie before importing KYC.` | No Paytrie user exists for that email **under your API key**                                                       | Make sure you created the user with `POST /v2/users` first, using the same email *and* the same API key you're using for the import                             |

<Callout type="warn">
  **Enable the `Share applicants data` permission on your Sumsub app token.**
  The app token you use to authenticate Sumsub API requests (for example,
  generating the share token) must have the [`Share applicants data`
  permission](https://docs.sumsub.com/docs/user-roles#permissions) enabled.
  Without it, Sumsub rejects the request with a permission error.
</Callout>

## Additional resources [#additional-resources]

<Cards>
  <Card title="Sumsub Reusable KYC" href="https://docs.sumsub.com/docs/reusable-kyc" icon="external-link">
    Sumsub's official documentation on Reusable KYC
  </Card>

  <Card title="Generate Share Token" href="https://docs.sumsub.com/reference/generate-share-token" icon="external-link">
    API reference for generating share tokens
  </Card>

  <Card title="Error Codes" href="https://docs.sumsub.com/reference/reuse-applicant-for-reusable-kyc#error-codes-with-descriptions" icon="external-link">
    Complete list of Sumsub error codes
  </Card>
</Cards>