概述

本套 API 面向 ISV（独立软件开发商） 客户：A 端为其终端客户（company）发起开户申请，由 OristaPay 平台完成企业查册、合规审核、IDV、签署、自动开通钱包等全流程。 ISV 客户完成 onboarding 后，拿到 companyCode 与 walletId，可直接复用 ISV 交易 API 代客户完成转账、收款、Payout 等交易。交易接口字段零变更——A 端调用时只需正常传 walletId，OristaPay 会按 ISV ↔ 商户的归属关系自动完成鉴权。

本套 API 的鉴权、签名、请求头、响应信封、文件上传、错误码体系与 RDPAY API 完全一致，未在本文档重复说明的部分请参考 ISV 交易 API。

业务流程

标识符约定

标识	生成方	用途
`extApplicationNo`	A 侧生成	外部申请单号，全局唯一；
`applicationNo`	OristaPay 侧生成	OristaPay 申请单号；查询、回调载荷的主键
`companyCode`	OristaPay 侧（审核通过后生成）	company 企业编码；用于查询完整资料、后续交易场景的企业身份
`peopleId`	OristaPay 侧（提交后生成）	keyPeople 全局 ID；用于获取 IDV / 签署链接
`walletId`	OristaPay 侧（钱包开通后）	钱包 ID；后续交易接口使用

OnboardingAPI

接口索引

#	Path	用途
1	`POST /storage/media/dg-putObject?mediaType=`	文件上传
2	`POST /api/v1/onboarding/application/submit`	提交开户申请
3	`POST /api/v1/onboarding/application/query`	查询申请进度
4	`POST /api/v1/onboarding/idv/link`	获取 IDV 链接（单一链接连续承载 IDV + 签署）
5	`POST /api/v1/onboarding/link/refresh`	刷新链接过期时间
6	`POST /api/v1/onboarding/profile`	查询审核通过的完整企业资料

1. 文件上传 (FileUpload)

接口概述 提交底层客户资料前,需使用该接口上传企业相关的文件。 请求参数

参数名	类型	是否必填	描述
mediaType	string	是	枚举: jpeg / jpg / png / pdf / gif
mediaFile	file	是	上传的文件,不超过20M

响应参数

参数名	类型	描述
code	int32	响应码,表示请求处理结果。如 1表示成功,其他值表示不同错误情况
message	string	响应消息,提供详细的处理信息或错误说明
data	string	校验成功时返回,返回数据为文件的key

响应示例

{
	"code":1,
	"message":"success",
	"data":"123876789124.png"
}

2. 提交开户申请 (SubmitApplication)

接口概述 为下游商户（B）提交 company 开户申请。首次提交，或上一笔申请审核拒绝（REJECTED）后重新提交，均走此接口。 请求参数

参数名	类型	是否必填	描述
extApplicationNo	string(128)	是	A 侧生成的外部申请单号，全局唯一
profile	Object	是	company 企业资料表单，结构详见【企业资料表单】

响应参数

参数名	类型	描述
code	int32	响应码：`1` 表示成功，其他值表示不同错误情况
message	string	响应消息
data	ApplicationData	申请受理成功时返回
errors	Array<Errors>	资料校验失败（`code = 6802`）时返回

ApplicationData 字段说明

字段名	类型	描述
applicationNo	string	OristaPay 申请单号；驳回后重提会生成新单号
applicationCreateTime	int64	申请创建时间，毫秒时间戳

Errors 字段说明

字段名	类型	描述
message	string	见附录【档案错误描述】

请求示例

{
  "extApplicationNo": "EXT20260512001",
  "profile": {
    "entityDetail": { "businessType": 1, "incorpPlace": "HKG" },
    "businessDetail": { "list": [{ "subIndustryCode": "I300734" }] },
    "shareholder": { "list": [{ "shareholderId": 1 }] },
    "keyPeople": { "quorum": 2, "directorNum": 2, "people": [] },
    "accountOpeningQuestionnaire": {
      "accountOpeningPurposes": ["PAYMENT_FOR_HK_BUSINESS"],
      "expectedMonthlyVolume": "FROM_2_5M_TO_5M_HKD",
      "handleClientMoney": false
    }
  }
}

响应示例（成功）

{
  "code": 1,
  "message": "Success",
  "data": {
    "applicationNo": "A202605258664",
    "applicationCreateTime": 1747094400000
  }
}

响应示例（资料校验失败）

{
  "code": 6802,
  "message": "Profile validation failed.",
  "errors": [
    { "message": "[Business details]Industry code cannot be empty!" },
    { "message": "[Entity details]Please upload a valid proof of Business Registration" }
  ]
}

