申请虚拟卡

📄 正文

发卡永远从虚拟卡开始：POST /open-api-corp/card/v1/apply 受理即返回 cardApplyId，风控与建卡全程异步，终态经 Webhook CARD_CREATED / CARD_REJECTED 通知，GET /open-api-corp/card/v1/query-apply 作查询兜底。建卡成功后用 cardId 走单卡查询与列表查询。整条链路在卡组各页的位置见管理卡片（概述）。

POST /open-api-corp/card/v1/apply

请求参数

字段	类型	必填	说明
`cardApplyRef`	String	是	≤64；合作伙伴侧申请唯一标识
`subjectType`	String	是	`ORGANIZATION`（公司卡）/ `CUSTOMER`（员工卡）
`subjectId`	String	是	≤20；持卡主体外部 id：`ORGANIZATION`→`organizationId`，`CUSTOMER`→`customerId`。须存在、类型一致、ACTIVE、属本合作伙伴
`cardProfileId`	String	是	卡类型码 = 四类型之一（与 `subjectType` 的搭配见下表）
`custodianCustomerId`	String	条件必填	≤20；公司卡（`subjectType`≠`CUSTOMER`）必填：值 = 本公司某员工的 `customerId`，须 ACTIVE
`ruleIds`	`Array<String>`	条件必填	≤5 条；开卡时同步绑定的交易限额限次规则，元素为规则外部 id。资金来源为公司资金池的两种卡型（`COMPANY_UTILITY_CARD` / `EMPLOYEE_CARD_CORPORATE_FUNDED`，即公司公用卡 / 员工卡（公司池））必填；其余卡型可选

cardProfileId 四卡型与 subjectType 的搭配

卡型由两个正交维度组合而成：持卡主体（卡发给谁）× 余额模式（钱从哪个账户扣）。完整卡型介绍见概述 · 卡片类型。

业务卡型	卡类型码（`cardProfileId`）	`subjectType`	余额模式	托管人（`custodianCustomerId`）
公司公用卡	`COMPANY_UTILITY_CARD`	`ORGANIZATION`	company pool 公司池	必填
专款专用卡	`COMPANY_DEDICATED_PURPOSE_CARD`	`ORGANIZATION`	card’s own balance 独立余额	必填
员工卡（公司池）	`EMPLOYEE_CARD_CORPORATE_FUNDED`	`CUSTOMER`	SHARED 公司池	不适用
员工卡（独立余额）	`EMPLOYEE_CARD_SELF_FUNDED`	`CUSTOMER`	DEDICATED 独立余额	不适用

按监管要求，公司卡须指定一名本公司在职员工作为托管人（Custodian）。卡片有问题时将联系托管人，消费遇 3DS 挑战需由托管人完成验证。

ruleIds 绑定规则

ruleIds 中的每条规则须同时满足：已存在、属同一公司、状态 ACTIVE；配置金额限额的规则须与卡核销币种有交集。数组内不得重复——重复携带同一条规则即拒（不会静默去重），请自行去重后再提交。

任一条不满足即整单拒绝（受理前早拒、不产生 cardApplyId），不做部分成功；开卡后仍可经限额限次接口调整绑定，见设置消费限额。

请求示例

// 场景一：员工卡（公司池，SHARED——ruleIds 必填）
{
  "cardApplyRef": "ext-card-apply-0001",
  "subjectType": "CUSTOMER",
  "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "cardProfileId": "EMPLOYEE_CARD_CORPORATE_FUNDED",
  "ruleIds": ["5136744097353943556"]
}

// 场景二：公司公用卡（不记名——custodianCustomerId 必填；SHARED——ruleIds 必填）
{
  "cardApplyRef": "ext-card-apply-0002",
  "subjectType": "ORGANIZATION",
  "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardProfileId": "COMPANY_UTILITY_CARD",
  "custodianCustomerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "ruleIds": ["5136744097353943556"]
}

响应 data 与示例

字段	类型	说明
`cardApplyId`	String	卡申请 ID
`status`	String	本接口受理成功固定返回 `PENDING`（建卡结果经 Webhook 异步通知）；卡申请状态枚举全集：`PENDING` / `SUCCEED` / `REJECTED`

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943553",
    "status": "PENDING"
  }
}

错误码

