> For the complete documentation index, see [llms.txt](https://docs.topay.mobi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.topay.mobi/cn/integration/webhook.md).

# Webhook 通知

### 配置 <a href="#setting-up" id="setting-up"></a>

配置 Webhook 后，您可以接收订单状态更新通知，包括收款、付款交易及交易状态变更等事件。Webhook 地址可在以下位置设置：

<figure><img src="https://708501463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5CoqhFwqwkrLal2C588B%2Fuploads%2Fgit-blob-a0da52d0beba279bf954af00eeeccb9467005a66%2Fimage%20(7).png?alt=media" alt=""><figcaption></figcaption></figure>

配置 Webhook 地址后，您将开始接收订单事件通知。所有事件均附带以下签名。

* **sign** = Base64(*RSA*(PLATFORM\_PRIVATE\_KEY, SHA1(msgBody))

用于验签的公钥可在以下位置获取：

<figure><img src="https://708501463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5CoqhFwqwkrLal2C588B%2Fuploads%2Fgit-blob-7c02cd6b0d01570b201a34477d293ca2c5c06150%2Fimage%20(8).png?alt=media" alt=""><figcaption></figcaption></figure>

### 数据对象 <a href="#data-objects" id="data-objects"></a>

#### 通知体 <a href="#notify-body" id="notify-body"></a>

<table><thead><tr><th width="193.66666666666666">参数</th><th width="118">类型</th><th>说明</th></tr></thead><tbody><tr><td>partner_id</td><td>String</td><td>Topay 分配给您的账户 ID。</td></tr><tr><td>order_no</td><td>String</td><td>交易 ID。</td></tr><tr><td>request_id</td><td>String</td><td>商户提供的外部交易 ID。</td></tr><tr><td>order_type</td><td>String</td><td>交易类型，参阅<a data-mention href="/cn/reference/enums/order-type.md">订单类型</a>。</td></tr><tr><td>product_code</td><td>String</td><td>交易子类型。</td></tr><tr><td>currency</td><td>String</td><td>交易对应的币种。</td></tr><tr><td>order_amount</td><td>String</td><td>请求金额。</td></tr><tr><td>pay_amount</td><td>String</td><td>实际付款金额，通常等于 order_amount</td></tr><tr><td>fee_amount</td><td>String</td><td>基于 pay_amount 计算的服务费金额</td></tr><tr><td>actual_amount</td><td>String</td><td>实际入账金额，即 pay_amount 减去 fee_amount。</td></tr><tr><td>finish_time</td><td>String</td><td>交易完成时间。</td></tr><tr><td>status</td><td>Number</td><td>交易状态，参阅<a data-mention href="/cn/reference/enums/order-status.md">订单状态</a>。</td></tr><tr><td>reason</td><td>String</td><td>交易失败原因。</td></tr><tr><td>sign</td><td>String</td><td>Base64 编码的签名字符串。</td></tr><tr><td>extra_info</td><td>JSON String</td><td>JSON 字符串；字段按数字货币支付和法币支付区分，参阅下方扩展信息。</td></tr></tbody></table>

#### 扩展信息 <a href="#extra-info" id="extra-info"></a>

`extra_info` 是 JSON 字符串，其内部字段取决于业务类型。读取通知后，需要单独解析该字符串以获取扩展字段。

**数字货币支付（Crypto Payments）**

<table><thead><tr><th width="200">参数</th><th width="120">类型</th><th>说明</th></tr></thead><tbody><tr><td>description</td><td>String</td><td>请求中的扩展信息。</td></tr><tr><td>txnHash</td><td>String</td><td>交易的区块链哈希</td></tr><tr><td>customerRefId</td><td>String</td><td>商户用于将资金所有者（客户）与交易关联的 ID</td></tr><tr><td>blockHeight</td><td>Number</td><td>交易所在区块的高度（编号）</td></tr><tr><td>numOfConfirms</td><td>Number</td><td>交易确认数。该数值会持续增加，直到交易达到确认策略要求并被视为完成。</td></tr><tr><td>networkFee</td><td>String</td><td>支付给区块链网络的手续费</td></tr><tr><td>sourceAddress</td><td>String</td><td>交易来源地址</td></tr><tr><td>destinationAddress</td><td>String</td><td>资产转入的目标地址</td></tr><tr><td>destinationTag</td><td>String</td><td>XRP 的目标 tag；EOS/XLM 中用作 memo</td></tr><tr><td>fiatAmount</td><td>String</td><td>对应的法币金额</td></tr><tr><td>fiatCurrency</td><td>String</td><td>对应的法币币种</td></tr><tr><td>exchangeRate</td><td>String</td><td>支付币种与法币之间的汇率</td></tr></tbody></table>

**法币支付（Fiat Payments）**

法币支付的 `extra_info` 可能包含以下字段，具体以实际通知为准；并非每次通知都会返回全部字段。账号、手机号码和证件号码均为字符串，解析时请保留前导零。

| 参数                         | 类型     | 说明                         |
| -------------------------- | ------ | -------------------------- |
| `beneficiaryAccountNumber` | String | 收款人账号。                     |
| `beneficiaryAccountType`   | String | 收款人账户类型，例如 `PHONE`。        |
| `beneficiaryEmail`         | String | 收款人电子邮箱。                   |
| `beneficiaryName`          | String | 收款人姓名。                     |
| `beneficiaryPhone`         | String | 收款人手机号码。                   |
| `beneficiaryWallet`        | String | 收款人钱包代码，例如 `jazzcash`。     |
| `channel`                  | String | 渠道信息，可能为空字符串。              |
| `country`                  | String | 国家代码，例如 `PK`。              |
| `documentId`               | String | 身份证件号码。                    |
| `payType`                  | String | 支付类型，例如 `wallet_transfer`。 |

以下为法币钱包代付通知中的 `extra_info` 片段，客户信息仅为虚构示例：

```json
{
  "extra_info": "{\"beneficiaryAccountNumber\":\"03000000000\",\"beneficiaryAccountType\":\"PHONE\",\"beneficiaryEmail\":\"customer@example.com\",\"beneficiaryName\":\"Test Customer\",\"beneficiaryPhone\":\"03000000000\",\"beneficiaryWallet\":\"jazzcash\",\"channel\":\"\",\"country\":\"PK\",\"documentId\":\"0000000000000\",\"payType\":\"wallet_transfer\"}"
}
```

### 重试机制 <a href="#retry-attempts" id="retry-attempts"></a>

Topay 会向商户配置的 URL 发送 POST 请求，并期望收到 200 响应。如果未收到响应，Topay 会多次重发请求，重试间隔逐步增加；重试时间为 \[ 0,2,4,8,16,32,64] 分钟。<br>