📄 正文
发卡永远从虚拟卡开始：申请通过即可用；需要实体卡时对已激活的虚拟卡同号升级。本页按「申请 → 查询 → 展示卡号 → 升级实体卡」的顺序讲清每个接口的关键参数与前置条件。申请虚拟卡
POST /open-api-corp/card/v1/apply——受理返回 cardApplyId，风控与建卡全程异步，终态经 Webhook CARD_CREATED / CARD_REJECTED 通知（兜底 GET /card/v1/query-apply）。
常见拒绝：
CARD_RULE_REQUIRED（SHARED 卡没带规则，传空数组同样算没带）、CARD_RULE_DUPLICATE（重复携带同一条规则）、CARD_LIMIT_EXCEEDED（超开卡上限，活卡与在途申请合并计数）、SUBJECT_INVALID（公司卡托管人缺失或非本公司有效员工）。GET /card/v1/query-apply?cardApplyId=...——status=SUCCEED 时返回 cardId；REJECTED 时 errorCode 固定为 CARD_RISK_REJECTED（不透传内部风控码）。
查询卡与卡列表
- 单卡：
GET /open-api-corp/card/v1/query?cardId=...，返回panFirst6/panLast4（不返回完整卡号）、所属公司、持卡主体、cardProfileId、卡组织cardNetwork（VISA / MASTERCARD / UPI）、卡币种cardCurrency与状态。 - 列表：
GET /open-api-corp/card/v1/list，可按organizationId/subjectType/subjectId/status过滤，page/pageSize分页。
开通独立余额卡收款账号
POST /open-api-corp/card/v1/open-va——为独立余额卡按币种开通银行虚拟账号（VA）供入金：传 cardId + fundingCurrencies（USD / HKD，可多个），响应 data 为 null——开通后的收款账号请调获取充值入金信息。花公司资金池的卡不可开 VA（CARD_NOT_DEDICATED）。独立余额卡也可不开 VA、改由公司资金池划拨充值，见资金与对账。
获取卡敏感信息
POST /open-api-corp/card/v1/retrieve-secure-card——返回密文级 encryptedPan / encryptedCvv2 / encryptedExpireDate 与本次随机 iv，供在自有前端解密展示。仅限 PCI DSS 白名单合作伙伴调用（否则 PCI_NOT_CERTIFIED）；无 PCI DSS 的合作伙伴集成 DCS 卡信息安全托管页。
虚拟卡转实体卡
四步链路：升级申请 → 查物流 → 激活 → 设 PIN。步骤详见实体卡，卡状态见状态机与冻结体系。 ① 升级申请：POST /open-api-corp/card/v1/virtual-to-physical——传 cardApplyRef（幂等键）、cardId（须为 ACTIVE 虚拟卡）、cardLayoutCode（卡面 code，取值由 DCS 按合作伙伴配置下发）、embossingName（≤26，卡面刻印第一行）与可选 embossingName2。寄送地址从持卡人 / 托管人名下读取并锁定为快照——地址未维护返回 SHIPPING_ADDRESS_REQUIRED，同卡已有在途申请返回 CARD_CONVERT_IN_PROGRESS。
② 查物流：GET /open-api-corp/card/v1/shipping-info——返回 trackingNumber / trackingCompanyName（未寄出为 null）；寄出时推送 Webhook CARD_SHIPPED。
③ 激活：POST /open-api-corp/card/v1/activate——前置是已寄出（否则 CARD_NOT_SHIPPED），本接口幂等；成功推送 CARD_ACTIVATED。
④ 设 PIN：POST /open-api-corp/card/v1/set-pin——前置是已激活。PIN 与核身字段（encryptedPin / encryptedCvv2 / encryptedExpireDate / encryptedPanLast4）由您用 SK 做 AES-GCM 加密后上送，四个密文共用同一 iv，与 retrieve-secure-card 同一套加解密约定、方向相反。PIN 明文须 4 位数字、禁连续、禁全同（PIN_RULE_VIOLATION）。
关联 Webhook
CARD_CREATED / CARD_REJECTED / 卡状态变更通知 / CARD_SHIPPED / CARD_ACTIVATED。