错误码	说明
`CARD_PROFILE_INVALID`	卡类型不可用（如：类型码无效/未启用、本合作伙伴未开通、`subjectType` 与该类型适用主体不符）；具体原因见 message/reason
`CARD_LIMIT_EXCEEDED`	超开卡上限（公司级或持卡人级，活卡+在途计数）；具体级别见 message/reason
`SUBJECT_INVALID`	公司卡托管人缺失/非本公司有效员工
`SUBJECT_INVALID`	持卡主体（公司）不存在/无效
`CUSTOMER_INVALID`	持卡/托管员工不存在/无效
`DAPI_PERMISSION_DENIED`	合作伙伴不存在 / 未激活（入驻方身份由 AK 派生，属授权问题，归口网关授权码，HTTP 401；一般不出现）
`APPLY_DUPLICATE`	同一 `cardApplyRef` 已存在在途或已成功的申请，不可重复提交
`CARD_RULE_REQUIRED`	公司余额模式卡未携带 `ruleIds`（传空数组同样视为未携带）
`CARD_RULE_DUPLICATE`	`ruleIds` 内重复携带同一条规则。不会静默去重——重复通常意味着调用方对「实际绑了哪几条」的认知有偏差，悄悄收敛会让您误以为绑成功了 N 条。注：同时超过 5 条且存在重复时，返回本码而非 `CARD_RULE_LIMIT_EXCEEDED`
`CARD_RULE_LIMIT_EXCEEDED`	`ruleIds` 超过 5 条
`CARD_RULE_INVALID`	规则不存在、不属本公司、或非 ACTIVE——三者统一一个码，避免据此探测某规则是否存在于其他公司名下；具体原因见 message
`CARD_RULE_CURRENCY_NOT_MATCH`	规则的金额限额币种与卡可核销币种无交集

关联 Webhook：CARD_CREATED / CARD_REJECTED。

查询卡申请进度

GET /open-api-corp/card/v1/query-apply?cardApplyId=5136744097353943553

请求参数只有一个：cardApplyId（String，必填，≤20；卡申请 ID）。 响应 data：

字段	类型	说明
`cardApplyId`	String	申请 ID
`status`	String	卡申请状态枚举全集：`PENDING`（受理中 / 建卡中）/ `SUCCEED` / `REJECTED`
`cardId`	String	成功后的卡 ID（未建卡为空）
`errorCode`	String	被拒错误码：固定 `CARD_RISK_REJECTED`（仅 `REJECTED` 时）
`errorMessage`	String	被拒原因：固定 `risk check refused`（仅 `REJECTED` 时；不透传内部风控码）

// 场景一：建卡成功
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943553",
    "status": "SUCCEED",
    "cardId": "5185740066240790530",
    "errorCode": null,
    "errorMessage": null
  }
}

// 场景二：风控拒绝
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943553",
    "status": "REJECTED",
    "cardId": null,
    "errorCode": "CARD_RISK_REJECTED",
    "errorMessage": "risk check refused"
  }
}

错误码：APPLY_NOT_FOUND——卡申请不存在（或不属本合作伙伴）。

查询单张卡详情

GET /open-api-corp/card/v1/query?cardId=5185740066240790530

请求参数只有一个：cardId（String，必填，≤20；卡 ID）。 响应 data：

字段	类型	说明
`cardId`	String	卡 ID
`panFirst6`	String	卡号前 6 位（BIN；不返回完整 PAN）
`panLast4`	String	卡号后 4 位（不返回完整 PAN）
`organizationId`	String	所属公司
`subjectType`	String	`ORGANIZATION` / `CUSTOMER`
`subjectId`	String	持卡主体外部 id
`cardProfileId`	String	卡产品编码：`COMPANY_UTILITY_CARD` / `COMPANY_DEDICATED_PURPOSE_CARD` / `EMPLOYEE_CARD_CORPORATE_FUNDED` / `EMPLOYEE_CARD_SELF_FUNDED`
`cardNetwork`	String	`VISA` / `MASTERCARD` / `UPI`
`currency`	String	`USD` / `HKD`
`status`	String	卡状态：`ACTIVE` / `FROZEN` / `LOCKED` / `RESTRICTED` / `LOST` / `EXPIRED` / `CLOSED`

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "panFirst6": "520983",
    "panLast4": "5492",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "subjectType": "CUSTOMER",
    "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
    "cardProfileId": "EMPLOYEE_CARD_CORPORATE_FUNDED",
    "cardNetwork": "MASTERCARD",
    "currency": "USD",
    "status": "ACTIVE"
  }
}

错误码：CARD_INVALID——卡不存在 / 不属本合作伙伴 / 非 ACTIVE。

查询卡列表

GET /open-api-corp/card/v1/list?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&subjectType=EMPLOYEE&status=ACTIVE&page=1&pageSize=20

分页查询本合作伙伴名下的卡，过滤参数均可选：

字段	类型	必填	说明
`organizationId`	String	否	≤20；按所属公司过滤
`subjectType`	String	否	`ORGANIZATION` / `CUSTOMER`
`subjectId`	String	否	≤20；按持卡主体过滤
`status`	String	否	按卡状态过滤：`ACTIVE` / `FROZEN` / `LOCKED` / `RESTRICTED` / `LOST` / `EXPIRED` / `CLOSED`
`page`	Integer	否	从 1 起，默认 1
`pageSize`	Integer	否	1~100，默认 20

响应 data：分页外壳为 page（当前页，Integer）、pageSize（每页条数，Integer）、total（总条数，数字）、result（卡列表）；result 中每个元素的字段与上文单卡查询的响应 data 完全一致（cardId / panFirst6 / panLast4 / organizationId / subjectType / subjectId / cardProfileId / cardNetwork / cardProfileId / currency / status）。

下一步

SHARED 卡开卡前须先创建并持有可绑定的限额规则：设置消费限额
卡建成后展示卡号与 CVV2：查看卡敏感信息

​📄 正文