申请卡（虚拟卡与实体卡） - DCS Technical Documentation

📄 概述

用户完成 KYC 后，您即可通过一次 API 调用为其发行虚拟卡，供其立即用于线上消费，并按需进一步申请实体卡。作为持牌、自有 BIN 的发卡机构，DCS 承接发卡、KYC 审核、授权决策与清算；您只需关心如何提交申请、如何查状态、拿到卡之后做什么。 DCS 支持两种卡介质：

虚拟卡：无实体介质，申请通过即自动激活，可立即用于线上消费。
实体卡：需邮寄给用户，收到后须激活并设置 PIN 方可使用。

虚拟卡按使用形态又分两类：一次性虚拟卡（单次交易后即失效，安全性最高，适合一次性支付）与可重复使用虚拟卡（在卡片有效期内可多次使用，通常可设单笔 / 总消费额度）。两者均不能直接用于线下实体店刷卡或 ATM 取现。具体哪类由卡产品（categoryId）决定，开卡前请向 DCS 确认。

前置条件

用户已注册并创建账户（见用户注册）。
KYC 资料齐备：Sumsub shareToken、必要的 POA 文件与就业/资金来源信息。

两种申请方式

两种申请方式并存，二选一：

方式	适用	入口
H5 内嵌引导页	希望复用 DCS 现成 KYC/开卡 UI，少写前端	`POST /redirect/v2/guidance-link`（见 H5 引导页）
OPEN-API	自管前端、自行采集 KYC 资料	`POST /card/v1/virtual-card/apply`（仅虚拟卡）

实体卡在 DeCard 托管侧没有独立的「申请实体卡」直连 API。实体卡的申请、激活、设 PIN 全部通过 H5 引导页完成（见下文实体卡章节），不存在 physical-card/apply 或「虚拟卡转实体卡」直连接口。

申请流程总览

OPEN-API 方式的主流程只有两步——提交申请，然后轮询到终态（也可通过 Webhook 接收结果）：

如需随申请补交 POA 文件，在提交申请前先完成三步：

调 POST /account/v1/generate-file-upload-prepare 获取预上传 URL 与 objectKey；

用返回的 URL 直接 PUT 上传 POA 文件；

将 objectKey 填入申请请求的 POA 字段（见下方字段表）。

申请虚拟卡

方式一：H5 内嵌引导页

调用 POST /redirect/v2/guidance-link，action 传 KYC_GUIDE，获取一段引导页 URL；在前端打开后由 DCS 引导用户完成 KYC + 开卡。引导页参数与渲染说明见 H5 引导页。

H5 申请流程截图

下面两组截图展示 H5 引导页申请虚拟卡的完整体验，供您预览页面形态。 KYC 渠道校验（用户在引导页内完成身份验证渠道校验各步骤）：

KYC 的 POA 信息采集（用户在引导页内填写并提交地址证明等补充信息）：

方式二：OPEN-API

调用 POST /card/v1/virtual-card/apply 直接提交申请（含 KYC 资料）。 请求字段：

字段	类型	必填	说明	约束
`externalUserId`	string	REQUIRED	用户 ID	用户外部 ID
`categoryId`	integer (Long)	REQUIRED	卡类别 ID
`applyRef`	string	REQUIRED	申请单幂等字段
`kycInfo.sumsubShareToken`	string	REQUIRED	Sumsub 令牌	最大 500
`kycInfo.email`	string	REQUIRED	邮箱	最大 100
`kycInfo.poaDocType`	string	POA 场景	POA 文件类型枚举（如 `BANK_STATEMENT`；`UTILITY_BILL` 须为 90 天内、法国 75 天内）。完整取值见申请卡参数字典	最大 50
`kycInfo.poaDocUrlList`	string[]	POA 场景	POA 文件 URL 列表（见 POA 文件交换）
`kycInfo.poaDocDate`	string	POA 场景	POA 文件日期（POA 文件须在 3 个月内）	最大 10
`kycInfo.addressLine1`	string	条件必填	地址行 1	最大 1024
`kycInfo.addressLine2`	string	可选	地址行 2	最大 1024
`kycInfo.state`	string	可选	州/省	最大 128
`kycInfo.city`	string	条件必填	城市	最大 128
`kycInfo.postalCode`	string	条件必填	邮政编码	最大 50
`kycInfo.country`	string	条件必填	国家码，2 位 ISO（如 CN/US/SG）	固定 2 位
`kycInfo.employmentStatus`	string	条件必填	工作状态	最大 50
`kycInfo.employerName`	string	条件必填	公司名；当 `employmentStatus = EMPLOYED` 时必填	最大 100
`kycInfo.employmentJobIndustry`	string	条件必填	行业	最大 50
`kycInfo.occupation`	string	条件必填	职业	最大 50
`kycInfo.jobSeniority`	string	条件必填	就业资历	最大 50
`kycInfo.purposeOfAccount`	string	条件必填	开户目的	最大 100
`kycInfo.sourceOfFunds`	string	条件必填	资金来源	最大 100
`kycInfo.sourceOfFundsCountry`	string	条件必填	资金来源国家码，2 位 ISO	固定 2 位
`kycInfo.sourceOfWealth`	string	条件必填	财富来源	最大 100
`kycInfo.fullName`	string	可选	姓名（H5 增强 KYC 用）
`kycInfo.birthday`	string	可选	生日（H5 增强 KYC 用）
`kycInfo.gender`	string	可选	性别（H5 增强 KYC 用）
`kycInfo.residenceCountry`	string	可选	居住国（H5 增强 KYC 用）

