卡管理 · 概述 - 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/v2/detail`
查看卡敏感信息（卡号 / 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（已冻结）	卡片被冻结，暂停使用
CANCELLED（已销卡）	卡片被销卡，停止使用

实体卡状态（physicalCardStatus）

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

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

操作一览

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

操作	谁做	摘要	详见
查询卡详情 / 状态	接入机构	用 `/card/v2/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/v2/detail 查询卡详情。该接口的 cardId 为非必填：传值查询指定单卡、传空查询该用户名下的卡列表；响应 data 始终为数组。返回卡状态（虚拟卡 cardStatus 与实体卡 physicalCardStatus，枚举见上方状态机）以及该卡关联的余额信息（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）之间切换。

下一步

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

​📄 正文

​虚拟卡与实体卡

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

​核心概念：卡状态机

​操作一览

​查询卡详情

​冻结 / 解冻

​下一步