关键约束

幂等键 (extApplicationNo)：同 extApplicationNo 重复提交，body 一致 → 返回原 applicationNo；body 不一致 → 6801
同一商户防并发：同一 B 的 (CI 号 / BR 号) 在 A 名下只允许一份活跃申请。当前申请进入终态（APPROVED / REJECTED）后才可再提交
驳回后重提：必须使用新的 extApplicationNo，提交后生成新的 applicationNo
查册失败 = 自动驳回：API 路径下，无论是 企业查册定级失败（CI/BR 找不到等）还是 查册比对不通过（数据不一致），都会直接将申请置为 REJECTED 并推送 REJECTED webhook，A 需换 extApplicationNo 重新提交

3. 查询申请进度 (QueryApplication)

接口概述 按 applicationNo 或 extApplicationNo 查询申请进度（二选一）。 请求参数

参数名	类型	是否必填	描述
applicationNo	string	条件	OristaPay 申请单号
extApplicationNo	string	条件	A 侧申请单号

响应参数

参数名	类型	描述
code	int32	响应码
message	string	响应消息
data	QueryApplicationData	`code = 1` 时返回

QueryApplicationData 字段说明

字段名	类型	描述
applicationNo	string	OristaPay 申请单号
extApplicationNo	string	A 侧申请单号
applicationCreateTime	int64	申请创建时间，毫秒时间戳
applicationStatus	string	审核状态：`UNDER_REVIEW` / `PENDING_USER` / `APPROVED` / `REJECTED`
companyCode	string	企业编码（审核通过后返回）
walletId	int64	钱包 ID（钱包开通后返回）
profile	Object	企业资料表单，见【企业资料表单】

applicationStatus 取值：

UNDER_REVIEW：受理中或审核中（覆盖查册中、人工审核中等所有非终态非待用户阶段）
PENDING_USER：后台查册通过，等待 keyPeople 完成 IDV / 签署；此时（且仅此时）才可调 GetIdvLink，之前调用返回 6406
APPROVED：审核通过、钱包已开通；取 companyCode / walletId 做后续业务
REJECTED：申请被驳回；API 场景下无法恢复，需换新的 extApplicationNo 重新提交

query 与 webhook 的 applicationStatus 语义一致。如果 A 端因网络异常错过 PENDING_USER webhook，可主动调 query 看到同样的状态。

profile.keyPeople.people[] 中各 KeyPeopleInfo 含 peopleId（用于获取 IDV / 签署链接）、idvStatus / mandateStatus 两个状态字段（实时反映该人员的 IDV / 签署进度）。

请求示例

{
  "applicationNo": "A202605258664"
}

响应示例

{
  "code": 1,
  "message": "Success",
  "data": {
    "applicationNo": "A202605258664",
    "extApplicationNo": "EXT20260512001",
    "applicationCreateTime": 1747094400000,
    "applicationStatus": "PENDING_USER",
    "companyCode": "",
    "walletId": 0,
    "profile": {
      "entityDetail": { "...": "..." },
      "keyPeople": {
        "people": [
          {
            "peopleId": 1000123456,
            "lastNameEn": "Lo",
            "firstNameEn": "Sang",
            "idvStatus": "UNDER_REVIEW",
            "mandateStatus": "NOT_STARTED",
            "isDirector": true,
            "isUbo": false
          }
        ]
      }
    }
  }
}

4. 获取 IDV 链接 (GetIdvLink)

接口概述 为指定 peopleId 生成一次性 H5 链接。单一链接连续承载 IDV → 签署两步：B 用户打开链接后先完成 IDV，IDV 通过后页面自动进入签署流程；isMandateUser = false 的人员只走 IDV，IDV 完成即结束。链接由 A 自行送达给 B 用户（邮件 / 短信 / 二维码扫码 / 跳转，A 决定）。

前置条件：必须先收到 ONBOARDING_APPLICATION_STATUS_NOTIFICATION 中 applicationStatus = PENDING_USER 的 webhook 后才能调用本接口。在此之前后端处于企业查册阶段，调用将返回 6406，提示等待 PENDING_USER webhook。

请求参数

参数名	类型	是否必填	描述
applicationNo	string	是	OristaPay 申请单号
peopleId	int64	是	从 `QueryApplication` 返回的 `profile.keyPeople.people[].peopleId` 取得

响应参数

参数名	类型	描述
code	int32	响应码
message	string	响应消息
data	LinkData	`code = 1` 时返回

LinkData 字段说明

字段名	类型	描述
linkUrl	string	一次性 H5 链接；用户访问后连续完成 IDV 与签署
expireTime	int64	链接过期时间，毫秒时间戳；默认 24 小时

