SumSub Token Sharing

Introduction

If your organization already verifies customers through SumSub, you can share that verification data with MoonPay using a share token. Your customers do not need to go through KYC again. This requires a tri-party agreement between MoonPay, your organization, and SumSub. Once signed, the integration is straightforward:

Prepare your SumSub applicant

The profile must include contact info, address, and (for US citizens or residents) an SSN or ITIN in fixedInfo.tin. For IP, follow IP address: supply it (or use SumSub IP capture) when you need EUR-related capabilities. Otherwise you can omit ip_address on the MoonPay request.

Generate a share token

Call SumSub’s API to create a one-time share token for your applicant.

Submit the token to MoonPay

Send the token to MoonPay’s identification endpoint with the required parameters.

Handle the response

If the data is sufficient, onboarding completes in seconds. If not, redirect the customer to complete the missing steps.

What Data Does MoonPay Expect?

At minimum, MoonPay expects the applicant data described in the standard onboarding requirements. The share token must carry enough verified data to satisfy these requirements. US citizens and residents must also have an SSN or ITIN in fixedInfo.tin before sharing. See US citizens and residents: SSN and TIN. To keep onboarding smooth and avoid extra steps for your customer:

Include the KYC questionnaire in your request. This covers employment status, income, source of wealth, and transaction expectations, which SumSub does not typically collect.
Include the EDD questionnaire as well if you already know the customer will transact large amounts or resides in a higher-risk jurisdiction. This prevents a step-up flow later.

If any required data is missing, MoonPay returns a Pending status with a url. This URL opens a hosted SumSub flow that only asks for the missing information, not a full KYC redo. You should redirect your customer to this URL to complete onboarding. See handling missing information for details.

Preparing Your SumSub Applicant

Before generating a share token, the applicant’s SumSub profile must contain all the data MoonPay requires. Missing fields are the most common cause of failed or incomplete token shares.

IP Address

MoonPay uses the applicant’s IP address for fraud and geo signals (including where EUR / euro-denominated or SEPA-related capabilities apply). You can provide it in one of three ways:

SumSub IP tracking: Enable SumSub’s IP address tracking so the IP is captured automatically during verification.
Metadata on the applicant: Store the IP as metadata on the SumSub applicant so it is included in the shared data.
Via the MoonPay API: Pass the ip_address field directly in your identification request to MoonPay.

If you use SumSub’s IP tracking, you do not need to pass ip_address in the MoonPay API call. MoonPay reads it from the shared applicant data.

If your integration does not require EUR (for example, no euro virtual accounts, SEPA, or other euro-specific MoonPay flows), you can omit ip_address on the MoonPay identification request. If you do need EUR-related capabilities, supply the IP using one of the options above so checks can run reliably.

Required Applicant Data

The following fields must be present on the SumSub applicant’s fixedInfo before sharing. If your KYC flow does not collect them, use SumSub’s Change Provided Info endpoint to PATCH them onto the applicant.

Field	Location	Description
`phone`	Top-level	Applicant’s phone number (e.g. `+12345678`)
`nationality`	`fixedInfo`	ISO 3166-1 alpha-3 country code (e.g. `DEU`)
`tin`	`fixedInfo`	SSN or ITIN. Required for US citizens and residents. A value starting with `9` is read as an ITIN, otherwise an SSN. Dashes are allowed.
`street`	`fixedInfo.addresses[]`	Street address
`town`	`fixedInfo.addresses[]`	City
`postCode`	`fixedInfo.addresses[]`	Postal code
`country`	`fixedInfo.addresses[]`	ISO 3166-1 alpha-3 country code

US citizens and residents: SSN and TIN

For US citizens or US residents, MoonPay requires a Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). See Individual KYC standard onboarding for the full requirement. Set this value on the applicant’s fixedInfo.tin field before you generate the share token. If your KYC flow does not collect it, PATCH it onto the applicant with SumSub’s Change Provided Info endpoint. A value starting with 9 is treated as an ITIN, otherwise as an SSN. Dashes are stripped, so 123-45-6789 and 123456789 are equivalent.