上表字段长度供参考；实际接入时请以接口返回的校验错误信息为准，不要沿用其他方案的字段长度。

请求示例（占位/脱敏）：

{
  "externalUserId": "<DECARD_USER_ID>",
  "categoryId": 1001,
  "applyRef": "<YOUR_IDEMPOTENT_REF>",
  "kycInfo": {
    "sumsubShareToken": "<SUMSUB_SHARE_TOKEN>",
    "email": "user@example.com",
    "poaDocType": "BANK_STATEMENT",
    "poaDocUrlList": ["<OBJECT_KEY_FROM_UPLOAD>"],
    "poaDocDate": "<POA_DOC_DATE>",
    "addressLine1": "<ADDRESS_LINE_1>",
    "city": "<CITY>",
    "postalCode": "<POSTAL_CODE>",
    "country": "SG",
    "employmentStatus": "EMPLOYED",
    "employerName": "<EMPLOYER>",
    "employmentJobIndustry": "<INDUSTRY>",
    "occupation": "<OCCUPATION>",
    "jobSeniority": "<SENIORITY>",
    "purposeOfAccount": "<PURPOSE>",
    "sourceOfFunds": "<SOURCE_OF_FUNDS>",
    "sourceOfFundsCountry": "SG",
    "sourceOfWealth": "<SOURCE_OF_WEALTH>"
  }
}

响应字段（data）：

字段	类型	说明
`applyId`	string	申请 ID
`cardId`	string	卡 ID（成功后返回）
`categoryId`	integer	卡类别 ID
`applyRef`	string	申请单幂等字段（回显）
`status`	string	申请状态，见申请状态，`PENDING / SUCCEED / FAILED`
`errorCode`	string	失败错误码
`errorReason`	string	失败原因描述
`needEddFile`	boolean	是否需要补充 EDD（加强尽职调查）文件
`needExtraInfo`	boolean	是否需要用户补充资料，见 needExtraInfo
`remark`	string	备注

成功响应示例（脱敏）：

{
  "code": "SYS_SUCCESS",
  "message": "SUCCESS",
  "messageDetail": null,
  "data": {
    "applyId": "<APPLY_ID>",
    "cardId": "<CARD_ID>",
    "categoryId": 1001,
    "applyRef": "<YOUR_IDEMPOTENT_REF>",
    "status": "SUCCEED",
    "needEddFile": false,
    "needExtraInfo": false,
    "remark": null
  }
}

失败响应示例（脱敏）：

{
  "code": "SYS_SUCCESS",
  "message": "SUCCESS",
  "messageDetail": null,
  "data": {
    "applyId": "<APPLY_ID>",
    "status": "FAILED",
    "errorCode": "<ERROR_CODE>",
    "errorReason": "<失败原因描述>",
    "needEddFile": false,
    "needExtraInfo": false
  }
}

响应结构统一为 { code, message, messageDetail, data }（无 success 布尔字段）。code = SYS_SUCCESS 仅表示请求被成功受理，业务结果以 data.status 为准。

POA 文件交换

POA（Proof of Address，地址证明）以预签名上传方式交换，不直接把文件传给开卡接口。三步：

调 POST /account/v1/generate-file-upload-prepare，请求体 { "fileNames": ["<your-file-name>"] }，获取每个文件的上传地址（预签名 URL）与 objectKey。
在您的服务端把 POA 文件 PUT 上传到返回的预签名 url。
把返回的 objectKey 作为 poaDocUrlList 的元素回传给开卡接口（或后续 KYC 补件接口）。

返回字段（data 数组每项）：fileName（原始文件名）、url（预签名上传地址）、objectKey（服务端文件对象键，回传用）。 上传示例（Java，占位预签名 URL，无 PII）：

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.FileEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import java.io.File;
import java.io.IOException;

class UploadPoa {
    public static void main(String[] args) throws IOException {
        String preUploadURL = "<PRESIGNED_UPLOAD_URL>";
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPut httpPut = new HttpPut(preUploadURL);

        File file = new File("<LOCAL_FILE_PATH>");
        httpPut.setEntity(new FileEntity(file));

        try (CloseableHttpResponse response = httpClient.execute(httpPut)) {
            if (response.getStatusLine().getStatusCode() == 200) {
                System.out.println(EntityUtils.toString(response.getEntity()));
            }
        }
    }
}

