个人用户一键开通法币交易

我们提供灵活的集成方案，帮助您平台的用户快速完成 KYC 流程，快速开启法币与加密货币交易。

方案一：API 全流程同步（适用于资料齐全的用户）

如果您能够一次性收集用户所需的完整资料，可通过调用 Legend 的 API 直接完成 KYC 信息同步与提交。

API 调用流程：

1. 提交个人基本信息：调用 POST /kyc/individual/pi
   1. 若为 EU 个人账户，请同时传入 tin（税号）——该字段在本接口为选填，但在最终提交前必填。见 收集税号（TIN）。
2. 获取问卷题目：调用 GET /kyc/individual/qa
3. 提交问卷答案：调用 POST /kyc/individual/qa
4. 上传证明文件：调用 POST /kyc/individual/file
5. 提交 KYC 申请：调用 POST /kyc/individual/submit

方案二：API + SDK v2 集成（包含完整的 IDV + PoA 重试流程, 提升通过率）

这里优化了 IDV 与 PoA 的验证流程, 增加了基于 GPS 的 PoA 验证, 实时响应审核结果, 用户可以立刻重试.

API 调用流程：

1. 提交个人基本信息：调用 POST /kyc/individual/pi
   1. 必须传递参数 kyc_flow ，且kyc_flow=kyc_sdk_v2；
   2. 若为 EU 个人账户，也可以在此传入 tin；若不传，会在后续 SDK 流程中向用户索取，见下方说明。见 收集税号（TIN）。
2. 【可选】上传 ID 证明文件：调用 POST /kyc/individual/file
   1. 如果这步跳过，那么我们会在下面的SDK中让用户上传ID 证明文件；
   2. 如果在这里上传了ID文件，我们会进行校验。如果校验通过，下面的 SDK就不会再让用户上传ID。只有校验失败，才会在下面的SDK中让用户重新上传ID 证明文件；
   3. 建议：优先上传 ID 证明文件，提前进入 IDV 审核流程，提升用户体验；
   4. 注意：上传完所有 ID 文件后，就会进入 IDV 审核流程，不再接受后续新上传的 ID 文件。
   5. 这一步只能传证件类文件（id_file、id_back_file、selfie_file）。地址证明（proof_of_address）传不了，会返回错误码 303124——本方案的地址证明由 SDK 自己收集（先 GPS 定位验证，不通过再让用户在 SDK 内上传文件），详见下面第 5 步。
3. 获取问卷题目：调用 GET /kyc/individual/qa
4. 提交问卷答案：调用 POST /kyc/individual/qa
5. 续填SDK获取 KYC Connect SDK v2 URL：调用 POST /kyc/individual/sdk/url

   1. 在前端页面通过 iframe 打开获取的 URL；

      注意：建议在 iframe 配置 allow="camera; geolocation"。其中 camera 用于用户完成 IDV 证件拍摄和人脸验证，geolocation 用于 GPS PoA 地址验证。若未授权对应权限，浏览器会阻止 iframe 内的 SDK 调用摄像头或定位能力，用户可能无法完成 IDV 或 GPS PoA，并需要重新打开页面或改走文件 PoA 流程。

      HTML

      <iframe
        src="https://otc.legendtrading.com/v2/kyc/s/dyaWAV2H3KN9t4EiftMUixVeeUWzBY0s"
        allow="camera; geolocation"
      ></iframe>

      注意：allow 仅覆盖摄像头与定位，不覆盖文件选择。若 SDK 运行在 App 的 WebView 中，宿主还需补齐浏览器本应提供的能力：Android 上必须实现 WebChromeClient.onShowFileChooser，否则用户将无法上传地址证明（按钮点击无反应，且不显示任何报错）。若用 window.open() 打开 SDK，宿主还必须响应新窗口请求（Android：onCreateWindow；iOS：createWebViewWithConfiguration），否则新窗口会白屏。详见 在手机 App 的 WebView 中嵌入。

   2. 用户完成剩余 KYC 流程， 完成后会自动 submit KYC；您不需要主动调用/app/submit API。用户 submit KYC后，我们会发送/kyc-status webhook通知您。

   3. 注意 URL 有效期是24小时， 过期需要重新申请。

   4. 我们在这里详细介绍了 SDK 事件与前端接入。 推荐前端同事阅读。