请求示例

{
  "applicationNo": "A202605258664",
  "peopleId": 1000123456
}

响应示例

{
  "code": 1,
  "message": "Success",
  "data": {
    "linkUrl": "https://customer.oristapay.com/h5/index?code=4e0af338-9605-4353-86db-f35c4fdb7959",
    "expireTime": 1747180800000
  }
}

关键约束

链接为一次性：B 完成完整流程（IDV + 签署）后链接失效；过期未使用同样失效
同一 peopleId 重复调用：已有未过期链接 → 直接返回原链接；已过期 → 自动作废原链接并生成新链接
该人员已完成全部任务（IDV 通过且 isMandateUser=true 时签署也完成）时再调用返回 6001

5. 刷新链接过期时间 (RefreshIdvLink)

接口概述 链接过期（expireTime < now）或临近过期时，A 调用此接口生成新链接；原链接立即失效。 请求参数

参数名	类型	是否必填	描述
applicationNo	string	是	OristaPay 申请单号
peopleId	int64	是	keyPeople 全局 ID

响应参数 LinkData：字段同 §4。 请求示例

{
  "applicationNo": "A202605258664",
  "peopleId": 1000123456
}

响应示例 同 §4。 关键约束

前置条件同 §4：必须先收到 PENDING_USER webhook，否则返回 6406
调用后原链接立即作废
若该人员已完成全部任务（IDV 通过且签署完成），调用返回 6001
若申请已进入终态（APPROVED / REJECTED），调用返回 6001

6. 查询审核通过的完整企业资料 (QueryCompanyProfile)

接口概述 按 companyCode 查询审核通过后的企业完整资料。 请求参数

参数名	类型	是否必填	描述
companyCode	string	是	企业编码（审核通过后从 `QueryApplication` 或 Webhook 拿到）

响应参数

参数名	类型	描述
code	int32	响应码
message	string	响应消息
data	ProfileFormDto	完整企业资料，结构见【企业资料表单】

请求示例

{
  "companyCode": "HKM12389h"
}

响应示例

{
  "code": 1,
  "message": "Success",
  "data": {
    "entityDetail": { "...": "..." },
    "businessDetail": { "...": "..." },
    "shareholder": { "...": "..." },
    "keyPeople": { "...": "..." }
  }
}

关键约束

仅可查询审核通过（applicationStatus = APPROVED）的企业；尚未通过的企业返回 6001 + 提示 “Profile is not approved yet.”
companyCode 必须属于当前 A，否则返回 6005
资料以 OristaPay 侧最新审核结果为准，可能与提交时的 profile 不完全一致（审核员可补录或修正部分字段）

Callback

回调请求体、签名验证、响应要求与 ISV 交易 API · Callback 完全一致，本文档仅定义新增的 OpenBizType 与载荷字段。

1. 新增的 OpenBizType 枚举

枚举值	触发时机
ONBOARDING_APPLICATION_STATUS_NOTIFICATION	申请状态变更（PENDING_USER / APPROVED / REJECTED）
ONBOARDING_KEY_PEOPLE_IDV_FAILED	某个 keyPeople IDV 失败（vendor 失败或人工 case 失败）

2. 回调数据类型

2.1 申请状态变更 (OnboardingApplicationStatusNotification)

触发时机（仅关键审核节点，节点变更不会逐个推送）

applicationStatus	触发时机	A 端动作
`PENDING_USER`	后台企业查册通过 → 可以开始 keyPeople 的 IDV/签署	此时（且仅此时）才可调用 `GetIdvLink`（在此之前调用会返回 `6406`）
`APPROVED`	申请最终审核通过、钱包已开通	取出 `companyCode` / `walletId` 做后续业务
`REJECTED`	申请被终态驳回（含查册失败、合规失败等）	API 场景下被拒申请无法恢复，A 需重新提交申请（`extApplicationNo` 不能复用原值，否则命中幂等返回旧记录）

申请刚提交（UNDER_REVIEW 状态首次进入）不会单独推送 webhook，A 通过 SubmitApplication 同步响应即知申请受理
节点级变更（NameScreening → RiskScreening 等）不再推送，仅 QueryApplication 接口可查
同一 applicationStatus 的重复推送应该幂等（按 X-Nonce 去重）

字段说明

字段名	类型	描述
applicationNo	string	OristaPay 申请单号
extApplicationNo	string	A 侧申请单号
applicationStatus	string	`PENDING_USER` / `APPROVED` / `REJECTED`
companyCode	string	企业编码（`APPROVED` 时填入；其他状态为空字符串）
walletId	int64	钱包 ID（钱包开通后填入；其他状态为 `0`）
eventTime	int64	事件触发时间，毫秒时间戳

