> ## 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.
# 用户注册 · 概述
> 讲 DeCard 托管模式下终端用户的两步注册流程：先请求验证码（手机/邮箱），再凭 OTP 注册得到 externalUserId，含发码/注册接口、字段、加密传输与错误重发。
## 📄 正文
在 DeCard 托管模式下，**先有用户、再有卡**：终端用户必须先注册得到一个 `externalUserId`，后续的 KYC、开卡、充值、消费、查余额等所有接口都以它标识该用户。作为持牌、自有 BIN 的发卡机构，DCS 为每个持卡人创建一个独立账户，通过「手机号 / 邮箱 + 一次性验证码（OTP）」完成注册。
注册是一个**两步流程**——先请求验证码，再凭验证码注册：
> `behavioral=REGISTER` 表示本次发码用于注册场景（字段说明见步骤 1）。
>
> DCS 为每个持卡人创建**独立账户**，拥有独立的可用 / 冻结余额。账户的状态与资产管理见 [用户管理](../managing-users/overview)；这是 DeCard 托管 / 独立账户模型的入口。
## 前置条件
* 您已开通企业（Enterprise）账户，并持有 `ApiKey` / `SecretKey`。如尚未获取，请参考 [前置准备](../../getting-started/first-steps) 与 [鉴权指南](../../integration-resources/overview)。
* 所有请求须按鉴权指南携带签名头。本页示例省略鉴权头，只聚焦业务字段。
## 步骤 1 · 发送验证码
按注册方式二选一调用发码接口。两个接口的**唯一必填字段都是 `behavioral`**，注册场景固定传 `REGISTER`。
| 注册方式 | 接口 |
| ----- | ----------------------------------- |
| 手机号注册 | `POST /captcha/v1/send-mobile-code` |
| 邮箱注册 | `POST /captcha/v1/send-email-code` |
### 手机号发码
```
POST /captcha/v1/send-mobile-code
```
```json theme={null}
{
"mobileCode": "SG",
"mobile": "91234567",
"behavioral": "REGISTER"
}
```
| 字段 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ----- | ----------------------------------------------------------------------------------------------------- |
| `behavioral` | string | **是** | 行为场景枚举：`REGISTER`（注册）/ `CARD_UNFROZEN`（解冻卡）/ `WITHDRAW`（提现）。注册场景传 `REGISTER` |
| `mobileCode` | string | 二选一 | 手机国家码，使用 ISO 字母码，如 `CN`、`US`、`SG` |
| `mobile` | string | 二选一 | 手机号（不带区号），**支持 AES 加密或明文传输**（见下方加密说明） |
| `externalUserId` | string | 二选一 | 用户 ID。注册新用户尚无 `externalUserId`，故留空、改传 `mobileCode` + `mobile`；已有用户的其他场景（如解冻 / 提现）可改传 `externalUserId` |
### 邮箱发码
```
POST /captcha/v1/send-email-code
```
```json theme={null}
{
"email": "user@example.com",
"behavioral": "REGISTER"
}
```
| 字段 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ----- | ---------------------------------------------------------------------------- |
| `behavioral` | string | **是** | 行为场景枚举：`REGISTER`（注册）/ `CARD_UNFROZEN`（解冻卡）/ `WITHDRAW`（提现）。注册场景传 `REGISTER` |
| `email` | string | 二选一 | 邮箱地址，**支持 AES 加密或明文传输** |
| `externalUserId` | string | 二选一 | 用户 ID。注册时留空、改传 `email`；已有用户可改传 `externalUserId` |
发码接口的成功响应（结构为全站统一的 `{code, message, messageDetail, data}`，无 `success` 布尔字段；成功码 `code = SYS_SUCCESS`）：
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": ""
}
```
> `messageDetail` 为展示用结构（含 `message`/`title`/`type`/`icon`/`action`/`linkTitle`/`linkUrl`），通常为 `null`。响应结构的完整说明见 [鉴权指南](../../integration-resources/overview)。
## 步骤 2 · 注册用户
凭步骤 1 收到的验证码调用注册接口。注意 `register` 接口**不含 `behavioral`**——该字段只属于发码接口，请勿混用。
```
POST /account/v1/register
```
手机号注册：
```json theme={null}
{
"mobileCode": "SG",
"mobile": "91234567",
"smsCode": "<短信验证码>"
}
```
邮箱注册：
```json theme={null}
{
"email": "user@example.com",
"emailCode": "<邮箱验证码>"
}
```
| 字段 | 类型 | 必填规则 | 说明 |
| ------------ | ------ | ------- | ------------------------ |
| `mobileCode` | string | 手机注册时必填 | 手机国家码，如 `CN`、`US`、`SG` |
| `mobile` | string | 手机注册时必填 | 手机号（不带区号），支持 AES 加密 / 明文 |
| `smsCode` | string | 手机注册时必填 | 短信验证码 |
| `email` | string | 邮箱注册时必填 | 邮箱地址，支持 AES 加密 / 明文 |
| `emailCode` | string | 邮箱注册时必填 | 邮箱验证码 |
> **二选一规则**：手机注册走 `mobileCode + mobile + smsCode`；邮箱注册走 `email + emailCode`。`smsCode` 与 `emailCode` 二选一，对应两种注册方式。
成功响应的 `data` 字段即**系统生成的 `externalUserId`**，后续所有接口以它标识该用户：
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": "usr_4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c"
}
```
## 手机号 / 邮箱加密传输（可选）
`mobile` 与 `email` 字段**支持 AES 加密或明文传输**，接入机构可按需选择。如使用加密：
1. 使用 AES（对称加密）对手机号 / 邮箱**明文**加密，得到加密后的字节数组。
2. 将加密结果做 **Base64 编码**为字符串。
3. 将 Base64 字符串填入请求的 `mobile` 或 `email` 字段。
以下为 Java 示例（密钥为占位，请替换为您与 DCS 约定的密钥）：
```java theme={null}
import cn.hutool.core.codec.Base64;
import cn.hutool.crypto.SecureUtil;
public class AES {
private static final String SECRET = "YOUR_AES_SECRET_KEY"; // 占位，勿提交真实密钥
public static void main(String[] args) {
String mobile = "91234567";
String encryptedMobile = SecureUtil.aes(Base64.decode(SECRET)).encryptBase64(mobile);
String email = "user@example.com";
String encryptedEmail = SecureUtil.aes(Base64.decode(SECRET)).encryptBase64(email);
}
}
```
> 示例中的手机号、邮箱、密钥均为占位 / 脱敏值。**请勿在请求或日志中写入真实终端用户 PII 或真实密钥。**
## 错误处理与重发
* **成功判定**：以响应结构 `code == SYS_SUCCESS` 判断请求是否成功受理；非该值时读取 `message` / `messageDetail` 了解原因。
* **典型错误响应**：失败时 `code` 即该错误对应的**具体业务错误码**（不存在通用失败码），`message` 中可读到具体原因。当验证码过期或输入错误时，响应大致如下（结构不变）：
```json theme={null}
{
"code": "<业务错误码>",
"message": "verification code expired or invalid",
"messageDetail": null,
"data": ""
}
```
> 以上 `code` / `message` 为示意占位，实际值以接口返回为准。响应结构始终为 `{code, message, messageDetail, data}`，错误信息出现在 `message` 字段。
* **验证码失效 / 输错**：验证码有时效，过期或填错会导致 `register` 失败——重新调用对应发码接口（`behavioral=REGISTER`）获取新验证码后重试。
* **方式一致**：注册方式须与发码方式一致——用手机号发的码只能用于手机号注册（`smsCode`），邮箱同理（`emailCode`）。
* **幂等**：同一手机号 / 邮箱重复注册会失败；如不确定是否已注册，可在 [用户管理](../managing-users/overview) 中查询用户状态。
## 下一步
* 注册得到 `externalUserId` 后，下一步通常是为用户完成 KYC——见 [合规 · 概述](../../basic-concepts/compliance-kyc-flow)。
* 管理用户账户状态与查看其资产，见 [用户管理](../managing-users/overview)。
* 想一口气走完「注册 → 开卡 → 入金 → 消费」最短路径，见 [快速开始](../../getting-started/quickstart)。