卡管理 · 概述 - DCS Technical Documentation

📄 正文

用户完成 KYC 后，您即可为其发卡，并在卡的整个生命周期内对它进行管理——冻结防盗刷、丢卡后注销、收到实体卡后激活、忘记密码后重置 PIN。作为持牌、自有 BIN 的发卡机构，DCS 在底层完成与卡组织、发卡处理器之间的状态同步，您只需关心业务语义：这张卡现在是什么状态、允许做哪些操作。 每张卡都归属于一个用户，因此发卡前请确保该用户已存在并通过 KYC（见用户管理）。本组涵盖发卡、查看卡敏感信息、冻结/解冻、管理 PIN、申请与激活实体卡，以及将卡片添加到 Apple Wallet 或 Google Wallet（Push Provisioning）。

虚拟卡与实体卡

卡按形态分为虚拟卡与实体卡，两者的交付与管理流程不同：

虚拟卡：发卡后即时可用，无需邮寄与激活。
实体卡：需邮寄给用户，收到后必须激活方可使用；激活与邮寄信息查询见下文。

两条能力交付路径（重要）

DeCard 托管的卡管理能力不是一组对称的独立 REST 接口，而是分两条路径交付，请勿照搬其他平台的「每个动作一个接口」模型：

能力	交付方式	入口
冻结 / 解冻	REST 接口	`POST /card/v2/block`
查询卡详情 / 状态	REST 接口	`GET /card/v3/detail`（v2 仍可用，见下文）
查看卡敏感信息（卡号 / CVV / 有效期）	托管引导页	`/redirect/v2/guidance-link` ⟶ `action=CARD_INFO`
申请实体卡	托管引导页	`/redirect/v2/guidance-link` ⟶ `action=CREATE_PHYSICAL_CARD`
激活实体卡	托管引导页	`/redirect/v2/guidance-link` ⟶ `action=ACTIVE_PHYSICAL_CARD`
更新 PIN	托管引导页	`/redirect/v2/guidance-link` ⟶ `action=UPDATE_PIN`

卡敏感信息查询、实体卡申请/激活、PIN 更新等涉及敏感操作的动作，统一通过托管引导页 /redirect/v2/guidance-link 按 action 枚举完成——用户在 DCS 托管页面内用短信或邮箱验证码完成操作，敏感信息不经接入机构后端。公开 guidance-link 的 action 枚举为 KYC_GUIDE / CARD_INFO / CREATE_PHYSICAL_CARD / ACTIVE_PHYSICAL_CARD / UPDATE_PIN / TRAVEL_RULE / KYC_EXTRA_DOC。DeCard 托管没有独立的 reset-pin / activate / convert-to-phy / invalidate REST 接口。

核心概念：卡状态机

DCS 用卡状态字段表达卡的生命周期阶段，所有管理操作本质上都是在驱动这台状态机。虚拟卡与实体卡各有一套状态枚举。

虚拟卡状态（cardStatus）

状态	含义	能否自助解冻
NORMAL（正常）	卡片已激活，可正常使用	—
FROZEN（已冻结）	由持卡人主动冻结，或连续三次 CVV / PIN 输入错误被冻结	可以，调冻结 / 解冻接口（解冻需短信或邮箱验证码）
BLOCKED（已封锁）	由发卡行侧发起的封锁：合规、风控、名单、产品下线、账管费不足等	不可以，需联系 DCS 处理
CANCELLED（已销卡）	卡片被销卡，永久失效	—

CARD_STATUS webhook 事件为兼容存量调用方，会把 BLOCKED 归一为 FROZEN，因此无法区分「可自助解冻」和「解不开」。需要区分请以 GET /card/v3/detail 与 CARD webhook 事件为准。

卡状态原因（statusReason）

当卡状态为 FROZEN / BLOCKED 时，可通过 statusReason 进一步了解状态变更的具体原因，用于向持卡人解释或决定后续动作。该字段随 GET /card/v3/detail 与 CARD webhook 事件返回，CARD_STATUS 不返回。

