> ## Documentation Index
> Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared KYC integration

> Expedite onboarding your KYCed users if you are already using Sumsub as your KYC provider.

## Product overview

Partners who are doing some form of KYC collection/verification using Sumsub will be able to pass KYC information to MoonPay via a share token so that we can expedite your users' verification. Doing so will dramatically reduce friction with your users by only having to KYC once. This is in addition to MoonPay's 20M verified users, millions of which we've KYCed with an ID & selfie.

## Product benefits

* **Higher conversion** – users skip a second ID & selfie step inside MoonPay, dramatically reducing drop‑offs.
* **Expanded reach** – MoonPay’s >20 M verified‑user database increases the chance we already know your customers.
* **Simple and secure integration** – a single endpoint, no sensitive PII passed directly to MoonPay.

## Prerequisites

1. **Verify required KYC information**<br />Make sure your app collects the [information required for MoonPay's KYC process](https://support.moonpay.com/en/articles/383332-how-to-verify-your-moonpay-account#h_0c35aef97d).
2. **Integrate Sumsub's Reusable KYC**<br />Build [Sumsub's reusable KYC feature](https://docs.sumsub.com/docs/reusable-kyc#get-started) using their SDK or API.
3. **Connect to Sumsub's Share-Token API**<br />See [Sumsub's Share-Token API documentation](https://docs.sumsub.com/reference/generate-share-token). This will generate the share token you use to provide to MoonPay. Sumsub allows partners and their data to be transferred between services.

   <Warning>
     `forClientId` must be exactly `Moonpay` — capital `M`, lowercase `p`, no
     space. Any other casing or spelling produces a token MoonPay cannot redeem.
     This is the most common integration failure on this flow.
   </Warning>

   <CodeGroup>
     ```bash Sandbox theme={null}
     # request signing skipped for brevity
     curl --request POST \
         --url https://api.sumsub.com/resources/accessTokens/shareToken \
         --header 'content-type: application/json' \
         --header 'x-app-token: sbx:...'
         --data '{
                  "applicantId": "{{applicantId}}", // applicant id they want to import
                  "forClientId": "Moonpay",
                  "ttlInSecs": 600
                 }'
     ```

     ```bash Production theme={null}
     # request signing skipped for brevity
     curl --request POST \
         --url https://api.sumsub.com/resources/accessTokens/shareToken \
         --header 'content-type: application/json' \
         --header 'x-app-token: prd:...'
         --data '{
                  "applicantId": "{{applicantId}}", // applicant id they want to import
                  "forClientId": "Moonpay",
                  "ttlInSecs": 600
                 }'
     ```

     ```json Example response theme={null}
     {
       "token": "{{shareToken}}",
       "forClientId": "Moonpay"
     }
     ```
   </CodeGroup>

   `ttlInSecs` is the lifetime of the share token, `600` seconds in the example above. The token is single use, so generate one per import call rather than caching it and reusing it across customers or retries.

### Sandbox and production

Sandbox and production are two separate switches, and they have to match:

| Environment | Sumsub app token prefix | MoonPay secret key prefix |
| - | - | - |
| Sandbox | `sbx:` | `sk_test_` |
| Production | `prd:` | `sk_live_` |

A sandbox share token cannot be imported with a live key, and the reverse also fails.

## Integration guide

1. **Enable KYC Sharing**<br />Reach out to your MoonPay representative and we will enable your account for KYC sharing in our backend.

2. **Share your customers data with MoonPay**<br />Call our [`POST /v3/customers/import`](/api-reference/widget/importcustomer) endpoint with the `externalCustomerId` and the SumSub share token (see payload below). The `externalCustomerId` is a unique identifier for the customer in **your** platform. A successful import returns HTTP 200 with an empty body.

   <Warning>
     This call authenticates with your **secret** key (`sk_test_` or
     `sk_live_`), so it must be made from your server. Never ship a secret key
     in client-side code or expose it in a browser or mobile app.
   </Warning>

   <CodeGroup>
     ```sh Test mode theme={null}
     curl --request POST \
         --url https://api.moonpay.com/v3/customers/import \
         --header 'content-type: application/json' \
         --header 'authorization: api-key sk_test_...'
         --data '{
         externalCustomerId: '{{userIdInPartner}}',  // unique identifier for the customer in the partner platform
         identity: [
         {
             source: 'sumsub',
             shareToken: '{{shareToken}}',  // share token from the Sumsub Share-Token API
         },
         ],
     }'
     ```

     ```sh Live environment theme={null}
     curl --request POST \
         --url https://api.moonpay.com/v3/customers/import \
         --header 'content-type: application/json' \
         --header 'authorization: api-key sk_live_...'
         --data '{
         externalCustomerId: '{{userIdInPartner}}',  // unique identifier for the customer in the partner platform
         identity: [
         {
             source: 'sumsub',
             shareToken: '{{shareToken}}',  // share token from the Sumsub Share-Token API
         },
         ],
     }'
     ```
   </CodeGroup>

3. **Calling the MoonPay widget**<br />When loading the MoonPay widget, make sure the same `externalCustomerId` is passed as a parameter. MoonPay will require the exact identifier to retrieve the user data and verify their KYC.

## Sharing KYC data in the other direction

Shared KYC imports identity data **into** MoonPay from your Sumsub account. If you instead need MoonPay-verified KYC data to leave MoonPay and land in another system, that is the opposite direction — see [Export customer data](/platform/guides/export-customer-data).