账户入驻

如果你运营一个平台或市场，可以将下游商户或客户以子账户的形式入驻到你的 UQPAY 主账户下。每个子账户拥有独立的身份、验证状态和 UQPAY 产品访问权限。你通过 API 管理这些子账户，并在账户激活后代表它们进行操作。

前置条件

开始之前，请确认你已准备好：

一个可用的沙盒账户
API 密钥（x-client-id 与 x-api-key）

实体类型

创建子账户时需指定实体类型：

实体类型	说明
`INDIVIDUAL`	面向个人的账户。仅在 `BANKING` 业务线下可用。
`COMPANY`	企业实体。需提交随国家和业务线变化的附加证件。

对于 COMPANY 账户，在创建账户前调用 Get Additional Documents，获取目标国家和业务线下的必填与选填证件列表。

业务线

一个子账户可以在一条或多条业务线下入驻：

ACQUIRING — 受理卡支付与电子钱包支付
BANKING — 发起出款并管理全球账户
ISSUING — 发行并管理卡片

入驻流程

检查必需证件（仅 COMPANY）

如果你要入驻的是 COMPANY 实体，调用 Get Additional Documents，获取目标国家和业务线下必填与选填的证件类型列表。

curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts/get_additional?country=SG&business_code=BANKING" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN"

本步骤仅适用于 COMPANY 实体。INDIVIDUAL 账户在创建时无需提交附加证件。

创建子账户

调用 Create SubAccount 并传入实体资料、业务线和实体类型。

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/accounts/create_accounts" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "INDIVIDUAL",
    "nickname": "John Doe",
    "individual_info": {
      "first_name_english": "John",
      "last_name_english": "Doe",
      "nationality": "SG",
      "phone_number": "+6591234567",
      "email_address": "john.doe@example.com",
      "date_of_birth": "1990-01-15",
      "country_or_territory": "SG",
      "street_address": "1 Raffles Place",
      "city": "Singapore",
      "state": "Singapore",
      "postal_code": "048616",
      "employment_status": "Employed",
      "industry": "Information Technology/IT",
      "job_title": "Business and administration professionals",
      "company_name": "Acme Corp."
    },
    "identity_verification": {
      "identification_type": "PASSPORT",
      "identification_value": "E12345678",
      "identity_docs": ["<BASE64_ENCODED_DOCUMENT>"]
    },
    "expected_activity": {
      "account_purpose": ["PURCHASE"],
      "banking_countries": ["SG"],
      "banking_currencies": ["SGD"],
      "internationally": 1,
      "turnover_monthly": "TM001",
      "turnover_monthly_currency": "USD"
    },
    "proof_documents": {
      "proof_of_address": ["<BASE64_ENCODED_DOCUMENT>"]
    },
    "tos_acceptance": {
      "ip": "203.0.113.42",
      "date": "2026-04-15",
      "user_agent": "Mozilla/5.0"
    }
  }'

成功响应会返回新账户的详情：

{
  "account_id": "7ec16ed4-2efc-4dec-9752-29ab32d6d921",
  "short_reference_id": "CB9221063168",
  "status": "PROCESSING",
  "verification_status": "PENDING"
}

响应中的关键字段：

字段	说明
`account_id`	子账户的唯一标识。后续 API 调用中使用此值。
`short_reference_id`	可读的业务编号，例如 `P220406-LLCVLRM`。
`status`	初始值为 `PROCESSING`。
`verification_status`	初始值为 `PENDING`。

处理初始响应

账户不会立即激活。创建后：

status 为 PROCESSING — 账户已创建但尚不可用。
verification_status 为 PENDING — 身份验证或企业验证进行中。

妥善保存 account_id 供后续使用。无需轮询 — 请通过 Webhook 接收状态更新。

监听 Webhook 通知

UQPAY 会在账户进入验证流程后发送 Webhook 事件：

事件	触发时机
`onboarding.account.create`	账户创建完成、进入处理流程。
`onboarding.account.update`	账户信息或状态发生变更。

在控制台配置你的 Webhook 端点。配置步骤参见 Webhook 设置。

账户状态生命周期

账户创建之后，子账户会沿两条并行的状态维度推进：

`status`

跟踪账户是否可用：

值	含义
`PROCESSING`	账户已创建、审核中。尚不可用。
`ACTIVE`	验证已通过。账户可正常使用。
`INACTIVE`	账户存在但当前已停用。
`CLOSED`	账户已永久关闭。

`verification_status`

跟踪身份验证或企业验证的结果：

值	含义
`PENDING`	验证尚未完成。
`APPROVED`	验证通过。账户进入 `ACTIVE` 状态。
`REJECT`	验证失败。账户无法激活。
`RETURN`	提交材料被退回，需按要求修正并重新提交。
`EXPIRED`	验证窗口期已过，未完成提交。

accountStatus webhook 对拒绝和退回状态下发的是 REJECTED 和 RETURNED（而非 REJECT / RETURN）。详见 Account Status webhook。

下一步

关联账户

使用 x-on-behalf-of header 代表子账户发起 API 请求。

Create SubAccount API

Create SubAccount 接口的完整参数说明。

Get Additional Documents API

按国家与业务线获取 COMPANY 入驻所需的证件列表。

Account Status webhook

onboarding.account.create 与 onboarding.account.update 的事件 payload 参考。

入门

认证

账户管理

Webhooks

参考

前置条件

实体类型

业务线

入驻流程

账户状态生命周期

`status`

`verification_status`

下一步

关联账户

Create SubAccount API

Get Additional Documents API

Account Status webhook

​前置条件

​实体类型

​业务线

​入驻流程

​账户状态生命周期

​status

​verification_status

​下一步

关联账户

Create SubAccount API

Get Additional Documents API

Account Status webhook

前置条件

实体类型

业务线

入驻流程

账户状态生命周期

`status`

`verification_status`

下一步