跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
前置条件

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

​
实体类型

创建子账户时需指定实体类型：
实体类型说明
INDIVIDUAL面向个人的账户。仅在 BANKING 业务线下可用。
COMPANY企业实体。需提交随国家和业务线变化的附加证件。
对于 COMPANY 账户，在创建账户前调用 Get Additional Documents，获取目标国家和业务线下的必填与选填证件列表。

​
业务线

一个子账户可以在一条或多条业务线下入驻：
  • ACQUIRING — 受理卡支付与电子钱包支付
  • BANKING — 发起出款并管理全球账户
  • ISSUING — 发行并管理卡片

​
入驻流程

1

检查必需证件（仅 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 账户在创建时无需提交附加证件。
2

创建子账户

调用 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": "[email protected]",
      "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。
3

处理初始响应

账户不会立即激活。创建后：
  • status 为 PROCESSING — 账户已创建但尚不可用。
  • verification_status 为 PENDING — 身份验证或企业验证进行中。
妥善保存 account_id 供后续使用。无需轮询 — 请通过 Webhook 接收状态更新。
4

监听 Webhook 通知

UQPAY 会在账户进入验证流程后发送 Webhook 事件：
事件触发时机
onboarding.account.create账户创建完成、进入处理流程。
onboarding.account.update账户信息或状态发生变更。
在控制台配置你的 Webhook 端点。配置步骤参见 Webhook 设置。

​
账户状态生命周期

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

​
status

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

​
verification_status

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

​
下一步

关联账户

使用 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 参考。