Sample Applicant

Below is a representative SumSub applicant object showing the fields MoonPay needs. Fields extracted automatically by SumSub (document data, review results, questionnaires) are omitted for brevity.

{
  "clientId": "iron.xyz",
  "info": {
    "firstName": "John",
    "firstNameEn": "John",
    "lastName": "Doe",
    "lastNameEn": "Doe",
    "dob": "1990-01-11",
    "country": "DEU"
  },
  "fixedInfo": {
    "firstName": "John",
    "firstNameEn": "John",
    "lastName": "Doe",
    "lastNameEn": "Doe",
    "dob": "1990-01-11",
    "country": "DEU",
    "nationality": "DEU",
    "addresses": [
      {
        "street": "5 some street.",
        "streetEn": "5 some street.",
        "stateCode": "DE-BE",
        "town": "Berlin",
        "townEn": "Berlin",
        "postCode": "12345",
        "country": "DEU",
        "formattedAddress": "5 some street., Berlin, Germany, 10247"
      }
    ]
  },
  "email": "john.doe@gmail.com",
  "phone": "+12345678",
  "lang": "en",
  "type": "individual"
}

The fixedInfo block is the most important section: it contains the data that was provided by the customer and must be collected during your flow or PATCHed via the SumSub API. The info block is typically populated by SumSub’s document extraction and does not need manual intervention.

Integration

Use SumSub’s share token API to issue a one-time token. This call is made server-side using your SumSub credentials.

curl --request POST \
  --url https://api.sumsub.com/resources/accessTokens/shareToken \
  --header 'Content-Type: application/json' \
  --header 'X-App-Token: <your-sumsub-app-token>' \
  --data '{
    "applicantId": "YOUR_APPLICANT_ID",
    "forClientId": "iron.xyz",
    "ttlInSecs": 600
  }'

Share tokens are single-use: SumSub invalidates a token after it has been consumed. Generate a new token for each submission attempt.

2. Submit the Token to MoonPay

POST /api/customers/<customer_id>/identifications/v2

Headers

Header	Required	Description
`X-API-Key`	Yes	Your MoonPay API key
`Idempotency-Key`	Yes	A unique UUID. Prevents duplicate identifications if retried.
`X-Sub-Partner-ID`	No	Sub-partner UUID, if scoped to a sub-partner

Body Parameters

Parameter	Type	Required	Description
`type`	`"Token"`	Yes	Must be `"Token"`
`token`	string	Yes	The SumSub share token
`intended_use`	string	Yes	One of: `Investing`, `PaymentToFriendsFamilyorOthers`, `PurchaseDigitalAssets`, `OnlinePurchasesOfGoodsOrServices`, `Trading`
`ip_address`	string	No	Applicant IP for fraud/geo signals. Optional if captured via SumSub. See IP address. You can omit it when your integration does not require EUR; otherwise supply it (API, SumSub tracking, or applicant metadata).
`kyc_questionnaire`	object	Recommended	See KYC questionnaire fields. Omitting this field causes a `Pending` response requiring a step-up flow for the customer.
`edd_questionnaire`	object	No	See EDD questionnaire fields. EDD is only triggered when you include this object. Omitting it means EDD is not applied.

with_edd is a response field only. It reflects whether EDD was applied to the identification. Do not include it in your request body — Iron ignores it.

Basic Request

At minimum, provide the token and intended use:

curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2 \
     --header 'X-API-Key: <your-api-key>' \
     --header 'Idempotency-Key: <unique-request-id>' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "type": "Token",
       "token": "sumsub_token",
       "intended_use": "Investing",
       "ip_address": "203.0.113.42"
     }'

With KYC Questionnaire

Include the questionnaire to avoid the customer being redirected to a step-up flow:

curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2 \
     --header 'X-API-Key: <your-api-key>' \
     --header 'Idempotency-Key: <unique-request-id>' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "type": "Token",
       "token": "sumsub_token",
       "intended_use": "Investing",
       "ip_address": "203.0.113.42",
       "kyc_questionnaire": {
         "employment_status": "Employed",
         "yearly_gross_income": "From50001To60000",
         "source_of_wealth": "Salary",
         "expected_monthly_transaction_count": "Between5And10",
         "expected_monthly_transaction_volume": "MoreThan500LessThan2000"
       }
     }'

With KYC + EDD Questionnaire

If the customer resides in a higher-risk jurisdiction or will transact large amounts, include both to complete onboarding in one step:

curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2 \
     --header 'X-API-Key: <your-api-key>' \
     --header 'Idempotency-Key: <unique-request-id>' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "type": "Token",
       "token": "sumsub_token",
       "intended_use": "Investing",
       "ip_address": "203.0.113.42",
       "kyc_questionnaire": {
         "employment_status": "Employed",
         "yearly_gross_income": "From50001To60000",
         "source_of_wealth": "Salary",
         "expected_monthly_transaction_count": "Between5And10",
         "expected_monthly_transaction_volume": "MoreThan500LessThan2000"
       },
       "edd_questionnaire": {
         "occupation": "FinancialServices",
         "approximate_net_worth": "Between100001And300000",
         "source_of_funds_proof": "<base64-encoded-document>"
       }
     }'

KYC Questionnaire Fields

Field	Values
`employment_status`	`Employed`, `SelfEmployed`, `Unemployed`, `Retired`, `Student`
`yearly_gross_income`	`LessThan20000`, `From20001To30000`, `From30001To40000`, `From40001To50000`, `From50001To60000`, `From60001To70000`, `From70001To80000`, `From80001To90000`, `From90001To100000`, `From100001To110000`, `From110001To120000`, `From120001To130000`, `From130001To140000`, `From140001To150000`, `MoreThan150000`, `From150001To200000`, `From200001To500000`, `MoreThan500000`
`source_of_wealth`	`Salary`, `Savings`, `Investments`, `CryptoTrading`, `Other`
`expected_monthly_transaction_count`	`LessThan5`, `Between5And10`, `MoreThan10`
`expected_monthly_transaction_volume`	`LessThan500`, `MoreThan500LessThan2000`, `MoreThan2000`

EDD Questionnaire Fields

Field	Values
`occupation`	`Agriculture`, `ArtsAndEntertainment`, `Construction`, `Education`, `FinancialServices`, `InformationAndTechnology`, `Retail`, `RealEstate`, `Other`, `BusinessOwner`, `Healthcare`, `Industrial`, `LegalServices`, `PublicSector`, `SeniorManagement`
`approximate_net_worth`	`UpTo25000`, `Between25001And50000`, `Between50001And100000`, `Between100001And300000`, `Between300001And500000`, `Between500001And1000000`, `Over1000001`
`source_of_funds_proof`	Base64-encoded document (jpg, png, pdf, doc, docx, xls, xlsx, odt, ods, txt). Max 10 MB.

3. Handle the Response

The endpoint returns an Identification object:

Field	Type	Description
`id`	string (UUID)	Unique identification ID
`customer_id`	string (UUID)	The customer this identification belongs to
`status`	string	Current status. See Identification Lifecycle.
`with_edd`	boolean or null	Whether EDD was applied: `true`, `false`, or `null` for pre-feature identifications. See Tracking EDD Status.
`url`	string or null	If `Pending`, redirect the customer to this URL to complete missing steps
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Sufficient data: onboarding proceeds immediately. with_edd reflects whether EDD was applied — it is set by Iron based on the risk profile, not by your request.

{
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "customer_id": "c5f2e8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "status": "Processed",
  "with_edd": true,
  "url": null,
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "updated_at": "2025-01-06T16:54:40.162807+00:00"
}

Insufficient data: redirect the customer to complete the missing information:

{
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "customer_id": "c5f2e8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "status": "Pending",
  "with_edd": true,
  "url": "https://in.sumsub.com/idensic/l/#/...",
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "updated_at": "2025-01-06T16:54:40.162807+00:00"
}

