用户注册 · 概述

​

📄 正文

behavioral=REGISTER 表示本次发码用于注册场景（字段说明见步骤 1）。 DCS 为每个持卡人创建独立账户，拥有独立的可用 / 冻结余额。账户的状态与资产管理见 用户管理；这是 DeCard 托管 / 独立账户模型的入口。

​

前置条件

• 您已开通企业（Enterprise）账户，并持有 ApiKey / SecretKey。如尚未获取，请参考 前置准备 与 鉴权指南。
• 所有请求须按鉴权指南携带签名头。本页示例省略鉴权头，只聚焦业务字段。

​

步骤 1 · 发送验证码

​

手机号发码

POST /captcha/v1/send-mobile-code

{
  "mobileCode": "SG",
  "mobile": "91234567",
  "behavioral": "REGISTER"
}

​

邮箱发码

POST /captcha/v1/send-email-code

{
  "email": "user@example.com",
  "behavioral": "REGISTER"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": ""
}

messageDetail 为展示用结构（含 message/title/type/icon/action/linkTitle/linkUrl），通常为 null。响应结构的完整说明见 鉴权指南。

​

步骤 2 · 注册用户

POST /account/v1/register

{
  "mobileCode": "SG",
  "mobile": "91234567",
  "smsCode": "<短信验证码>"
}

{
  "email": "user@example.com",
  "emailCode": "<邮箱验证码>"
}

二选一规则：手机注册走 mobileCode + mobile + smsCode；邮箱注册走 email + emailCode。smsCode 与 emailCode 二选一，对应两种注册方式。

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": "usr_4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c"
}

​

手机号 / 邮箱加密传输（可选）

1. 使用 AES（对称加密）对手机号 / 邮箱明文加密，得到加密后的字节数组。
2. 将加密结果做 Base64 编码为字符串。
3. 将 Base64 字符串填入请求的 mobile 或 email 字段。

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 中可读到具体原因。当验证码过期或输入错误时，响应大致如下（结构不变）：
  {
    "code": "<业务错误码>",
    "message": "verification code expired or invalid",
    "messageDetail": null,
    "data": ""
  }
  

  以上 code / message 为示意占位，实际值以接口返回为准。响应结构始终为 {code, message, messageDetail, data}，错误信息出现在 message 字段。

• 验证码失效 / 输错：验证码有时效，过期或填错会导致 register 失败——重新调用对应发码接口（behavioral=REGISTER）获取新验证码后重试。
• 方式一致：注册方式须与发码方式一致——用手机号发的码只能用于手机号注册（smsCode），邮箱同理（emailCode）。
• 幂等：同一手机号 / 邮箱重复注册会失败；如不确定是否已注册，可在 用户管理 中查询用户状态。

​

下一步

• 注册得到 externalUserId 后，下一步通常是为用户完成 KYC——见 合规 · 概述。
• 管理用户账户状态与查看其资产，见 用户管理。
• 想一口气走完「注册 → 开卡 → 入金 → 消费」最短路径，见 快速开始。