> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 申请卡（虚拟卡与实体卡）
> 讲为已通过 KYC 的用户申请虚拟卡（H5 引导页 / OPEN-API 两种方式）与实体卡（仅 H5 引导页），含 POA 文件交换、申请状态查询与拿到卡之后的动作。
## 📄 概述
用户完成 KYC 后，您即可通过一次 API 调用为其发行虚拟卡，供其立即用于线上消费，并按需进一步申请实体卡。作为持牌、自有 BIN 的发卡机构，DCS 承接发卡、KYC 审核、授权决策与清算；您只需关心如何提交申请、如何查状态、拿到卡之后做什么。
DCS 支持两种卡介质：
* **虚拟卡**：无实体介质，申请通过即自动激活，可立即用于线上消费。
* **实体卡**：需邮寄给用户，**收到后须激活并设置 PIN** 方可使用。
> 虚拟卡按使用形态又分两类：**一次性虚拟卡**（单次交易后即失效，安全性最高，适合一次性支付）与**可重复使用虚拟卡**（在卡片有效期内可多次使用，通常可设单笔 / 总消费额度）。两者均不能直接用于线下实体店刷卡或 ATM 取现。具体哪类由卡产品（`categoryId`）决定，开卡前请向 DCS 确认。
### 前置条件
* 用户已注册并创建账户（见 [用户注册](../signing-up-a-customer/overview)）。
* KYC 资料齐备：Sumsub `shareToken`、必要的 POA 文件与就业/资金来源信息。
### 两种申请方式
两种申请方式并存，二选一：
| 方式 | 适用 | 入口 |
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------ |
| **H5 内嵌引导页** | 希望复用 DCS 现成 KYC/开卡 UI，少写前端 | `POST /redirect/v2/guidance-link`（见 [H5 引导页](../../integration-resources/h5-kyc-guidance)） |
| **OPEN-API** | 自管前端、自行采集 KYC 资料 | `POST /card/v1/virtual-card/apply`（仅虚拟卡） |
**实体卡在 DeCard 托管侧没有独立的「申请实体卡」直连 API**。实体卡的**申请、激活、设 PIN 全部通过 H5 引导页完成**（见下文实体卡章节），不存在 `physical-card/apply` 或「虚拟卡转实体卡」直连接口。
### 申请流程总览
OPEN-API 方式的主流程只有两步——提交申请，然后轮询到终态（也可通过 Webhook 接收结果）：
> **如需随申请补交 POA 文件**，在提交申请前先完成三步：
>
> 1. 调 `POST /account/v1/generate-file-upload-prepare` 获取预上传 URL 与 `objectKey`；
> 2. 用返回的 URL 直接 `PUT` 上传 POA 文件；
> 3. 将 `objectKey` 填入申请请求的 POA 字段（见下方字段表）。
***
## 申请虚拟卡
### 方式一：H5 内嵌引导页
调用 `POST /redirect/v2/guidance-link`，`action` 传 `KYC_GUIDE`，获取一段引导页 URL；在前端打开后由 DCS 引导用户完成 KYC + 开卡。引导页参数与渲染说明见 [H5 引导页](../../integration-resources/h5-kyc-guidance)。
#### 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 天内**）。完整取值见 [申请卡参数字典](./application-data-dictionary#地址证明文件类型（poadoctype）) | 最大 50 |
| `kycInfo.poaDocUrlList` | string\[] | POA 场景 | POA 文件 URL 列表（见 [POA 文件交换](#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 用） | |
上表字段长度供参考；实际接入时请以接口返回的校验错误信息为准，不要沿用其他方案的字段长度。
**请求示例**（占位/脱敏）：
```json theme={null}
{
"externalUserId": "",
"categoryId": 1001,
"applyRef": "",
"kycInfo": {
"sumsubShareToken": "",
"email": "user@example.com",
"poaDocType": "BANK_STATEMENT",
"poaDocUrlList": [""],
"poaDocDate": "",
"addressLine1": "",
"city": "",
"postalCode": "",
"country": "SG",
"employmentStatus": "EMPLOYED",
"employerName": "",
"employmentJobIndustry": "",
"occupation": "",
"jobSeniority": "",
"purposeOfAccount": "",
"sourceOfFunds": "",
"sourceOfFundsCountry": "SG",
"sourceOfWealth": ""
}
}
```
**响应字段**（`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](#needextrainfo) |
| `remark` | string | 备注 |
**成功响应示例**（脱敏）：
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "SUCCESS",
"messageDetail": null,
"data": {
"applyId": "",
"cardId": "",
"categoryId": 1001,
"applyRef": "",
"status": "SUCCEED",
"needEddFile": false,
"needExtraInfo": false,
"remark": null
}
}
```
**失败响应示例**（脱敏）：
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "SUCCESS",
"messageDetail": null,
"data": {
"applyId": "",
"status": "FAILED",
"errorCode": "",
"errorReason": "<失败原因描述>",
"needEddFile": false,
"needExtraInfo": false
}
}
```
响应结构统一为 `{ code, message, messageDetail, data }`（无 `success` 布尔字段）。`code = SYS_SUCCESS` 仅表示请求被成功受理，**业务结果以 `data.status` 为准**。
***
## POA 文件交换
POA（Proof of Address，地址证明）以**预签名上传**方式交换，不直接把文件传给开卡接口。三步：
1. 调 `POST /account/v1/generate-file-upload-prepare`，请求体 `{ "fileNames": [""] }`，获取每个文件的上传地址（预签名 URL）与 `objectKey`。
2. 在您的服务端把 POA 文件 **PUT 上传**到返回的预签名 `url`。
3. 把返回的 `objectKey` 作为 `poaDocUrlList` 的元素回传给开卡接口（或后续 KYC 补件接口）。
返回字段（`data` 数组每项）：`fileName`（原始文件名）、`url`（预签名上传地址）、`objectKey`（服务端文件对象键，回传用）。
**上传示例**（Java，占位预签名 URL，无 PII）：
```java theme={null}
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 = "";
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpPut httpPut = new HttpPut(preUploadURL);
File file = new File("");
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 引导页](../../integration-resources/h5-kyc-guidance)。
| 操作 | `action` | 说明 |
| --------- | ---------------------- | ------------------------------- |
| 申请实体卡 | `CREATE_PHYSICAL_CARD` | 用户填写邮寄信息并提交申请；申请成功后实体卡处于「未激活」状态 |
| 激活实体卡 | `ACTIVE_PHYSICAL_CARD` | 用户收到卡后激活 |
| 设置/更新 PIN | `UPDATE_PIN` | 激活后须设置 PIN 方可使用 |
**申请实体卡流程**（`action=CREATE_PHYSICAL_CARD`，用户在引导页内填写邮寄信息并提交）：
**激活实体卡流程**（`action=ACTIVE_PHYSICAL_CARD`，用户收到卡后在引导页内激活）：
> PIN 的完整设置/更新说明见 [管理卡片 PIN](./managing-a-cards-pin)，本页不重复展开。
> 实体卡的邮寄信息查询、卡状态等见 [卡管理 · 概述](./overview) 与 [实体卡寄送](../../customer-success/physical-card-shipping)。
***
## 申请状态
虚拟卡申请状态（来源 `/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` |
***
## 卡状态（引用）
卡有两套状态枚举，集中在 [卡管理 · 概述](./overview) 定义，本页仅列出供参考，**全站以《卡管理 · 概述》为准**：
* **`cardStatus`**（卡总体状态）：`NORMAL`（正常）/ `FROZEN`（冻结）/ `CANCELLED`（销户）
* **`physicalCardStatus`**（实体卡状态）：`UN_APPLY`（未申请）/ `INACTIVE`（未激活）/ `ACTIVE`（已激活）/ `REPLACE`（换卡）/ `FROZEN`（冻结）/ `CANCELLED`（销户）
***
## 拿到卡之后
1. 申请返回 `status=SUCCEED` 后，`data.cardId` 即可用；**虚拟卡无需激活，开卡完成即为可用状态**。
2. 用 `cardId` 调 `GET /card/v2/detail` 查卡状态与关联余额（见 [卡管理 · 概述](./overview)）。
3. 需展示完整卡号 / CVV 时，引导终端用户走托管引导页（`action=CARD_INFO`），见 [查看卡敏感信息](./viewing-encrypted-card-details)。
4. 需要实体卡时，走 H5 引导页 `CREATE_PHYSICAL_CARD → ACTIVE_PHYSICAL_CARD → UPDATE_PIN`（见上文实体卡章节）。
## 下一步
* `kycInfo` 各枚举字段取值（poaDocType / employmentStatus / occupation / sourceOfFunds 等）：见 [申请卡参数字典](./application-data-dictionary)。
* 冻结/解冻、注销、换卡、卡状态机：见 [卡管理 · 概述](./overview)。
* 设置 / 更新 PIN：见 [管理卡片 PIN](./managing-a-cards-pin)。
* 把卡添加到 Apple / Google Wallet：见 [Apple Pay 与 Google Pay 绑卡](./push-provisioning)。
* 充值与消费授权：见 [用户余额](../managing-transactions/user-balance)。