实体卡

📄 正文

实体卡由一张已激活（ACTIVE）的虚拟卡经「虚拟卡转实体卡」同号升级而来。升级前后卡号、有效期、CVV2 与 cardId 全程保持不变——激活前查询返回原虚拟卡信息，激活后按实体卡生效，因此您无需在升级后替换卡片或迁移任何绑定关系。卡状态背景见状态机与冻结体系。四步链路如下：

寄送地址挂在员工名下，受理虚拟卡转实体卡时读取并锁定为快照，此后修改地址不影响在途制卡。

① 升级申请：虚拟卡转实体卡

POST /open-api-corp/card/v1/virtual-to-physical

把 ACTIVE 虚拟卡同号升级为实体卡。寄送方式由 shippingAddressId 是否携带决定：不带走单个邮寄，寄给该卡持卡 / 托管员工，地址与邮寄手机号取自该员工；带则走批量邮寄，寄到该 id 对应的收件地址，同一 id 下同日受理的卡归入同一批次统一寄出。

请求参数

字段	类型	必填	说明
`companyId`	String	是	≤50；发起请求的公司Id
`cardPhysicalApplyRef`	String	是	≤64；合作伙伴侧申请唯一标识（幂等键）；字符集 `^[A-Za-z0-9_-]+$`
`cardId`	String	是	≤50；被升级虚拟卡；须属本合作伙伴 / 公司、当前为虚拟卡且 ACTIVE；持卡 / 托管员工由该卡派生
`cardLayoutCode`	String	是	卡面 code；须为已配置卡面（取值由 DCS 按合作伙伴配置下发，非固定枚举）
`embossingName`	String	是	≤20；卡面压花第一行
`embossingName2`	String	否	≤20；卡面压花第二行（可选）
`shippingAddressId`	String	否	≤50；批量收件地址标识；不传则寄给该卡持卡 / 托管员工

响应 data

字段	类型	说明
`cardPhysicalApplyId`	String	虚转实受理单 id

请求与响应示例

// 场景一：单个邮寄——不带 shippingAddressId，寄给该卡持卡 / 托管员工
{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardPhysicalApplyRef": "ext-v2p-0001",
  "cardId": "5185740066240790530",
  "cardLayoutCode": "LAYOUT_CLASSIC_BLACK",
  "embossingName": "DOE JOHN",
  "embossingName2": "EXAMPLE HK LIMITED"
}

// 场景二：批量邮寄——带 shippingAddressId，寄到该 id 对应的收件地址
{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardPhysicalApplyRef": "ext-v2p-0002",
  "cardId": "5185740066240790531",
  "cardLayoutCode": "LAYOUT_CLASSIC_BLACK",
  "embossingName": "LEE SIU MING",
  "embossingName2": "EXAMPLE HK LIMITED",
  "shippingAddressId": "100023"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardPhysicalApplyId": "5136744097353943557"
  }
}

错误码

错误码	说明
`CARD_INVALID`	卡不存在 / 不属本合作伙伴 / 非 ACTIVE
`CARD_NOT_VIRTUAL`	卡已是实体卡，不可再转
`CARD_CONVERT_IN_PROGRESS`	同卡已有在途虚转实申请（未终结）
`APPLY_DUPLICATE`	同一 `cardPhysicalApplyRef` 已受理（幂等）
`SHIPPING_ADDRESS_REQUIRED`	仅单个邮寄：持卡 / 托管员工未维护寄送地址
`SHIPPING_ADDRESS_INVALID`	仅批量邮寄：`shippingAddressId` 无效，或该收件地址不允许被这张卡使用
`COUNTRY_SANCTIONED`	收件国命中制裁名单
`LIMIT_PHYSICAL_EXCEEDED`	实体卡数超上限（公司级或持卡人级）

关联 Webhook：CARD_SHIPPED（寄出）/ CARD_ACTIVATED（激活）。

② 查询制卡寄送进度

GET /open-api-corp/card/v1/shipping-info

查询实体卡制卡寄送进度与物流单号。

请求参数

字段	类型	必填	说明
`companyId`	String	是	≤50；发起请求的公司Id
`cardId`	String	是	≤50；卡 id

响应 data

字段	类型	说明
`cardId`	String	卡 id
`trackingNumber`	String	物流单号（未寄出为空）
`trackingCompanyName`	String	物流公司

