本页带您在沙盒环境用推荐的最佳实践路径发出第一张可用卡。作为持牌、自有 BIN 的发卡机构，DCS 的托管模式让发卡、KYC、授权与清算都在同一套 API 内完成，您无需自建任何卡核心能力。
本页只走一条最简路径（手机号注册、托管引导页开卡、单张虚拟卡、单一币种入金）；完整的 KYC 流程、链/币种矩阵、卡管理与对账见各自专页。
开始前
请确认您已完成以下准备（详见 前置准备）：
- 已了解 DeCard 托管模型：授权决策在 DCS 系统内完成，持卡人将资金转入 DCS 托管，DCS 据其可用资产实时决定卡额度（见 概述）。
- 已领取调用凭证 API Key / Secret Key。
- 已向 DCS 提供网络出口 IP（DCS 启用接口白名单机制）。
- Webhook 回调地址（必配）：本流程的开卡结果依赖 Webhook 送达，未配置将无法完成步骤 4。
- WebSocket 连接（可选）：如需实时推送余额变动、交易结果等，可额外配置，详见 Webhook 与 WebSocket。
环境地址 —— 沙盒：https://api.thedecard-sandbox.com；生产：https://api.thedecard.com。
鉴权：所有请求需携带 X-DAPI-API-KEY / X-DAPI-TIMESTAMP / X-DAPI-NONCE / X-DAPI-SIGN 四个头并计算 HMAC-SHA256 签名。完整规则（签名拼接公式、防重放说明及代码示例）见 鉴权指南。下文示例为聚焦业务字段省略了鉴权头，实际调用时必须携带。SecretKey 仅在本地参与签名计算，绝不上送。
路径前缀：DeCard 托管模式各模块直接使用 /account/、/card/、/crypto/、/user-asset/、/redirect/、/simulation/ 前缀（无 /open-api/ 前缀）。
下文所有手机号、用户 ID、地址等示例值均为脱敏占位，请替换为您自己的真实值。
📄 正文
全程 6 步。整体形态是：您调 API 发起，持卡人在 DCS 托管页面完成敏感操作，结果通过 Webhook 回到您这里。
上图为生产路径。沙盒下步骤 6 的入金与消费改用模拟器接口，见该步说明。
步骤 1: 发送短信验证码
DeCard 托管模式下用户以「手机号 + 短信 OTP」两段式注册。先为目标手机号请求一条验证码：
mobileCode 为手机号国家码（ISO 2 位，如 SG / CN / US）；mobile 为本机号码（不加区号）。新用户注册时 externalUserId 留空。
behavioral 是场景枚举，标识本次验证码的用途，取值 REGISTER（注册）/ CARD_UNFROZEN（解冻卡）/ WITHDRAW（提现）。注册场景填 REGISTER。
成功响应（结构统一为 {code, message, messageDetail, data}，成功码 code = SYS_SUCCESS）：
本接口的 data 固定为空字符串——验证码通过短信下发，不在响应体里返回。以 code = SYS_SUCCESS 判断是否成功即可。
关于响应结构：messageDetail 成功时通常为 null；在失败或需要前端提示的场景下，它是一个对象（含 message / title / type / icon / action / linkTitle / linkUrl 等字段）。本页后续示例为聚焦业务字段，结构一律按成功态展示。
步骤 2: 注册用户
凭上一步收到的短信验证码完成注册：
手机号注册需 mobileCode + mobile + smsCode 三者同时提供。
DCS 另支持邮箱注册路径（email + emailCode），与手机号路径严格互斥——smsCode 与 emailCode 同时传会被拒绝并返回 SMS_EMAIL_CODE_MUTUALLY_EXCLUSIVE。本页只走手机号路径，邮箱路径见 用户注册。
响应的 data 字段直接返回 externalUserId（字符串），后续所有接口以它标识用户，请务必保存：
步骤 3: 获取开卡引导链接
这是推荐的开卡方式。 KYC 与开卡都在 DCS 托管的 H5 页面内完成——持卡人的证件、人脸等敏感材料直接提交给 DCS，不经过您的后端，您无需承担这部分合规与存储责任。
action、externalUserId、successRedirectUrl、errorRedirectUrl 四者必填。
language 取值为小写连字符形式且大小写敏感：zh / en / ko / ja / zh-Hant / th / vi。传入白名单以外的值会被静默降级为默认语言，不会报错——请严格按此列表传。
完整参数（theme / mode / primaryColor / selectCardPageShow 等）见 H5 KYC 与开卡引导页。
响应的 data 就是一次性引导链接（字符串），把它交给持卡人在浏览器打开即可：
⏱ 链接有效期 5 分钟（服务端 secret TTL 为 300 秒），过期后页面失效需重新申请。
因此不要用邮件、工单等异步渠道下发链接——请在持卡人处于活跃会话时即时生成、即时跳转；用户中途放弃后重新进入，也应重新调本接口取新链接，不要缓存复用。
两个前置校验会直接拦下请求，接入时请预先处理：
- 该用户 KYC 已是
PASS 或 PENDING 时返回 OPERATION_UNSUPPORTED——不允许重复发起。
- 触发当日进件限流时返回
KYC_APPLY_LIMIT_EXCEEDED——请做好重试节流与用户提示。
步骤 4: 接收卡申请 Webhook
持卡人在托管页完成提交后，开卡结果通过 CARD_APPLY Webhook 推送给您。本流程中接入机构不主动发起开卡请求，因此这是拿到 applyId 的唯一途径（cardId 在开卡成功后也可用步骤 5 的查卡接口取到）。
同一事件会同时投递到 Webhook 与 WebSocket 两个通道（服务端先推 WS 再推 Webhook），两边数据内容一致。只接 Webhook 即可完成本流程；接了 WebSocket 的话注意做去重。
CARD_APPLY 事件的 data 结构：
status 只有 3 个公开值（KYC 通过、卡创建成功等内部中间状态统一显示为 PENDING）：
收到 Webhook 后请在 2 秒内返回 2xx（DCS 侧 connectTimeout 与 socketTimeout 均为 2000 ms），建议先存储再异步处理业务，否则会被判超时并重复投递。详见 Webhook 与 WebSocket。 needExtraInfo = true。此时用 同一个 applyId 再申请一条补件引导链接：
KYC_EXTRA_DOC 场景下 applyId 必填，缺失返回 OPERATION_UNSUPPORTED；applyId 不属于该用户返回 PERMISSION_DENIED；该申请的 needExtraInfo 不为 true 时同样返回 OPERATION_UNSUPPORTED——请以 Webhook 的 needExtraInfo 为准再发起，不要盲目调用。
持卡人补件完成后，DCS 会再次推送 CARD_APPLY，直至 status 进入 SUCCEED 或 FAILED 终态。
步骤 5: 卡管理
拿到 cardId 后即可进入卡的日常管理。
查持卡列表 / 单卡详情
externalUserId 必填；cardId 可选，留空返回该用户全部卡，传入则查单张。
返回字段含 cardStatus（NORMAL / FROZEN / CANCELLED）、cardNo（脱敏）、cardHolder、physicalCardStatus 等。
把完整卡号展示给持卡人
出于 PCI 合规，完整卡号、CVV、有效期不会通过 API 返回到您的后端。请用 CARD_INFO 引导页，由持卡人在 DCS 托管页面直接查看：
CARD_INFO / CREATE_PHYSICAL_CARD / ACTIVE_PHYSICAL_CARD / UPDATE_PIN 这四个 action 必须携带 cardId，且该用户须已有卡，否则请求会被拒绝。
冻结 / 解冻
block = true 冻结、false 解冻。响应 data 为布尔值，表示本次冻结/解冻操作是否成功（true = 成功 / false = 失败）。
解冻需要二次验证：block = false 时必须额外传 smsCode 或 emailCode，请先用步骤 1 的验证码接口以 behavioral = CARD_UNFROZEN 下发。冻结则不需要。
实体卡申请与激活、重置 PIN 等其余能力见 卡管理。
步骤 6: 入金与模拟消费
入金 —— 生产环境
查该用户的加密充值地址，向该地址链上转账即可：
三个参数均必填。v2 返回 network / address / coin / fxRate / status。
本接口不返回最小充值额与所需链上确认数。如果您需要向持卡人提示”最少充多少、要等几个确认”，请从 network-coin 配置获取（minConfirm 等字段）或另行维护该配置。 链与币种矩阵见 加密货币充值。
模拟资金充入用户的加密入金地址，address 取自上一步的 deposit-address。
确认余额
余额字段：free = 可用、freeze = 冻结、total = 总额（API 实际字段名以此为准）。返回的是数组，请按 asset 遍历。
模拟一笔消费
用模拟器发起一笔卡授权，验证您的 Webhook 处理与额度变化：
推荐用 v2（以 cardId 定位卡，与步骤 4 拿到的 cardId 直接衔接）；v1 用 cardMantissa（卡号后四位）定位，仅为兼容保留。
authType 枚举：EXPEND（消费）| REFUND（退货）| REVERSAL（消费冲正）。
授权在 DCS 系统内依用户可用资产完成，approved 即授权结果。沙盒模拟会产生真实交易记录、触发 Webhook 并更新余额，但不涉及真实资金。完整场景见 模拟交易。
至此，第一张可用卡已发出并完成入金，也已验证一笔模拟消费。
下一步
- 完整 KYC 流程与状态机 → 合规 — KYC 申请、审核、POA 补充与 AML 处理的完整流程
- 引导页全部 action 与参数 → H5 KYC 与开卡引导页 — 7 个 action 的适用场景、语言与主题定制、链接有效期
- 申请实体卡、换卡、重置 PIN → 卡管理 — 卡的全生命周期管理
- 加密充值链/币种矩阵、链上提现 → 资金充提 — 多链充值与提现
- 沙盒模拟交易全场景 → 模拟交易 — 消费、退货、冲正等全部交易类型
- 鉴权头与 HMAC-SHA256 签名规则 → 鉴权指南 — 必带头列表、签名拼接公式、防重放说明与代码示例
- Webhook & WebSocket 实时推送 → Webhook 与 WebSocket — 全部 9 类事件的数据结构、重试与幂等处理
