生命周期概览
前置条件
通过 API 创建虚拟账户前，请先确认：- 已完成所需的入驻流程，并为目标账户启用 Global Account 产品。
- 已确认该账户支持所请求的币种和收款方式。参见支持的地区与币种。
- 已决定虚拟账户属于主账户还是子账户。如果为子账户创建虚拟账户，请在
x-on-behalf-of请求头中传入该子账户的account_id。 - 已配置并测试虚拟账户创建 / 更新 Webhook，再发送生产环境创建请求。
- 每次创建请求都生成唯一的
x-idempotency-key。如果同时传入x-request-id，请保存该值，因为它会在虚拟账户 Webhook 的request_id中返回。
步骤 1：提交创建请求
为应接收该虚拟账户的账户调用 Create Virtual Account。
接口响应中的
message = SUCCESS 表示请求已被受理并进入处理流程。它不表示虚拟账户已经开通完成，也不应在此时向付款人展示付款指引。
步骤 2：通过 Webhook 跟踪开通状态
虚拟账户创建会通过虚拟账户创建 / 更新 Webhook 异步完成。
Webhook payload 中包含以下应保存的标识：
步骤 3：查询可用虚拟账户
收到 Active Webhook 后、服务启动时，或需要刷新已保存账户信息时，调用 List Virtual Accounts。 你可以按currency 筛选。查询子账户时，请传入与创建或代该子账户操作时相同的 x-on-behalf-of 值。
请在你的系统中保存返回的信息：
Webhook 状态值和 List API 状态值的大小写不同。例如 Webhook 可能发送
Active，而 List API 可能返回 ACTIVE。请在你的系统中先统一状态值，再执行业务判断。步骤 4：使用正确的收款能力
每条返回的虚拟银行账户信息都有对应收款能力。请根据预期支付通道展示匹配的付款指引。
如果某个币种同时支持本地收款和 SWIFT 收款，请将每条返回的银行账户信息视为独立记录。你应向付款人展示与预期收款能力匹配的指引。
步骤 5：将充值与虚拟账户对账
虚拟账户用于标识资金应汇入哪里。充值 是资金到达并被处理后生成的交易记录。 对账时：- 虚拟账户激活后，保存账户映射关系。
- 监听充值状态 Webhook 事件。
- 如果是子账户充值，使用 Webhook 中的
account_id作为x-on-behalf-of查询充值详情。 - 使用
deposit_id调用 Retrieve Deposit。 - 使用充值详情中的
receiver_account_number、currency和所属account_id匹配到你的虚拟账户映射。可在有值时结合付款人信息和deposit_reference做辅助对账。