# 配置指南

本指南涵盖了 Antom Payments for WooCommerce 的所有配置选项。

## 核心设置

核心设置通过 **WooCommerce → 设置 → 结账 → Antom Payment Gateway** 访问。

| 设置项 | 必填 | 说明 |
|---|---|---|
| **启用/禁用** | 是 | 开启/关闭 Antom Payment Gateway |
| **标题** | 否 | 结账页面显示的名称（默认："Antom Payments"） |
| **描述** | 否 | 结账页面显示的描述 |
| **Client ID** | **是** | 你的 Antom 商家客户端 ID |
| **私钥 (Private Key)** | **是** | 用于请求签名的 RSA 私钥（PKCS#8 格式） |
| **公钥 (Public Key)** | **是** | 用于响应验证的 Antom RSA 公钥 |
| **域名 (Domain)** | 否 | 自定义 API 域名（覆盖默认 Antom API 端点） |
| **测试模式 (Test Mode)** | 否 | 启用/禁用沙箱环境（1 = 启用，0 = 禁用） |
| **结算币种** | 否 | 资金结算币种 |

### Client ID

Antom 提供给商家的唯一标识符。可在 **Antom 商家门户** 的账户设置中找到。

### 密钥管理

插件使用 RSA-SHA256 进行 API 请求签名：

- **私钥 (Private Key)** — 你的商家私钥，用于签名外发 API 请求。必须使用 PKCS#8 格式。
- **公钥 (Public Key)** — Antom 的公钥，用于验证传入的 API 响应和 Webhook 通知。

**⚠️ 安全提示：** 请确保你的私钥安全。切勿分享或将其提交到版本控制系统。

### 测试模式

启用后，所有支付请求将发送至 Antom 沙箱环境。使用从 Antom 商家门户获取的沙箱凭据（独立的 Client ID 和密钥）。

测试模式激活时，结账页面将显示 **"Test Mode (Antom Sandbox)"** 警告。

### 自定义域名

如果你有 Antom 提供的专用 API 域名，可在此配置。留空则使用默认端点。

## 各支付方式设置

每种支付方式在 **WooCommerce → 设置 → 结账** 下都有自己的设置页面：

| 设置项 | 说明 |
|---|---|
| **启用/禁用** | 开启/关闭该特定支付方式 |
| **标题** | 该支付方式的自定义显示名称 |
| **描述** | 结账时显示的自定义描述 |
| **测试模式** | 为该特定方式覆盖测试模式设置 |

### 币种筛选

支付方式会根据商店币种自动筛选。结账时仅显示支持当前币种的方式。

例如：
- **NAVER Pay** 仅支持 KRW（韩元）
- **支付宝（中国大陆）** 支持 17 种币种，包括 CNY、USD、EUR、JPY
- **信用卡** 支持 10 种主要币种

完整的币种支持矩阵请参阅[支付方式](payment-methods.md)文档。

## Webhook 配置

Webhook URL 处理来自 Antom 的异步支付通知。

### Webhook URL

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

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

### Webhook 事件

插件处理以下支付通知事件：

| 事件 | 说明 |
|---|---|
| **支付成功** | 订单标记为"处理中"或"已完成" |
| **支付失败** | 订单状态更新为"失败"并附带错误详情 |
| **支付取消** | 订单状态相应更新 |

### Webhook 安全

Webhook 请求通过以下方式验证：
1. **签名验证** — 使用配置的公钥验证 Antom 的签名
2. **响应处理** — 仅处理经过正确签名的通知

## 支付流程

### 标准支付（数字钱包）

1. 客户在结账时选择支付方式
2. WooCommerce 创建订单，状态为"等待付款"
3. 客户被重定向到 Antom 的收银台页面（CKP）或留在结账页面
4. 支付完成后，Antom 发送 Webhook 通知
5. 根据支付结果更新订单状态

### 卡支付（Antom Elements）

1. 客户在嵌入式字段中输入卡信息（Antom Elements SDK）
2. 卡数据在客户端加密（RSA + AES）
3. 通过 AJAX 创建支付会话
4. 客户确认支付
5. 处理支付结果

### 重新支付

客户可以在 **订单支付** 页面重试已失败订单的支付。

## 退款配置

退款可以在 WooCommerce 订单管理页面处理：

1. 进入 **WooCommerce → 订单**
2. 点击要退款的订单
3. 点击 **退款**
4. 输入退款金额（全额或部分）
5. 提交 — 退款通过 Antom API 处理

## 订单状态映射

| 支付结果 | WooCommerce 状态 |
|---|---|
| 成功 | 处理中 / 已完成 |
| 失败 | 失败 |
| 处理中 | 等待付款 |
| 已取消 | 已取消 |

## HPOS 兼容性

插件完全支持 WooCommerce 高性能订单存储（HPOS）。确保在 **WooCommerce → 设置 → 高级 → 功能** 中启用 HPOS。

## 参见

- [安装指南](installation.md) — 初始设置说明
- [Webhook 与 API 参考](webhook-api.md) — 技术性 Webhook 详情
- [架构概述](architecture.md) — 系统架构