示例（查册通过，可发起 IDV）

{
  "applicationNo": "A202605258664",
  "extApplicationNo": "EXT20260512001",
  "applicationStatus": "PENDING_USER",
  "companyCode": "",
  "walletId": 0,
  "eventTime": 1747094400000
}

示例（审核通过）

{
  "applicationNo": "A202605258664",
  "extApplicationNo": "EXT20260512001",
  "applicationStatus": "APPROVED",
  "companyCode": "HKM12389h",
  "walletId": 12345678901234,
  "eventTime": 1747104400000
}

示例（驳回 / 查册失败）

{
  "applicationNo": "A202605258664",
  "extApplicationNo": "EXT20260512001",
  "applicationStatus": "REJECTED",
  "companyCode": "",
  "walletId": 0,
  "eventTime": 1747094500000
}

2.2 keyPeople IDV 失败 (OnboardingKeyPeopleIdvFailedNotification)

某个 keyPeople 的 IDV 失败时推送，A 端收到后可让 B 重做 IDV：调 RefreshIdvLink 拿新链接给 B。 触发时机

IDV失败

字段说明

字段名	类型	描述
applicationNo	string	OristaPay 申请单号
extApplicationNo	string	A 侧申请单号
peopleId	string	keyPeople 全局 ID（字符串形式，保留 int64 精度）
eventTime	int64	事件触发时间，毫秒时间戳

示例

{
  "applicationNo": "A202605258664",
  "extApplicationNo": "EXT20260512001",
  "peopleId": "1000123456",
  "eventTime": 1747100100000
}

企业资料表单

profile 是提交开户申请（SubmitApplication）的核心载荷，也是查询接口返回的核心数据。结构因业务类型（合伙 / 有限 / 独资）和注册地不同而异。

1. 顶层结构

profile = {
  entityDetail,                  // 企业基本信息（必有）
  businessDetail,                // 业务信息（必有）
  shareholder,                   // 股东信息（仅"有限公司"必有）
  keyPeople,                     // 关键人物（必有，含 IDV / 签署对象）
  accountOpeningQuestionnaire    // 开户问题答卷（必有）
}

2. 支持矩阵

注册地 \ 商业类型	有限公司	合伙公司	独资公司
香港 (`HKG`)	✓	✓	✓
其他（非 HKG，且非 CHN）	✓	✗	✗

3. 通用子结构

3.1 businessDetail.list[] 元素

字段	类型	是否必填	描述
subIndustryCode	string(10)	是	子行业 itemId，必须存在于 OristaPay foundation 行业字典，见附录【行业编码】
yearsInBusiness	string	是	code 的字符串形式，见附录【经营年限】
businessLocations	Array<string>(3)	是	商业地点列表，最多 3 个，见附录【国家地区编码】
lastYearSales	string	是	code 的字符串形式，见附录【上年销售额】
industryDetails	string(256)	是	行业补充说明

A 端只需要传 subIndustryCode，主行业 industryCode 由服务端按字典反查自动回填，即使 A 端填了也会被服务端覆盖。

3.2 KeyPeopleInfo 通用字段

所有业务类型的 keyPeople.people[] 都使用 KeyPeopleInfo。通用提交字段：

字段	类型	是否必填	描述
lastNameEn	string(128)	条件	中英文名必填其一
firstNameEn	string(128)	条件	中英文名必填其一
nameZh	string(128)	条件	中英文名必填其一
areaCode	string(8)	否	电话区号
mobileNumber	string(32)	否	手机号码
email	string(128)	否	邮箱地址
gender	int32	是	`1` 男 / `2` 女
birthdate	string	是	出生日期 `YYYY-MM-DD`
region	string	是	证件所在国家 / 地区，见附录【国家地区编码】
idType	int32	是	`1` 中国大陆身份证 / `2` 中国香港身份证 / `3` 护照
idNumber	string	是	证件号码
isMandateUser	boolean	是	是否为签署用户。keyPeople 中 `isMandateUser=true` 的人数必须 ≥ `keyPeople.quorum`（最小法定人数）。一般为部分或全部董事
ownedSharesPercent	double(6,3)	条件	该人持股比例（百分比，0~100，3 位小数）。仅当 `isUbo=true` 时必填
isWalletAdmin	boolean	是	是否为钱包管理员。整组 keyPeople 中必须有且仅有 1 人为 `true`；该人会被自动设为企业的 wallet 超级管理员
overseaWorkCertificateFileKey	Array<string>	条件	海外工作证明文件 fileKey 列表。仅当该人 `isWalletAdmin=true` 且 `region=CHN`（中国大陆居民）时必填；最多 5 份

