Shared KYC integration

​

Product overview

​

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
   Make sure your app collects the information required for MoonPay’s KYC process.
2. Integrate Sumsub’s Reusable KYC
   Build Sumsub’s reusable KYC feature using their SDK or API.
3. Connect to Sumsub’s Share-Token API
   See Sumsub’s Share-Token API documentation. This will generate the share token you use to provide to MoonPay. Sumsub allows partners and their data to be transferred between services.
   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.
   Sandbox

   Production

   Example response

   # 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
               }'
   
   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

​

Integration guide

1. Enable KYC Sharing
   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
   Call our POST /v3/customers/import 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.
   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.
   Test mode

   Live environment

   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
       },
       ],
   }'
   
3. Calling the MoonPay widget
   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