响应示例（已寄出 / 未寄出）

// 场景一：已寄出
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "trackingNumber": "SF1234567890123",
    "trackingCompanyName": "SF Express"
  }
}

// 场景二：未寄出
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "trackingNumber": null,
    "trackingCompanyName": null
  }
}

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

③ 激活实体卡

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

激活实体卡，前置是卡已寄出。本接口幂等——重复调用返回同样的成功结果。

请求参数与响应

请求参数：companyId（String，必填，≤36；发起请求的公司Id）与 cardId（String，必填，≤32；卡 id）。响应为动作类，data 为 null。

{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530"
  }
}

错误码

错误码	说明
`CARD_INVALID`	卡不存在 / 不属本合作伙伴
`CARD_NOT_SHIPPED`	卡未寄出，尚不可激活

关联 Webhook：CARD_ACTIVATED。

④ 设置 PIN

POST /open-api-corp/card/v1/set-pin

设置实体卡 PIN，前置条件是实体卡已激活。

PIN 与核身字段由合作伙伴用 SK 做 AES-GCM 加密后上送，与 retrieve-secure-card 同一套加解密约定、方向相反（约定见查看卡敏感信息：AES/GCM/NoPadding、128 位标签、密钥即 SK）。

请求参数

字段	类型	必填	说明
`companyId`	String	是	≤50；发起请求的公司Id
`cardId`	String	是	≤50；卡 id
`encryptedPin`	String	是	密文 PIN（企业密钥 AES-GCM；明文须 4 位数字、禁连续、禁全同）
`encryptedCvv2`	String	是	密文 CVV2（核身）
`encryptedExpireDate`	String	是	密文有效期（核身，原文 mm/yy）
`encryptedPanLast4`	String	是	密文卡号后四位（核身）
`iv`	String	是	本次随机 IV（Base64）；4 个密文字段共用同一个 `iv`

请求与响应示例

{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530",
  "encryptedPin": "UGluTW9ja0NpcGhlclRleHQrVGFnMTZC",
  "encryptedCvv2": "Q3Z2Mk1vY2tDaXBoZXJUZXh0K1RhZzE2Qg==",
  "encryptedExpireDate": "RXhwTW9ja0NpcGhlclRleHQrVGFnMTZC",
  "encryptedPanLast4": "TGFzdDRNb2NrQ2lwaGVyVGV4dCtUYWcxNkI=",
  "iv": "MTIzNDU2Nzg5MGFi"
}

响应 data 为 cardId 与 success（Boolean，是否设置成功）：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "success": true
  }
}

错误码

错误码	说明
`CARD_INVALID`	卡不存在 / 不属本合作伙伴
`CARD_NOT_ACTIVATED`	卡未激活，不可设置 PIN
`CARD_STATE_INVALID`	卡状态不允许设置 PIN；仅 ACTIVE / FROZEN 可设
`PIN_RULE_VIOLATION`	PIN 非 4 位数字 / 连续 / 全同

下一步

还没有可升级的虚拟卡？先发一张：申请虚拟卡
卡状态与冻结能力域背景：状态机与冻结体系

开始使用

基础概念

使用指南

客户成功

📄 正文

① 升级申请：虚拟卡转实体卡

请求参数

响应 data

请求与响应示例

错误码

② 查询制卡寄送进度

请求参数

响应 data

响应示例（已寄出 / 未寄出）

③ 激活实体卡

请求参数与响应

错误码

④ 设置 PIN

请求参数

请求与响应示例

错误码

下一步

​📄 正文

​① 升级申请：虚拟卡转实体卡

​请求参数

​响应 data

​请求与响应示例

​错误码

​② 查询制卡寄送进度

​请求参数

​响应 data

​响应示例（已寄出 / 未寄出）

​③ 激活实体卡

​请求参数与响应

​错误码

​④ 设置 PIN

​请求参数

​请求与响应示例

​错误码

​下一步

📄 正文

① 升级申请：虚拟卡转实体卡

请求参数

响应 data

请求与响应示例

错误码

② 查询制卡寄送进度

请求参数

响应 data

响应示例（已寄出 / 未寄出）

③ 激活实体卡

请求参数与响应

错误码

④ 设置 PIN

请求参数

请求与响应示例

错误码

下一步