钱包管理员两种典型组合：

兼任：某个董事 / UBO 同时勾 isWalletAdmin=true（一人两职）
独立：在 keyPeople 列表里追加一个仅作钱包管理员的人（isDirector / isUbo / isPartner / isOwner 全部 false，只 isWalletAdmin=true），该人需走 IDV

idType 的”中国大陆身份证”是个人证件枚举，与”企业注册地”是不同维度；当企业注册地为 HKG 但董事 / 股东是中国大陆居民时，正常使用此 idType。

3.3 KeyPeopleInfo 中由 OristaPay 侧回写的运行时字段

提交时 A 不要填写这些字段；通过 QueryApplication 读取时它们承载 OristaPay 侧的回写结果。

字段	类型	描述
peopleId	int64	OristaPay 生成的人员全局 ID；获取 IDV / 签署链接时必须传此 ID
idvStatus	string	IDV 进度：`NOT_STARTED` 未开始 / `UNDER_REVIEW` vendor 通过 + 人工审核中 / `COMPLETED` 人工通过 / `FAILED` 失败
mandateStatus	string	签署状态（仅 `isMandateUser = true` 时有意义）：`NOT_STARTED` 未签 / `SIGNED` 已签；非签署人为空字符串

3.4 开户问卷 (accountOpeningQuestionnaire)

所有商业类型的 profile 都必须填写此模块。

字段	类型	是否必填	描述
accountOpeningPurposes	Array<enum>	是	开户目的，多选 1~2 个；可选值：`PAYMENT_FOR_HK_BUSINESS` / `STORE_DIGITAL_ASSETS_FOR_HK_BUSINESS`
expectedCounterparties	string(256)	否	预期业务交易对手（自由文本）
expectedMonthlyVolume	enum	是	预期月交易额（HKD），单选；可选值：`BELOW_1M_HKD` / `FROM_1M_TO_2_5M_HKD` / `FROM_2_5M_TO_5M_HKD` / `FROM_5M_TO_10M_HKD` / `ABOVE_10M_HKD`
handleClientMoney	string	是	是否代客户处理资金（YES/NO）

示例

"accountOpeningQuestionnaire": {
  "accountOpeningPurposes": ["PAYMENT_FOR_HK_BUSINESS", "STORE_DIGITAL_ASSETS_FOR_HK_BUSINESS"],
  "expectedCounterparties": "Major HK retail merchants",
  "expectedMonthlyVolume": "FROM_2_5M_TO_5M_HKD",
  "handleClientMoney": "NO"
}

4. 合伙公司（仅香港）

entityDetail

字段	类型	是否必填	描述
businessType	int32	是	`2` 合伙公司
incorpPlace	string	是	公司注册地，仅支持 `HKG`
brNumber	string(32)	是	商业登记证书编号
brFileKey	string(128)	是	Business Registration 文件 fileKey
incorpDate	string	是	公司注册日期 `YYYY-MM-DD`
website	string(512)	否	网站 URL
regPlace	string	是	公司注册所在地，见附录【国家地区编码】
regAddress	string(256)	是	公司注册详细地址，仅英文 / 数字 / 空格
operatingPlace	string	是	公司运营地
operatingAddress	string(256)	是	公司运营详细地址
nameEn	string(128)	是	企业英文名
nameZh	string(128)	否	企业中文名
paFileKey	Array<string>	是	Partnership Agreement 文件，最多 5 份

keyPeople：合伙人列表 2-6 人，KeyPeopleInfo 除通用字段外新增：

字段	类型	是否必填	描述
isPartner	bool	是	是否为合伙人，固定 `true`

提交示例

