查看卡敏感信息 - DCS Technical Documentation

📄 正文

卡的完整卡号（PAN）、CVV2 与有效期属于敏感认证数据，常规卡查询接口只返回 panFirst6 / panLast4（见申请虚拟卡中的单卡查询）。要向持卡人展示完整卡面信息，持有 PCI DSS 的合作伙伴调用本页的 retrieve-secure-card 取密文自行解密展示；无 PCI DSS 的合作伙伴可集成 DCS 平台卡信息安全托管页。本页同时收录独立余额卡的收款账号开通接口 open-va。

获取卡敏感信息

POST /open-api-corp/card/v1/retrieve-secure-card

返回密文级 PAN / CVV2 / 有效期，供在前端安全展示。

仅限持有 PCI DSS 的合作伙伴可调（否则返回 PCI_NOT_CERTIFIED）；无 PCI DSS 的合作伙伴可集成平台卡信息安全托管页。

请求参数

字段	类型	必填	说明
`cardId`	String	是	≤20；卡 ID；须属本合作伙伴且为 ACTIVE

响应 data

字段	类型	说明
`cardId`	String	卡 ID
`encryptedPan`	String	卡号（AES-GCM 密文）
`encryptedCvv2`	String	CVV2（密文）
`encryptedExpireDate`	String	有效期（密文，原文 mm/yy）
`iv`	String	本次随机 IV（Base64），解密用

解密约定

算法：AES/GCM/NoPadding，128 位（128-bit）认证标签。
密钥：即您的 SK。
IV：encryptedPan / encryptedCvv2 / encryptedExpireDate 三个密文字段共用同一个 iv（每次调用随机生成，Base64 编码返回）。

CVV2 与有效期实时获取、不可缓存——每次需要展示时重新调用本接口取密文解密。

请求与响应示例

{
  "cardId": "5185740066240790530"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "encryptedPan": "UGFuTW9ja0NpcGhlclRleHRCYXNlNjQrVGFnMTZC",
    "encryptedCvv2": "Q3Z2Mk1vY2tDaXBoZXJUZXh0K1RhZzE2Qg==",
    "encryptedExpireDate": "RXhwTW9ja0NpcGhlclRleHQrVGFnMTZC",
    "iv": "MTIzNDU2Nzg5MGFi"
  }
}

错误码

错误码	说明
`PCI_NOT_CERTIFIED`	未开通卡敏感信息访问权限（不在 PCI 白名单）
`CARD_INVALID`	卡不存在 / 不属本合作伙伴 / 非 ACTIVE

PCI DSS · 持卡人数据保护

按 PCI DSS 要求，完整卡号（PAN）、CVV2 与有效期属于敏感认证数据，须全程按最小暴露原则处理：

掩码默认：默认情况下，前端仅展示掩码卡号——保留前 6 位与后 4 位（如 531993 •••• •••• 8888），CVV2 与有效期不作默认展示。
按需临时展示：仅当业务确有需要且完成持卡人身份核验后，方可临时解密并在前端展示明文。
明文不落地：展示过程中不得将明文以任何形式落地存储——数据库、文件、日志、缓存、埋点与链路追踪等均不得留存；CVV2 在授权后亦不得保存。
密钥进 KMS：用于解密的密钥须托管于密钥管理服务（KMS）并定期轮换。

为独立余额卡开通收款账号

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

为独立余额卡按币种开通充值账号（VA）；合作伙伴可按需选择银行转账入金或公司资金池调拨为卡充值（充值与对账见资金与对账）。

请求参数

字段	类型	必填	说明
`cardId`	String	是	≤32；卡 ID；须属本合作伙伴、且为独立余额卡
`fundingCurrencies`	`Array<String>`	是	待开通 VA 的币种列表（至少一个，取值 `USD` / `HKD`；各申一个 VA）；元素不可空、币种不可重复，空/重复/非枚举 → `DAPI_PARAM_INVALID`；还须为本企业允许币种的子集，超出范围整单拒绝（不做部分开通）→ `CURRENCY_NOT_ALLOWED`

响应

动作类接口，data 为 null。开通后的收款账号请调获取充值入金信息按 subjectType=CARD 查询——开 VA 与查账号分属两个接口，本接口只负责开通。

请求与响应示例

{
  "cardId": "5185740066240790531",
  "fundingCurrencies": ["USD", "HKD"]
}

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

错误码

错误码	说明
`CARD_INVALID`	卡不存在 / 不属本合作伙伴
`CARD_NOT_DEDICATED`	非独立余额卡，不可开 VA
`UNSUPPORTED_CURRENCY`	币种不支持（仅 `USD` / `HKD`）
`CURRENCY_NOT_ALLOWED`	申请币种不在该企业允许的币种列表内（message 点名具体币种）
`SUBJECT_INVALID`	卡账本主体（account_holder）缺失，或持卡人 KYB/KYC 户名缺失（均属主体侧问题，无法开 VA）

下一步

给独立余额卡入金、公司资金池调拨与对账：资金与对账
把已激活的虚拟卡同号升级为实体卡：实体卡

​📄 正文

​获取卡敏感信息

​请求参数

​响应 data

​解密约定

​请求与响应示例

​错误码

​PCI DSS · 持卡人数据保护

​为独立余额卡开通收款账号

​请求参数

​响应

​请求与响应示例

​错误码

​下一步

📄 正文

获取卡敏感信息

请求参数

响应 data

解密约定

请求与响应示例

错误码

PCI DSS · 持卡人数据保护

为独立余额卡开通收款账号

请求参数

响应

请求与响应示例

错误码

下一步