> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 虚拟账户申请 Webhook

> 安全接收申请受理、更新和关闭事件。

Webhook 订阅版本为 `V1.5.1`、`V1.5.2` 或 `V1.6.0` 时，均可接收虚拟账户申请事件。

每个事件代表整笔申请。`source_id` 等于 `data.application_id`，`data` 包含该事件发生后的最新申请详情。事件不会按每种收款方式或每条银行信息分别发送。

使用 `data.account_id` 识别申请所属账户。如果它是关联账户，`data.direct_id` 表示其主账户；如果它就是主账户，`data.direct_id` 为 `"0"`。

> [!WARNING]
>
> `virtual.account.create` 只表示申请已受理并进入处理，不表示审批已完成或银行信息已可用。只能使用状态为 `ACTIVE` 的银行信息。

## 何时发送事件

| 事件类型 | 发送时机 | 处理方式 |
| - | - | - |
| `virtual.account.create` | 新申请受理后发送，`public_version` 初始值为 `1`。 | 保存申请，并继续跟踪状态为 `SUBMITTED` 的结果。 |
| `virtual.account.update` | 返回的申请数据发生变化，且申请尚未全部关闭时发送。 | 仅在 `public_version` 高于本地已存版本时应用事件，然后逐项处理全部结果。 |
| `virtual.account.closed` | 所有已开通虚拟账户均已关闭，且没有结果仍在处理中时发送。 | 应用 `CLOSED` 申请，并停止使用全部关联银行信息。 |

Create 响应和 `virtual.account.create` Webhook 可能以任意顺序到达，不要让其中一个等待另一个。

update 可能表示某种方式被跳过或失败、新银行信息已开通、申请部分完成或最终完成，也可能表示某条银行信息关闭。两种方式在同一次变化中完成时，只发送一条最终 update；分时完成时，先发送部分完成 update，再发送最终 update。

银行信息关闭后，请立即根据其 `status` 停止使用。关闭记录的 `close_reason` 仍可能为空。

## 何时不发送事件

以下情况不会发送申请 Webhook：

* Create 同步返回 `4xx`。
* 所有评估的收款方式均被拒绝，因而没有创建申请。
* 使用相同 `x-idempotency-key` 重放完全相同的请求。
* 处理仍在继续，但返回的申请数据没有变化。

需要主动获取最新数据时，请调用 [Retrieve Virtual Account Application](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/retrieve-virtual-account-application.md)。

## 安全处理事件

1. 使用原始 request body 和 `x-wk-timestamp` 验证 `x-wk-signature`。详见[签名验证](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-overview.md#signature-verification)。
2. 使用 `event_id` 对投递去重。同一事件重试时会复用该值。
3. 根据 `data.account_id` 将事件关联到对应账户；如适用，使用 `data.direct_id` 识别其主账户。
4. 使用 `data.application_id` 定位申请。
5. 仅当 `data.public_version` 高于该申请的本地已存版本时应用事件。
6. 逐项处理 `data.results[]`，并通过 `payment_method` 识别。
7. 发现投递缺口或疑似乱序时，查询最新申请详情。

即使申请之前已变为 `FAILED`，更高的 `public_version` 仍代表更新后的数据。

状态含义、错误处理和银行信息可用性规则详见[通过 API 集成虚拟账户](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/virtual-account-api-lifecycle.md)。


## OpenAPI

````yaml webhooks-banking.yaml webhook virtualAccountCreateUpdate
openapi: 3.1.0
info:
  title: Banking Webhooks
  version: 1.6.0
  description: |
    Webhook events for the Global Account product. UQPAY sends these events to
    your registered webhook endpoint as HTTP POST requests with a JSON body.

    All events share a common envelope (`event_id`, `event_name`, `event_type`,
    `source_id`, `version`) and carry event-specific data in the `data` field.
servers: []
security: []
paths: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.