{
  "entityDetail": {
    "businessType": 2,
    "incorpPlace": "HKG",
    "brNumber": "br-number-partner",
    "incorpDate": "2025-05-01",
    "website": "www.example.com",
    "regPlace": "HKG",
    "regAddress": "Example partner register address",
    "operatingPlace": "HKG",
    "operatingAddress": "Example partner operating address",
    "nameEn": "Example Partnership",
    "nameZh": "示例合伙公司",
    "brFileKey": "4e0af338-9605-4353-86db-f35c4fdb7959.jpg",
    "paFileKey": ["06993a52-3069-41c9-a048-1601a3dfade4.jpg"]
  },
  "businessDetail": {
    "list": [
      {
        "subIndustryCode": "I300734",
        "yearsInBusiness": "1",
        "businessLocations": ["HKG"],
        "lastYearSales": "1",
        "industryDetails": "Digital asset platform"
      }
    ]
  },
  "keyPeople": {
    "quorum": 2,
    "directorNum": 0,
    "people": [
      {
        "lastNameEn": "Lo",
        "firstNameEn": "Sang",
        "nameZh": "罗生",
        "areaCode": "852",
        "mobileNumber": "61234567",
        "email": "lo@example.com",
        "isPartner": true,
        "isMandateUser": true,
        "isWalletAdmin": true
      },
      {
        "lastNameEn": "Yeung",
        "firstNameEn": "Sang",
        "nameZh": "杨生",
        "areaCode": "852",
        "mobileNumber": "61234568",
        "email": "yeung@example.com",
        "isPartner": true,
        "isMandateUser": true,
        "isWalletAdmin": false
      }
    ]
  },
  "accountOpeningQuestionnaire": {
    "accountOpeningPurposes": ["PAYMENT_FOR_HK_BUSINESS"],
    "expectedMonthlyVolume": "FROM_2_5M_TO_5M_HKD",
    "handleClientMoney": false
  }
}

5. 有限公司（香港）

entityDetail

字段	类型	是否必填	描述
businessType	int32	是	`1` 有限公司
incorpPlace	string	是	公司所在地，`HKG`
ciNumber	string(32)	是	企业注册证书编号
ciFileKey	string(128)	是	Certificate of Incorporation 文件
brNumber	string(32)	是	商业登记证书编号
brFileKey	string(128)	是	Business Registration 文件
incorpDate	string	是	公司注册日期 `YYYY-MM-DD`
website	string(512)	否	网站 URL
regPlace	string	是	公司注册所在地
regAddress	string(256)	是	公司注册详细地址
operatingPlace	string	是	公司运营地
operatingAddress	string(256)	是	公司运营详细地址
nameEn	string(128)	是	企业英文名
nameZh	string(128)	否	企业中文名
isFinancialInstitute	int32	是	`1` 受监管 / `2` 不受监管
financialRegulatorPlace	string	条件	受监管必填
financialRegulator	string(256)	条件	受监管必填
financialLicenseType	string(128)	条件	受监管必填
regulatedProofKey	Array<string>	条件	受监管证明文件，最多 5 份
isListed	int32	是	`1` 上市 / `2` 非上市
listingPlace	string(3)	条件	上市公司必填
listingExchange	string(256)	条件	上市公司必填
stockCode	string(128)	条件	上市公司必填
isGovOwned	int32	是	`1` 国有 / `2` 非国有
ownedGovPlace	string(3)	条件	国有必填
maFileKey	Array<string>	是	Memorandum and Articles of Association 文件，最多 5 份

shareholder（list 与 shareholderFileKey 二选一）

字段	类型	是否必填	描述
list	Array<ShareholderDto>	二选一	结构化股东列表
shareholderFileKey	Array<string>	二选一	股权架构图文件 fileKey 列表；传图时不需要再传 `list`

仅”有限公司”且 isFinancialInstitute=2 / isListed=2 / isGovOwned=2（即都不豁免）时必须提供股权结构。

ShareholderDto

字段	类型	是否必填	描述
shareholderId	int64	是	股东唯一标识，请求侧自生成
sameId	int64	否	标识”同一股东在结构中重复出现”；默认 `0`
parentId	int64	否	父级 `shareholderId`；第一层填 `0`
shareholderType	int32	是	`1` 个人股东 / `2` 企业股东
businessType	int32	条件	企业股东商业类型，`shareholderType=2` 时必填
incorpPlace	string	条件	企业股东注册地。合伙 / 独资股东仅支持 `HKG`；不接受 `CHN`
ownedSharesPercent	double(6,3)	是	对父级持股比例
companyNameEn	string(128)	条件	企业股东英文名（中英名必填其一）
companyNameZh	string(128)	条件	企业股东本地名（中英名必填其一）
firstNameEn	string(128)	条件	个人股东英文名（中英名必填其一）
lastNameEn	string(128)	条件	个人股东英文姓（中英名必填其一）
nameZh	string(128)	条件	个人股东本地名（中英名必填其一）

keyPeople

字段	类型	是否必填	描述
quorum	int32	是	最小法定人数 1-99
directorNum	int32	是	董事人数（须等于 `isDirector=true` 的人数）1-99
people	Array<KeyPeopleInfo>	是	列出企业所有 UBO 与董事

KeyPeopleInfo 除通用字段外新增：

字段	类型	是否必填	描述
isDirector	boolean	是	是否为董事
isUbo	boolean	是	是否为最终受益人（UBO）

6. 有限公司（非香港）

字段绝大部分与 §5 相同，差异如下（未列字段同 §5）：