方案三：Sumsub Token Sharing（复用用户已有的 Sumsub 身份验证）

如果您的用户已经在使用 Sumsub 的平台完成过身份验证（IDV），可以借助 Sumsub 的 Reusable KYC 能力，把已有的验证结果共享给 Legend。用户无需重复拍摄证件与人脸，可显著缩短开户时间。

前置配置（一次性，正式对接前完成）

另请注意：只有当您在 Sumsub 侧的核验等级满足 Legend recipient level 的要求时，共享的资料才可被复用。等级要求请在对接阶段与 Legend 合规团队确认。

API 调用流程

1. 生成 share token：在您的 Sumsub 后台为该用户生成一次性 share token，参考 Reusable KYC share。

2. 提交个人基本信息：调用 POST /kyc/individual/pi

   1. 必须先完成这一步创建用户，再提交 share token。

3. 提交 share token：调用 POST /kyc/individual/idv-share

   JSON

   {
     "uid": "your-user-id",
     "provider": "sumsub",
     "share_token": "_act-sbx-jwt-eyJhbGciOi..."
   }

   • provider 目前仅支持 sumsub；
   • share_token 最长 1024 字符。

   响应示例：

   JSON

   {
     "request_id": "26487087dd9ccf7e08ced77f447f400e",
     "status": "success",
     "code": "100000",
     "message": "success",
     "data": [
       {
         "status": "pending",
         "review_answer": ""
       }
     ],
     "metadata": {}
   }

   💡

   外层的 status（success）表示接口调用本身成功；data[].status 与 data[].review_answer 才是 Sumsub 侧的验证进度与结果，含义见下方状态表。

4. 获取问卷题目：调用 GET /kyc/individual/qa

5. 提交问卷答案：调用 POST /kyc/individual/qa

6. 【按需】补充剩余材料：例如地址证明（PoA）等。IDV 已复用成功时，无需再调用 POST /kyc/individual/file 上传 ID 证件文件。

7. 提交 KYC 申请：调用 POST /kyc/individual/submit

共享结果状态说明

请以 status 作为流程判断依据；review_answer 仅在 status 为 completed 时才有确定含义，未出结果时可能为 "" 或 null。

幂等与重试

• share token 是一次性的，且有有效期，消费后即失效。
• 同一用户重复调用 /kyc/individual/idv-share 是幂等的：若该用户已导入过 Sumsub 验证记录，接口会直接返回已有结果，不会二次消费 token。
• 同一用户的并发请求会被串行处理，最长等待约 60 秒。请避免对同一 uid 并发提交。
• 请求超时或返回 914015 时可以重试；若重试返回 914020，说明原 token 已失效，请重新生成 share token 后再试。

失败处理

完整错误码见 接口错误代码参考（v2）。

实时获取 KYC 审核状态

您可以通过以下方式实时追踪用户的 KYC 进度：

• 主动查询（轮询）：调用 POST /app/kyc-status API。
• 被动接收（推荐）：实现 kyc-status Webhook 回调接口。当用户的 KYC 状态变更时（例如：审核中→已通过），Legend 系统将自动推送通知至您配置的地址。

获取支持的国家/地区列表

在引导用户注册前，建议先调用 GET /countries API，获取 Legend 支持的服务区域及合规限制地区，以便进行前期地域筛选。

---

简洁要点：

• 全资料用户：API 同步
• 部分资料用户：API + SDK v2 混合（推荐，通过率更高）
• 已在 Sumsub 完成 IDV 的用户：Token Sharing 复用验证结果
• 状态获取：支持轮询与 Webhook
• 地域合规：先查列表再引导