Skip to main content
一笔虚拟账户申请，是针对一个国家和一个币种发起的一次银行信息申请。它可以包含 LOCAL、SWIFT 或两种收款方式的结果。
如果已有虚拟账户集成，请先阅读升级虚拟账户 API 集成。
Create 返回 HTTP 200 表示申请已受理并进入处理，不表示银行信息已经可用。只能使用状态为 ACTIVE 的银行信息。

​
开始前

  • 完成入驻，并为目标账户启用 Global Account。
  • 配置虚拟账户申请 Webhook。
  • 如果操作子账户，请在 Create、List 和 Retrieve 的 x-on-behalf-of 中传入其账户 ID。
  • 为每笔新申请生成唯一的 x-idempotency-key。

​
选择申请参数

选择国家和币种，查看支持的收款方式。生成的 JSON 可用于 Create Virtual Account。
以下列表包含传入 payment_method 时支持的全部组合。省略 payment_method 时，UQPAY 会针对所选国家和币种分别评估 LOCAL 和 SWIFT。
只申请一种收款方式时，传 LOCAL 或 SWIFT。如需评估两种方式，可以省略 payment_method，或传 null、空字符串、仅空白字符。不要传 ALL 或 AUTO。

​
创建申请

使用一个 country 和一个 currency 调用 Create Virtual Account。 UQPAY 会去除 country、currency 和 payment_method 首尾的空格，并接受小写值。nickname 省略、为 null、为空或仅包含空白字符时按相同方式处理。未定义的 JSON 字段会被忽略。 仅在为同一账户重试相同请求时复用 x-idempotency-key。相同请求重试成功时会返回原申请；使用同一 key 提交不同的申请输入会返回 parameter_conflict。 收到 HTTP 200 后：
  1. 将 account_id 和 direct_id 与申请一起保存，以保留其账户层级。
  2. 保存 application_id 和 public_version。
  3. 逐项处理 results[]，并通过 payment_method 识别。
  4. 继续跟踪状态为 SUBMITTED 的结果。
  5. 在具体银行信息变为 ACTIVE 前，不要展示付款指引。
评估两种方式时，LOCAL 排在 SWIFT 之前，但代码不得依赖数组位置。一种方式可能为 SKIPPED，另一种为 SUBMITTED。 同步 400 表示没有创建申请，不要等待申请 Webhook。所有评估方式都不可用时，Create 会返回一个顶层错误，不会创建只有跳过结果的申请。

​
跟踪申请

两个查询接口用途不同：
  • List Virtual Account Applications 用于查找申请摘要。结果按从新到旧排列；可选的 status、country 和 currency 筛选条件会同时生效。结果为空或页码超出范围时，返回 HTTP 200 和 data: []。
  • Retrieve Virtual Account Application 用于查询一笔申请的最新完整详情。申请不存在和申请属于其他账户时，均返回相同的 HTTP 400 错误。
两个接口都会返回 account_id 和 direct_id。请使用它们将每笔申请关联到正确的账户层级。 使用虚拟账户申请 Webhook接收异步变化。如果投递缺失或疑似乱序，请调用 Retrieve，并为同一个 application_id 保留最高的 public_version。

​
区分三层状态

​
处理错误

接口参数校验和业务错误包含 type、code 和 message。程序处理应使用 code。在接口处理请求前返回的鉴权等错误，可能使用网关公共错误格式。 收款方式被跳过或失败时，results[].error 包含 code 和 message；没有错误时为 null。

​
使用已开通的银行信息

结果变为 COMPLETED 后，逐项处理 virtual_accounts[]：
  • 只使用 status 为 ACTIVE 的记录。
  • 将 account_bank_id 视为不透明字符串，并按原值保存，用于关联同一记录的后续变化。
  • 按返回值原样展示 account_holder、account_number、bank_name、bank_address、country_code 和 currency。
  • 成对保存 clearing_system.type 和 clearing_system.value，并保留原值。
  • 记录变为 CLOSED 后立即停止使用。
close_reason 始终存在。记录未关闭时为 ""；记录关闭后，如系统已记录原因则返回该值，否则仍为 ""。不要等待该字段变为非空才停止使用。 服务启动或进行对账时，可使用 List Virtual Accounts 刷新已开通的银行信息。该既有接口列出银行信息，不列出申请。

​
对账入账资金

虚拟账户用于提供付款指引。充值 是资金到账后创建的交易记录。
  1. 银行信息激活后，保存虚拟账户与所属账户的映射。
  2. 监听充值状态事件。
  3. 如果是子账户充值，请使用 Webhook 中的 account_id 作为 x-on-behalf-of 查询充值详情。
  4. 调用 Retrieve Deposit。
  5. 使用 receiver_account_number、currency 和所属 account_id 匹配充值记录；付款人信息和 deposit_reference 可在有值时作为辅助信号。