字段	类型	是否必填	描述
incorpPlace	string	是	非 `HKG` 的国家 / 地区编码；不接受 `CHN`
brNumber	string(32)	否	商业登记证书编号（非 HK 地区可不填）
brFileKey	string(128)	否	Business Registration 文件（非 HK 地区可不填）
coiFileKey	Array<string>	条件	Certificate of Incumbency。当 `incorpPlace` 为 `BMU` / `WSM` / `SYC` / `CYM` / `VGB` 时必填，最多 5 份

7. 独资公司（仅香港）

entityDetail

字段	类型	是否必填	描述
businessType	int32	是	`3` 独资公司
incorpPlace	string	是	仅支持 `HKG`
brNumber	string(32)	是	商业登记证书编号
brFileKey	string(128)	是	Business Registration 文件
incorpDate	string	是	公司注册日期 `YYYY-MM-DD`
website	string(512)	否	网站 URL
regPlace	string	是	注册所在地
regAddress	string(256)	是	注册详细地址
operatingPlace	string	是	运营地
operatingAddress	string(256)	是	运营详细地址
nameEn	string(128)	是	企业英文名
nameZh	string(128)	否	企业中文名
isFinancialInstitute	int32	否	`1` 受监管 / `2` 不受监管

keyPeople：仅一位 owner，KeyPeopleInfo 除通用字段外新增：

字段	类型	是否必填	描述
isOwner	boolean	是	是否为独资公司拥有人（有且仅一位）

8. 文件 fileKey 字段汇总

文件先通过文件上传接口拿到 fileKey，再填入 profile。

profile 字段	文件含义	类型
entityDetail.brFileKey	商业登记证书	string
entityDetail.ciFileKey	公司注册证书	string
entityDetail.maFileKey[]	组织章程（M&A）	Array<string> ≤ 5
entityDetail.paFileKey[]	合伙协议	Array<string> ≤ 5
entityDetail.kycFileKey[]	KYC 证明	Array<string> ≤ 5
entityDetail.regulatedProofKey[]	受监管金融机构证明	Array<string> ≤ 5
entityDetail.coiFileKey[]	Certificate of Incumbency	Array<string> ≤ 5
keyPeople.people[].idFileKey[]	个人证件照	Array<string> ≤ 5
keyPeople.people[].overseaWorkCertificateFileKey[]	海外工作证明（CHN 钱包管理员必填）	Array<string> ≤ 5

文件类型与上限：jpeg / jpg / png / pdf / gif，单文件 ≤ 20 MB。

错误码

1. 业务错误码

code	含义	ISV onboarding 路径下的典型触发
`1`	成功	—
`6001`	通用业务失败	未明确分类的业务错误
`6002`	参数错误	必填字段缺失、字段类型不符
`6003`	订单不存在	`applicationNo` / `extApplicationNo` 不存在；`peopleId` 不存在
`6005`	没有权限	A 未开通 ISV onboarding 能力；A 试图查询非己 `applicationNo`
`6406`	请求正在处理中	后台企业查册尚未通过，需先等待 `PENDING_USER` webhook 后再调 `GetIdvLink` / `RefreshIdvLink`
`6801`	重复申请	同 `extApplicationNo` 不同 body；同一 B（CI / BR 号）已有活跃申请
`6802`	资料错误	`profile` 校验失败，伴随 `errors[]` 列表（详见附录【档案错误描述】）
`6803`	申请达到上限	A 当前周期已开户数超配额（若有约束）

2. 各接口错误码对照

2.1 SubmitApplication

场景	返回
提交成功	`code = 1` + `data.applicationNo`
必填字段缺失 / 类型错误	`code = 6002`
A 未开通 ISV onboarding	`code = 6005`
同 `extApplicationNo`，body 一致	`code = 1` + 返回原 `applicationNo`（幂等）
同 `extApplicationNo`，body 不一致	`code = 6801`
同一 B（CI / BR 号）已有活跃申请	`code = 6801`
`profile` 校验失败	`code = 6802` + `errors[]`

2.2 QueryApplication

场景	返回
查询成功	`code = 1` + `data`
`applicationNo` / `extApplicationNo` 都未传	`code = 6002`
申请不存在	`code = 6003`
申请不属于当前 A	`code = 6005`

2.3 GetIdvLink

场景	返回
成功	`code = 1` + `data.linkUrl` + `expireTime`
`applicationNo` 不存在 / 不属于当前 A	`code = 6003` / `6005`
`peopleId` 不存在 / 不属于此申请	`code = 6003`
该人员全部任务已完成	`code = 6001`
申请已进入终态（`APPROVED` / `REJECTED`）	`code = 6001`
查册尚未通过（在 `PENDING_USER` webhook 之前调用）	`code = 6406` + `message`: “Company search not passed yet. Wait for PENDING_USER webhook before requesting IDV link.”