预签名 URL 接受的是 PUT 上传，请用 HttpPut。

申请实体卡（H5 引导页）

实体卡的申请、激活与设 PIN 全部通过 POST /redirect/v2/guidance-link 获取对应 H5 页面 URL，由前端打开引导用户完成，没有直连 API。引导页参数说明见 H5 引导页。

操作	`action`	说明
申请实体卡	`CREATE_PHYSICAL_CARD`	用户填写邮寄信息并提交申请；申请成功后实体卡处于「未激活」状态
激活实体卡	`ACTIVE_PHYSICAL_CARD`	用户收到卡后激活
设置/更新 PIN	`UPDATE_PIN`	激活后须设置 PIN 方可使用

申请实体卡流程（action=CREATE_PHYSICAL_CARD，用户在引导页内填写邮寄信息并提交）：

激活实体卡流程（action=ACTIVE_PHYSICAL_CARD，用户收到卡后在引导页内激活）：

PIN 的完整设置/更新说明见管理卡片 PIN，本页不重复展开。

实体卡的邮寄信息查询、卡状态等见卡管理 · 概述与实体卡寄送。

申请状态

虚拟卡申请状态（来源 /card/v1/apply-list 与申请响应的 status）：

状态	含义	终态
`PENDING`	申请中	否
`SUCCEED`	虚拟卡成功创建并激活	是
`FAILED`	任一环节失败导致的终态	是

DeCard 托管的卡申请终态为 SUCCEED / FAILED。

needExtraInfo

申请响应/记录中的 needExtraInfo 指示是否需要用户补充资料：

取值	含义与建议
`true`	用户尚未提交补充资料。请引导用户走 `POST /redirect/v2/guidance-link`，`action = KYC_EXTRA_DOC` 上传补件
`false`	用户已完成资料提交。此时即使 `status` 仍为 `PENDING`，也请等待审核，无需重复引导

查询申请状态

申请提交后，用以下两个接口持续查询申请与卡片状态。注意区分 applyId（申请单） 与 cardId（卡）。

接口	用途	关键参数 / 返回
`GET /card/v1/virtual-card/detail`	查单笔申请详情	query：`externalUserId` / `applyId` / `applyRef`；返回与申请响应同结构（含 `status` / `cardId` / `needExtraInfo` 等）
`GET /card/v1/apply-list`	查用户全部申请记录	query：`externalUserId`（必填）；列表项含 `applyId` / `cardId` / `categoryId` / `network` / `currency` / `status` / `errorCode` / `needExtraInfo`

卡状态（引用）

卡有两套状态枚举，集中在卡管理 · 概述定义，本页仅列出供参考，全站以《卡管理 · 概述》为准：

cardStatus（卡总体状态）：NORMAL（正常）/ FROZEN（冻结）/ CANCELLED（销户）
physicalCardStatus（实体卡状态）：UN_APPLY（未申请）/ INACTIVE（未激活）/ ACTIVE（已激活）/ REPLACE（换卡）/ FROZEN（冻结）/ CANCELLED（销户）

拿到卡之后

申请返回 status=SUCCEED 后，data.cardId 即可用；虚拟卡无需激活，开卡完成即为可用状态。
用 cardId 调 GET /card/v2/detail 查卡状态与关联余额（见卡管理 · 概述）。
需展示完整卡号 / CVV 时，引导终端用户走托管引导页（action=CARD_INFO），见查看卡敏感信息。
需要实体卡时，走 H5 引导页 CREATE_PHYSICAL_CARD → ACTIVE_PHYSICAL_CARD → UPDATE_PIN（见上文实体卡章节）。

下一步

kycInfo 各枚举字段取值（poaDocType / employmentStatus / occupation / sourceOfFunds 等）：见申请卡参数字典。
冻结/解冻、注销、换卡、卡状态机：见卡管理 · 概述。
设置 / 更新 PIN：见管理卡片 PIN。
把卡添加到 Apple / Google Wallet：见 Apple Pay 与 Google Pay 绑卡。
充值与消费授权：见用户余额。

​📄 概述

​前置条件

​两种申请方式

​申请流程总览

​申请虚拟卡

​方式一：H5 内嵌引导页

​H5 申请流程截图

​方式二：OPEN-API

​POA 文件交换

​申请实体卡（H5 引导页）

​申请状态

​needExtraInfo

​查询申请状态

​卡状态（引用）

​拿到卡之后

​下一步

📄 概述

前置条件

两种申请方式

申请流程总览

申请虚拟卡

方式一：H5 内嵌引导页

H5 申请流程截图

方式二：OPEN-API

POA 文件交换

申请实体卡（H5 引导页）

申请状态

needExtraInfo

查询申请状态

卡状态（引用）

拿到卡之后

下一步