变更概览
Create 路径仍为
POST /v1/virtual/accounts。
1. 更新 Create 请求
继续传入必填的x-idempotency-key，并按以下方式修改请求构造逻辑：
- 新增必填的两位国家代码
country。 currency只传一个三位币种代码。payment_method传LOCAL或SWIFT，或省略以评估两种方式。不要传ALL或AUTO。- 将
nickname作为可选字段处理。 - 移除该接口中依赖
x-request-id的逻辑。
x-on-behalf-of 中传入其账户 ID。请求结构详见 Create Virtual Account，有效值详见支持的参数组合。
网络失败后重试时，请为同一账户发送相同请求，并复用同一个 x-idempotency-key。任何申请输入发生变化时，都应使用新的 key。
2. 替换 Create 成功响应
将 HTTP200 解析为“申请已受理”，而不是“银行信息已可用”。
停止解析 message 和 request_id，改为：
- 将
data.account_id和data.direct_id与申请一起保存。 - 保存
data.application_id。 - 保存
data.public_version。 - 逐项处理
data.results[]，并通过payment_method识别。 - 只有当结果为
COMPLETED且具体记录为ACTIVE时，才使用银行信息。
payment_method 时，一项结果可能为 SKIPPED，另一项为 SUBMITTED。不要将申请顶层状态当成每种收款方式的状态。
3. 增加申请查询
为集成增加以下接口：- List Virtual Account Applications 用于查找和对账申请。
page_number和page_size必填。 - Retrieve Virtual Account Application 用于查询某个
application_id的最新完整详情。
4. 更新 Webhook 消费逻辑
处理全部三种申请事件：
保留现有的验签与响应确认流程，并将关联和顺序处理逻辑改为：
- 使用
event_id对投递去重。 - 使用
data.account_id将事件关联到对应账户；如适用，使用data.direct_id识别其主账户。 - 使用
data.application_id定位申请。 - 仅应用更高的
data.public_version。 - 应用事件后逐项处理全部结果。
- 发现版本缺口或疑似乱序时，调用 Retrieve 查询最新详情。
5. 区分请求错误与后续失败
Create 同步返回400 表示没有创建申请，后续也不会产生申请 Webhook。请修正请求或账户配置后再试。
HTTP 200 之后，某种收款方式仍可能变为 FAILED。此时请处理 virtual.account.update 事件，并使用 results[].error.code 决定后续操作。错误码和建议操作详见通过 API 集成虚拟账户。
Sandbox 验收清单
Production 上线前，请确认你的集成能够：- 发送一组受支持的
country和currency，并按需传入payment_method。 - 使用同一
x-idempotency-key重试相同请求，并保持一个application_id。 - 拒绝使用同一个 key 提交不同的申请输入。
- 解析 HTTP
200，并逐项处理results[]。 - 处理同一申请中一项
SKIPPED、另一项SUBMITTED的情况。 - 保存并比较
application_id + public_version。 - 查询申请列表和最新详情。
- 接受早于或晚于 Create 响应到达的
virtual.account.create。 - 使用
account_id和direct_id将申请事件关联到正确的账户。 - 在不依赖到达顺序的情况下应用
COMPLETED、FAILED和CLOSED数据。 - 只使用
ACTIVE银行信息，并在close_reason为空时仍停止使用CLOSED记录。 - Create 同步报错后停止等待 Webhook。