2.4 RefreshIdvLink

场景	返回
成功	`code = 1`
`applicationNo` / `peopleId` 不存在 / 不属于当前 A	`code = 6003` / `6005`
该人员全部任务已完成	`code = 6001`
申请已进入终态	`code = 6001`
查册尚未通过（在 `PENDING_USER` webhook 之前调用）	`code = 6406`

2.5 QueryCompanyProfile

场景	返回
成功	`code = 1` + `data`
`companyCode` 不存在	`code = 6003`
`companyCode` 对应企业不属于当前 A	`code = 6005`
企业尚未审核通过	`code = 6001` + 提示 “Profile is not approved yet.”

3. 档案错误描述（`code = 6802`）

完整清单同 ISV 交易 API · 档案错误描述，按所属模块分组：

[Business details]
[Entity details]
[Key people]
[Shareholder]
[Others]

本套 API 额外的拒绝场景：

[Entity details]Place of incorporation not supported: CHN —— 企业层 incorpPlace / regPlace / operatingPlace 不允许 CHN
[Entity details]Place of incorporation not supported: <制裁国家代码> —— 被制裁国家
[Entity details]Partnership / Sole proprietorship only support incorpPlace=HKG —— 合伙 / 独资仅限香港
[Key people]Nationality not supported: <国家代码> —— keyPeople 国籍为被制裁国家（CHN 特例放行）
[Wallet Admin]Work certification is necessary —— region=CHN 的钱包管理员未传 overseaWorkCertificateFileKey

​概述

​业务流程

​标识符约定

​OnboardingAPI

​接口索引

​1. 文件上传 (FileUpload)

​2. 提交开户申请 (SubmitApplication)

​3. 查询申请进度 (QueryApplication)

​4. 获取 IDV 链接 (GetIdvLink)

​5. 刷新链接过期时间 (RefreshIdvLink)

​6. 查询审核通过的完整企业资料 (QueryCompanyProfile)

​Callback

​1. 新增的 OpenBizType 枚举

​2. 回调数据类型

​2.1 申请状态变更 (OnboardingApplicationStatusNotification)

​2.2 keyPeople IDV 失败 (OnboardingKeyPeopleIdvFailedNotification)

​企业资料表单

​1. 顶层结构

​2. 支持矩阵

​3. 通用子结构

​3.1 businessDetail.list[] 元素

​3.2 KeyPeopleInfo 通用字段

​3.3 KeyPeopleInfo 中由 OristaPay 侧回写的运行时字段

​3.4 开户问卷 (accountOpeningQuestionnaire)

​4. 合伙公司（仅香港）

​5. 有限公司（香港）

​6. 有限公司（非香港）

​7. 独资公司（仅香港）

​8. 文件 fileKey 字段汇总

​错误码

​1. 业务错误码

​2. 各接口错误码对照

​2.1 SubmitApplication

​2.2 QueryApplication

​2.3 GetIdvLink

​2.4 RefreshIdvLink

​2.5 QueryCompanyProfile

​3. 档案错误描述（code = 6802）

概述

业务流程

标识符约定

OnboardingAPI

接口索引

1. 文件上传 (FileUpload)

2. 提交开户申请 (SubmitApplication)

3. 查询申请进度 (QueryApplication)

4. 获取 IDV 链接 (GetIdvLink)

5. 刷新链接过期时间 (RefreshIdvLink)

6. 查询审核通过的完整企业资料 (QueryCompanyProfile)

Callback

1. 新增的 OpenBizType 枚举

2. 回调数据类型

2.1 申请状态变更 (OnboardingApplicationStatusNotification)

2.2 keyPeople IDV 失败 (OnboardingKeyPeopleIdvFailedNotification)

企业资料表单

1. 顶层结构

2. 支持矩阵

3. 通用子结构

3.1 businessDetail.list[] 元素

3.2 KeyPeopleInfo 通用字段

3.3 KeyPeopleInfo 中由 OristaPay 侧回写的运行时字段

3.4 开户问卷 (accountOpeningQuestionnaire)

4. 合伙公司（仅香港）

5. 有限公司（香港）

6. 有限公司（非香港）

7. 独资公司（仅香港）

8. 文件 fileKey 字段汇总

错误码

1. 业务错误码

2. 各接口错误码对照

2.1 SubmitApplication

2.2 QueryApplication

2.3 GetIdvLink

2.4 RefreshIdvLink

2.5 QueryCompanyProfile

3. 档案错误描述（`code = 6802`）