# Webhook 与 API 参考

本文档描述了 Antom Payments for WooCommerce 使用的 Webhook 处理、支付查询和 SDK API。

## Webhook

插件通过 Webhook 端点从 Antom 接收异步支付通知。

### Webhook URL

```
https://your-store.com/?wc-api=antom_payment_notify
```

在 [Antom 商家门户](https://dashboard.alipay.com/global-payments/home) 中配置此 URL。

### 通知处理

Webhook 由 `WC_Gateway_Antom_Common` 中的 `payment_notify_handler()` 方法处理。

**流程：**

```
Antom API ──POST──► /?wc-api=antom_payment_notify
                        │
                        ▼
            payment_notify_handler()
                        │
                        ├─► 解析通知数据
                        ├─► 验证 RSA-SHA256 签名
                        ├─► 验证支付请求 ID
                        ├─► 更新订单状态
                        ├─► 返回 SUCCESS/FAILURE 响应
                        └─► 记录日志
```

**响应格式：**

处理器返回 JSON 编码的结果：

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}
```

| 字段 | 可能的值 | 说明 |
|---|---|---|
| `resultCode` | `SUCCESS`、`FAIL` | 处理结果 |
| `resultStatus` | `S`、`F` | 状态码（S = 成功，F = 失败） |
| `resultMessage` | 自由文本 | 人类可读的消息 |

### Webhook 安全

1. **签名验证** — 每个 Webhook 数据包含一个签名头。插件使用配置的 Antom 公钥通过 `Antom_Signature_Tool` 验证此签名。
2. **支付请求 ID** — 通过检查数据库中存储的唯一支付请求 ID 来防止重复支付通知。

## 支付查询

作为回退机制，当 Webhook 通知延迟或丢失时，插件可以直接查询 Antom API 的支付状态。

### 查询端点

```
/?wc-api=antom_inquiry_webhook
```

查询由 `WC_Gateway_Antom_Common` 中的 `inquiry_handler()` 方法触发。

### 查询流程

```
结账页面加载 / AJAX 调用查询
        │
        ▼
inquiry_handler()
        │
        ├─► 使用支付请求 ID 构建查询请求
        ├─► SDK::inquiry_payment()
        │       │
        │       └─► Antom API → 支付状态
        │
        └─► 根据查询结果更新订单状态
```

## SDK API

Antom SDK（`includes/sdk/`）提供与 Antom API 的通信层。

### HTTP 客户端：`Antom_Alipay_Client`

```php
$client = new Antom_Alipay_Client(
    $gatewayUrl,         // Antom API 端点
    $merchantPrivateKey, // 商家的 RSA 私钥
    $alipayPublicKey     // Antom 的 RSA 公钥
);

$response = $client->execute($request);
```

- **构造函数参数：**
  - `$gatewayUrl` — Antom API 基础 URL
  - `$merchantPrivateKey` — 你的 RSA 私钥（PKCS#8）
  - `$alipayPublicKey` — Antom 的 RSA 公钥

- **`$client->execute($request)`** — 向 Antom API 发送签名请求并返回解析后的响应

### 签名工具：`Antom_Signature_Tool`

处理 RSA-SHA256 签名生成和验证：

- **`sign($httpMethod, $path, $clientId, $reqTime, $reqBody, $merchantPrivateKey)`** — 为外发请求生成签名
- **`verify($signValue, $httpMethod, $path, $clientId, $reqTime, $reqBody, $alipayPublicKey)`** — 验证传入响应/Webhook 的签名

### 请求构建器

#### 基础请求：`SDK_Antom_Alipay_Request`

```php
$request = new SDK_Antom_Alipay_Request();
$request->set_client_id($clientId);
$request->set_path($apiPath);
$request->set_http_method('POST');
$request->set_key_version(1);
```

#### 在线支付请求：`SDK_Antom_Alipay_Online_Request`

用于创建支付会话：

```php
$request = new SDK_Antom_Alipay_Online_Request();
$request->set_client_id($clientId);
$request->set_path('/ams/api/onlinePayment/create');
$request->set_http_method('POST');
$request->set_key_version(1);

// 设置订单参数
$request->set_order($orderModel);
$request->set_payment_amount($amountModel);
$request->set_payment_redirect_url($redirectUrl);
$request->set_payment_notify_url($notifyUrl);
```

#### 查询请求：`SDK_Antom_Alipay_Inquiry_Request`

用于支付状态查询：

```php
$request = new SDK_Antom_Alipay_Inquiry_Request();
$request->set_client_id($clientId);
$request->set_path('/ams/api/inquiry/payment');
$request->set_http_method('POST');
$request->set_key_version(1);

$request->set_payment_request_id($paymentRequestId);
```

### RPC 响应模型

响应解析为 `Antom_Http_Rpc_Result`：

- **`getRspBody()`** — 响应体（已解码 JSON）
- **`getRspSign()`** — 响应签名值
- **`getRspTime()`** — 响应时间戳

## 数据模型

### 订单模型 (`Antom_Order_Model`)

聚合所有订单相关数据的顶层订单模型：

```php
$order = new Antom_Order_Model();
$order->set_order_amount($amountModel);
$order->set_order_buyer($buyerModel);
$order->set_order_env($envModel);
$order->set_payment_method($paymentMethodModel);
$order->set_payment_redirect_url($redirectUrl);
$order->set_payment_notify_url($notifyUrl);
$order->set_payment_request_id($uniqueId);
$order->set_merchant_order_no($orderId);
$order->set_order_settlement_strategy($settlementStrategyModel);
```

### 子模型

| 模型 | 字段 | 用途 |
|---|---|---|
| `Antom_Order_Amount_Model` | `currency`、`value` | 支付金额 |
| `Antom_Order_Buyer_Model` | `buyer_id`、`buyer_name`、`buyer_phone`、`buyer_register_time` | 客户信息 |
| `Antom_Order_Env_Model` | `terminal_type`、`os_type`、`device_info` | 环境/设备 |
| `Antom_Order_Name_Model` | `first_name`、`last_name`、`full_name` | 名称处理 |
| `Antom_Order_Payment_Method_Model` | `payment_method_type` | 方式标识符 |
| `Antom_Order_Settlement_Strategy_Model` | `settlement_currency` | 结算配置 |
| `Antom_Refund_Model` | `refund_amount`、`refund_reason`、`order_id` | 退款数据 |

## API 端点 (Antom)

插件与以下 Antom API 端点通信：

| 端点 | 用途 |
|---|---|
| `/ams/api/onlinePayment/create` | 创建支付会话 |
| `/ams/api/inquiry/payment` | 查询支付状态 |
| `/ams/api/onlinePayment/refund` | 处理退款 |

## 工具函数

### 选项管理：`Antom_Payment_Gateways_Options`

管理 WordPress `wp_options` 表中插件选项的单例类（前缀：`antom_payment_gateway_`）：

```php
// 获取选项
$value = Antom_Payment_Gateways_Options::get_instance()->get_option('option_name', $default);

// 设置选项
Antom_Payment_Gateways_Options::get_instance()->set_option('option_name', $value);
```

### 支付请求检查器：`Antom_Payment_Request_Checker`

管理唯一支付请求 ID 以防止重复处理：

```php
// 为订单生成支付请求 ID
$requestId = antom_generate_payment_request_id($order_id);

// 从支付请求 ID 获取订单 ID
$orderId = antom_get_order_id_by_payment_request_id($payment_request_id);
```

## 参见

- [架构概述](architecture.md) — 系统架构
- [配置指南](configuration.md) — 设置和配置
- [开发指南](development.md) — 构建和开发