# Webhook

当收到通知后，请根据 `event_type` 做后续处理; 并且由于通知的异步性，建议以 API 查询结果为准

## 付款通知

### 授权成功通知

当交易订单授权成功时，会触发授权成功通知。字段 `event_type` 代表通知类型，`status` 仅代表通知时订单状态。

```json
{
  "event_type": "PAYMENT.AUTHORIZATION",
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m58129512",
  "order_id": "GW2056xxxxx2136685",
  "status": "AUTHORIZED",
  "amount": 199,
  "currency": "EUR",
  "session_id": "CS20602223728587",
  "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
  "expire_time": "2025-03-08T10:00:00+08:00",
  "payment": {
    "payment_method": "BANKCARD"
  },
  "card_info": {
    "bin": "424242",
    "last4": "4242",
    "card_brand": "VISA"
  }
}
```

### 请款成功通知

当交易订单成功时，会触发授权成功通知。字段`event_type` 代表通知类型，`status` 仅代表通知时订单状态。

```json
{
  "event_type": "PAYMENT.SUCCESS",
  "error_code": "0000",
  "error_description": "request success",
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m58129512",
  "order_id": "GW2056xxxxx2136685",
  "session_id": "CS20602223728587",
  "status": "SUCCESS",
  "amount": 99,
  "currency": "USD",
  "pay_finish_time": "2025-03-08T10:00:00+08:00",
  "recurring_agreement_id": "RA2061xxxx0784537",
  "token": "TK206139xxx264751",
  "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
  "expire_time": "2025-03-08T10:00:00+08:00",
  "payment": {
    "payment_method": "BANKCARD"
  },
  "card_info": {
    "bin": "424242",
    "last4": "4242",
    "card_brand": "VISA"
  },
  "balances": {
    "authed_amount": 0,
    "captured_amount": 0,
    "able_to_capture_amount": 0,
    "voided_amount": 0,
    "able_to_void_amount": 0,
    "refunded_amount": 0,
    "able_to_refund_amount": 0
  }
}
```

### 请款失败通知

当交易订单失败时，会触发请款失败通知。字段`event_type` 代表通知类型，`status` 仅代表通知时订单状态。

```json
{
  "event_type": "PAYMENT.FAILURE",
  "error_code": "0068",
  "error_description": "The transaction was declined by your issuer bank",
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m58129512",
  "order_id": "GW20620784537",
  "status": "FAILURE",
  "amount": 1979,
  "currency": "USD",
  "pay_finish_time": "2025-04-23T16:43:11+08:00",
  "recurring_agreement_id": "RA2061xxxx0784537",
  "token": "TK206139xxx264751",
  "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
  "expire_time": "2025-04-30T22:43:09+08:00",
  "payment": {
    "payment_method": "BANKCARD"
  },
  "card_info": {
    "bin": "400000",
    "last4": "9987",
    "card_brand": "VISA"
  },
  "balances": {
    "authed_amount": 0,
    "captured_amount": 0,
    "able_to_capture_amount": 0,
    "voided_amount": 0,
    "able_to_void_amount": 0,
    "refunded_amount": 0,
    "able_to_refund_amount": 0
  }
}
```

### 取消付款通知

当交易订单取消时，会触发取消付款通知。字段`event_type` 代表通知类型，`status` 仅代表通知时订单状态。

```json
{
  "event_type": "PAYMENT.CANCELED",
  "error_code": "0000",
  "error_description": "request success",
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m58129512",
  "order_id": "GW20620784537",
  "status": "CANCELED",
  "amount": 2903,
  "currency": "EUR",
  "pay_finish_time": "2025-04-17T19:59:24+08:00",
  "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
  "expire_time": "2025-04-18T01:59:21+08:00",
  "payment": {
    "payment_method": "BANKCARD"
  },
  "card_info": {
    "bin": "424242",
    "last4": "4242",
    "card_brand": "VISA"
  },
  "balances": {
    "authed_amount": 2903,
    "captured_amount": 0,
    "able_to_capture_amount": 0,
    "voided_amount": 2903,
    "able_to_void_amount": 0,
    "refunded_amount": 0,
    "able_to_refund_amount": 0
  }
}
```

## 退款通知

### 退款成功通知

当交易订单退款成功时，会触发退款成功通知。字段`event_type` 代表通知类型，`status` 仅代表通知时订单状态。

```json
{
  "event_type": "REFUND.SUCCESS",
  "error_code": "0000",
  "error_description": "request success",
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m58129512",
  "refund_order_id": "RG20324325320129",
  "order_id": "GW2056xxxxx2136685",
  "status": "SUCCESS",
  "amount": 2,
  "currency": "USD",
  "pay_finish_time": "2025-04-18T19:34:34+08:00"
}
```

### 退款失败通知

当交易订单退款失败时，会触发退款失败通知。`event_type` 代表通知类型，`status` 仅代表通知时订单状态。

```json
{
  "event_type": "REFUND.FAILURE",
  "error_code": "2010",
  "error_description": "The bookkeeping has failed for the refund",
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m58129512",
  "refund_order_id": "RG20324325320129",
  "order_id": "GW2056xxxxx2136685",
  "status": "FAILURE",
  "amount": 300,
  "currency": "USD",
  "pay_finish_time": "2025-04-22T13:53:10+08:00"
}
```

## 资金状态变更通知

### 资金状态变更通知

当交易订单资金状态变更时，会触发资金状态变更通知。字段 `event_type` 代表通知类型，`status` 仅代表通知处理状态。

**参数说明：**

| 参数 | 类型 | 说明 |
|  --- | --- | --- |
| `event_type` | string | 通知类型：`FUND.SETTLING`（结算处理中），`FUND.SETTLED`（结算已完成） |
| `merchant_id` | string | 商户ID |
| `order_id` | string | 网关订单号 |
| `amount` | integer | 交易金额，单位为最小货币单位（如分） |
| `currency` | string | 货币代码 |
| `status` | string | 通知处理状态，始终为 `SUCCESS` |
| `fund_status` | string | 资金状态：`SETTLING`（资金结算中），`SETTLED`（资金已结算） |
| `fund_status_updated_time` | string | 资金状态更新时间 |


```json
{
  "event_type": "FUND.SETTLED",
  "merchant_id": "18356675194960",
  "order_id": "GW2056xxxxx2136685",
  "amount": 9900,
  "currency": "USD",
  "status": "SUCCESS",
  "fund_status": "SETTLED",
  "fund_status_updated_time": "2025-04-22T13:53:10+08:00"
}
```