Skip to main content

​
Introduction

If the Partner uses Sumsub for their own KYC processes, it is possible to enable token-based KYC data sharing with Iron by entering into a tri-party agreement between Iron, the Partner, and Sumsub. This allows Iron to access applicant data that has already been verified by the Partner via Sumsub. Once the tri-party agreement is in place, the Partner may:
  • Generate a Sumsub share token for each applicant
  • Send the token to Iron via API, along with a few additional parameters If the shared data meets Iron’s standards, onboarding can be completed in seconds.

​
Advisory Note

As a regulated entity with strict financial controls under Lithuanian law, Iron operates what may appear to be a rather “heavy” AML & Compliance framework, furthermore, we have to account for the AML & Compliance rules associated with each of our banking providers. Please be aware that our KYC/KYB requirements reflect this, and while we continuously review our requirements (and negotiate with our providers on theirs), we cannot reduce our requirements at this time without sacrificing some of the services we are able to partners and their end customers. KYC Parameters required: We require at minimum the information from low risk level from the KYC level parameters

​
Integration

​
Generating Share tokens with Sumsub

​
1. Generate a Sumsub Share Token

Use Sumsub’s share token API to issue a one-time share token: 
curl --request POST \
  --url https://api.sumsub.com/resources/accessTokens/shareToken \
  --header 'Content-Type: application/json' \
  --data '{
    "applicantId": "YOUR_APPLICANT_ID",
    "forClientId": "iron.xyz",
    "ttlInSecs": 600
  }'
Response: 
{
  "token": "eyJhbGciOiJub25lIn0…",
  "forClientId": "iron.xyz"
}
The token is a short-lived string you’ll pass it to Iron using our Identification endpoint with the RELIANCEPERSONPARAMS parameters

​
2. Reliance Person Params explained

  • share_token parameter is generic and required across all requests
  • ip_address parameter may be excluded if the Applicant being imported already contains location data gathered Sumsub’s IP address check feature
Tiers explained Iron operates a tiered KYC process whereby applicants are divided into Low-, Medium-, or High-Risk categories. This is determined primarily by looking at the sources:
  1. Nationality of the Customer (Proof of Identity or POI)
  2. Address of the Customer (Proof of Address or POA)
If an applicant is imported at the incorrect risk level, the identification will have apending state and we will return a url to pass to the customer to supply the missing or incorrect data imported from the token For detailed information on countries and their associated risk levels please reach out to us High Risk The high risk questionnaire is required. It consists of a few compliance questions, and a source of funds proof as a base64 encoded document. 
curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/customer_id/identifications \
     --header 'accept: application/json; charset=utf-8' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '
{
   "ip_address": "127.0.0.1",
  "token": "sumsub_token",
  "high_risk_questionnaire": {
    "employment_status": "Employed",
    "expected_monthly_volume": "LessThan1000",
    "monthly_income": "Between1000And2000",
    "source_of_funds": "SalaryAndWages",
    "source_of_funds_proof": "some-doc-as-base64"
  }
}
'
Medium Risk 
curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/customer_id/identifications \
     --header 'accept: application/json; charset=utf-8' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '
{
 "ip_address": "127.0.0.1",
  "token": "sumsub_token",
  "medium_risk_questionnaire": {
    "employment_status": "Employed",
    "expected_monthly_volume": "LessThan1000",
    "monthly_income": "Between1000And2000",
    "source_of_funds": "SalaryAndWages"
  }
}
'
Low Risk 
curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/customer_id/identifications \
     --header 'accept: application/json; charset=utf-8' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '
{
  "ip_address": "127.0.0.1",
  "token": "sumsub_token"
}
'

​
3. Response explained

Success with sufficient identification data Assuming all went well the Partner will receive a success response, the identification will be in status Processing. Indicating all went well and that the imported Applicant contains sufficient Identification data for our purposes. 
{
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "status": "Processing",
  "updated_at": "2025-01-06T16:54:40.162807+00:00",
  "url": "" 
}
Success without sufficient identification data If we import the applicant and find that the original KYC does not contain sufficient Identification data for our process, the identification will be in status Pending and we will return a url to pass to the end-customer in order to collect the missing information. 
{
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "status": "Pending",
  "updated_at": "2025-01-06T16:54:40.162807+00:00",
  "url": "some_url_to_pass_to_end_customer" 
}

​
4. Lifecycle and Webhooks

It is important to note that this process triggers not only a sumsub applicant import, with its own potential problems, but a fan-out of requests to our banking providers who require identification data for their own KYC processes, therefore the Identification status may change rather quickly after import, in the best case scenario simply to Approved. We strongly recommend the partner subscribes to our WebhookIdentificationStatusMessage webhooks

​
5. Is reliance and token sharing the same thing?

Strictly speaking, there is overlap, in legal terms reliance implies that every part of the identification process can legally be handled by the partner, and iron can simply “rely” on their processes, we do offer this possibility, but due to the complex nature of aligning AML & Compliance practices, and the realities of implementing this alignment correctly, by default, we will still run any imported applicants through our own AML/Compliance checks initially. Once we can confirm the quality of the applicant identity information passed to us by token is of the quality level expected, we will be happy to consider bypassing our internal checks, thereby fully embracing the reliance model.