Error Responses

Status	Cause
`400`	Invalid body, customer is not a person, invalid base64 `source_of_funds_proof`, or `source_of_funds_proof` exceeds 10 MB
`401`	Invalid API key or missing `CreateIdentification` permission
`403`	Authenticated, but not authorized for this customer or sub-partner scope
`404`	Customer not found
`409`	An identification is already in progress for this customer
`500`	Internal error while creating the identification. Retry with the same `Idempotency-Key`.

This endpoint uses two error body shapes. Client errors (400, 401, 403, 404, 409) return a plain JSON string. Server errors (500) return an object with message and trace_id. Quote the trace_id when reporting a 500 to MoonPay.

A client error (4xx) is a JSON string:

"Source of funds proof exceeds 10MB limit"

A server error (500) is an object:

{
  "message": "Create customer identification creation error. Please try again.",
  "trace_id": "0f9c7a1e-3b4d-4e6f-8a9b-1c2d3e4f5a6b"
}

Proof of Address

There is no separate API field for proof of address (POA). POA is expected to come from the SumSub applicant’s verified documents — it is read from the shared token, not uploaded directly to Iron. If you collect POA during your KYC flow, ensure the document is on the SumSub applicant before generating the share token. Iron reads it automatically. If POA is missing when Iron processes the token, two options:

Collect POA in SumSub, then re-submit: Add the document to the SumSub applicant (via your own flow or SumSub’s API), generate a new share token, and create a new identification. See Re-submitting After Missing Document Data.
Redirect to the hosted step-up flow: Use the url returned on the Pending identification. Iron’s hosted flow collects only the missing documents — the customer does not redo full KYC.

The Iron dashboard showing “Proof of Residence: Not Started” means Iron determined POA is required but was not present in the shared token. It does not mean the identification has failed.

Re-submitting After Missing Document Data

If a Pending response is caused by missing documents on the SumSub applicant (for example, a missing proof of address that was collected later), you cannot update an existing identification. Instead:

Ensure the SumSub applicant has the missing document or data. Use SumSub’s Change Provided Info endpoint to PATCH it if needed.
Generate a new share token for the applicant.
Create a new identification using POST /api/customers/<customer_id>/identifications/v2 with the new token.

Each identification is immutable once created. A new token submission creates a new identification for the same customer.

4. Identification Lifecycle

Status	Description
`Pending`	Waiting for the end-user to complete missing steps via the returned URL
`Processed`	Data submitted and verification is underway
`PendingReview`	Under manual review by the compliance team
`Approved`	Identification approved. Customer is verified.
`Declined`	Identification declined
`Expired`	Identification expired due to inactivity

In the best case, an applicant with sufficient data moves from Processed to Approved within seconds.

Subscribe to the identification_status webhook to track status changes in real time rather than polling.

​Introduction

​What Data Does MoonPay Expect?

​Preparing Your SumSub Applicant

​IP Address

​Required Applicant Data

​US citizens and residents: SSN and TIN

​Sample Applicant

​Integration

​1. Generate a SumSub Share Token

​2. Submit the Token to MoonPay

​Basic Request

​With KYC Questionnaire

​With KYC + EDD Questionnaire

​KYC Questionnaire Fields

​EDD Questionnaire Fields

​3. Handle the Response

​Proof of Address

​Re-submitting After Missing Document Data

​4. Identification Lifecycle

Introduction

What Data Does MoonPay Expect?

Preparing Your SumSub Applicant

IP Address

Required Applicant Data

US citizens and residents: SSN and TIN

Sample Applicant

Integration

1. Generate a SumSub Share Token

2. Submit the Token to MoonPay

Basic Request

With KYC Questionnaire

With KYC + EDD Questionnaire

KYC Questionnaire Fields

EDD Questionnaire Fields

3. Handle the Response

Proof of Address

Re-submitting After Missing Document Data

4. Identification Lifecycle