statusReason	非销户时的卡状态	说明
`NORMAL`	全部	无特殊原因
`USER_FREEZE`	FROZEN	持卡人主动冻结
`AUTHENTICATION_FAILED`	FROZEN	验证失败冻结（连续三次 CVV / PIN 输入错误）
`USER_REQUESTED_CLOSURE`	BLOCKED	持卡人已提出销卡、销户流程尚未完成，卡片处于封锁待销状态。不是 CANCELLED，这张卡仍是有效卡、会继续出现在卡列表里
`COMPLIANCE_REVIEW`	BLOCKED	合规审查封锁
`SECURITY_RESTRICTION`	BLOCKED	风控安全封锁
`VERIFICATION_OVERDUE`	BLOCKED	验证逾期未完成（未在规定期限内回应或提供所需验证资料）
`ACCOUNT_TERMINATED`	BLOCKED	账户已终止
`ACCOUNT_FEE_INSUFFICIENT`	BLOCKED	账户管理费不足。请引导用户在 D-Vault 充值，补足后由我方解除封锁并通过 `CARD` 事件通知，接入机构无需调用任何接口
`OTHER`	BLOCKED	其他原因

第二列是卡未销户时的对应状态。卡片一旦在我方核心侧注销，cardStatus 一律为 CANCELLED，与该列无关——statusReason 此时会保留销户前最后一次的原因值。所以不要用 statusReason 反推 cardStatus：看到 USER_REQUESTED_CLOSURE 不代表这张卡一定是 BLOCKED，它也可能已经是 CANCELLED。判断卡片能否使用、能否自助解冻请一律以 cardStatus 为准。

实体卡状态（physicalCardStatus）

状态	含义
UN_APPLY（未申请）	尚未申请实体卡
INACTIVE（未激活）	已申请实体卡，但未激活，无法使用
ACTIVE（已激活）	卡片已激活，可正常使用
REPLACE（换卡）	卡片处于换卡流程中
FROZEN（已冻结）	卡片被冻结，暂停使用
CANCELLED（已销卡）	卡片被销卡，停止使用

换卡（Replace Card）：当前公开接口中没有换卡 action 或 REST 接口，REPLACE 仅作为 physicalCardStatus 的一个状态值出现。如需换卡，请联系 DCS 团队确认可用方式。

操作一览

每项操作的一句话摘要与入口如下；REST 类操作（冻结/解冻、查详情）在本页下文展开，引导页类操作（查卡密、实体卡申请/激活、PIN）见各自子页。

操作	谁做	摘要	详见
查询卡详情 / 状态	接入机构	用 `/card/v3/detail` 查卡状态与余额；`cardId` 传空可查用户名下全部卡	本页 · 查询卡详情
冻结 / 解冻	接入机构	用 `/card/v2/block` 切换 `block` 布尔值，冻结防盗刷、解冻恢复使用	本页 · 冻结 / 解冻
查看卡敏感信息	终端用户	引导页 `action=CARD_INFO`，在 DCS 托管页内展示完整卡号/CVV/有效期	查看卡敏感信息
申请实体卡	终端用户	引导页 `action=CREATE_PHYSICAL_CARD`，用户填邮寄信息提交申请	申请卡
激活实体卡	终端用户	引导页 `action=ACTIVE_PHYSICAL_CARD`，用户收到卡后激活	申请卡
重置 / 更新 PIN	终端用户	引导页 `action=UPDATE_PIN`，用户在托管页内设置 PIN，明文不经接入机构	管理卡片 PIN
添加到数字钱包	终端用户	调绑卡 API 把卡推送至 Apple / Google Wallet	Apple Pay 与 Google Pay 绑卡

查询卡详情

通过 GET /card/v3/detail 查询卡详情。该接口的 cardId 为非必填：传值查询指定单卡、传空查询该用户名下的卡列表；响应 data 始终为数组。返回卡状态（虚拟卡 cardStatus 与实体卡 physicalCardStatus，枚举见上方状态机）、statusReason，以及该卡关联的余额信息（walletBalance / caBalance / cardBalance / balanceCurrency / billingCurrency）。每张卡关联用户级余额、授权决策在 DCS 内部完成，是 DeCard 托管（独立账户）模式的核心特征。余额管理详见用户余额。

该接口以 cardId 精确标识卡片。

冻结 / 解冻

通过 POST /card/v2/block 冻结或解冻卡——这是同一个接口，用 block 布尔值切换方向：block=true 冻结、block=false 解冻。冻结可在卡片疑似被盗刷或用户主动暂停时立即生效。

字段	类型	必填	说明
`externalUserId`	string	是	用户 ID
`cardId`	string	是	卡 ID
`block`	boolean	是	`true` = 冻结；`false` = 解冻
`smsCode` / `emailCode`	string	解冻时必填	解冻验证码，二选一

冻结（block=true）通常无需验证码。
解冻（block=false）需要验证码：传 smsCode（短信）或 emailCode（邮箱）二选一。

冻结卡（无需验证码）

{
  "externalUserId": "user_xxxxxxxx",
  "block": true,
  "cardId": "card_xxxxxxxx"
}

解冻卡（需验证码）

{
  "externalUserId": "user_xxxxxxxx",
  "block": false,
  "cardId": "card_xxxxxxxx",
  "smsCode": "<sms-otp>"
}

响应示例

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

data 为布尔值，表示本次冻结/解冻操作是否成功：true = 成功、false = 失败。响应结构 {code, message, messageDetail, data} 全站统一，详见 API 快速开始。

block 接口只能在 NORMAL ⇄ FROZEN（或 ACTIVE ⇄ FROZEN）之间切换。

处于 BLOCKED 的卡由发卡行侧封锁，接入机构无法用本接口解除，需联系 DCS。由于 v1 / v2 把 BLOCKED 归一成了 FROZEN，仅凭 v2 的出参无法预先识别这类卡——改用 GET /card/v3/detail 判断。

解冻失败的三个错误码 状态层面允许自助解冻，不代表下一次调用一定成功。请分别处理：

错误码	含义	处置
`UNFREEZE_DAILY_LIMIT_EXCEEDED`	同一张卡当日成功解冻次数已达上限	提示用户次日再试。注意这个码没有 `CARD_` 前缀，请按实际字符串匹配
`CARD_UNFREEZE_UNSUPPORTED_L4`	账户管理费不足	引导用户在 D-Vault 充值，不要重试解冻
`CARD_UNFREEZE_UNSUPPORTED`	该卡不在可自助解冻范围内（`cardStatus` 为 `BLOCKED`）	引导联系客服

下一步

申请卡——为已通过 KYC 的用户申请虚拟卡或实体卡。虚拟卡发卡后即时可用；实体卡需邮寄后激活。
查看卡敏感信息——通过托管引导页（action=CARD_INFO）安全展示完整卡号、CVV 与有效期，敏感信息不经接入机构后端。
管理卡片 PIN——通过托管引导页（action=UPDATE_PIN）让用户在 DCS 托管页内设置/更新 PIN，接入机构不接触明文或密文 PIN。
Apple Pay 与 Google Pay 绑卡——在您的应用内将 DCS 发行的 Visa 卡一键添加到 Apple Wallet 或 Google Wallet，无需在钱包应用中手动输入卡号。

​📄 正文

​虚拟卡与实体卡

​两条能力交付路径（重要）

​核心概念：卡状态机

​卡状态原因（statusReason）

​操作一览

​查询卡详情

​冻结 / 解冻

​下一步

📄 正文

虚拟卡与实体卡

两条能力交付路径（重要）

核心概念：卡状态机

卡状态原因（statusReason）

操作一览

查询卡详情

冻结 / 解冻

下一步