# 常见问题解答

## 通用

### Antom 是什么？

Antom 是蚂蚁集团（支付宝母公司）旗下的官方支付服务提供商。Antom 的 AI 驱动支付平台通过优化的支付体验和数字化服务帮助企业实现全球增长。

### 这个插件支持哪些支付方式？

插件支持全球 300+ 种支付方式，包括：
- **信用卡/借记卡** — Visa、Mastercard、AMEX、JCB、Discover、Diners Club、UnionPay（通过 Antom Elements）
- **数字钱包** — 支付宝（中国大陆和香港）、DANA、GCash、Kakao Pay、NAVER Pay、Touch 'n Go、Toss Pay、TrueMoney
- **收银台支付 (CKP)** — 聚合多种本地支付方式的结算页面

完整列表请参阅[支付方式](payment-methods.md)文档。

### 这个插件依赖任何第三方服务吗？

是的，本插件依赖 **Antom 支付服务**。当客户选择 Antom 支付方式时，插件会与 Antom 的支付系统通信以处理交易。你可以查看相关的服务文档[这里](https://global.alipay.com/docs/ac/ams/api)。

### 是否必须安装 WooCommerce？

是的，必须安装并启用 WooCommerce 才能使用本插件。如果 WooCommerce 不存在，插件会显示错误消息并拒绝激活。

### 插件是否兼容 HPOS（高性能订单存储）？

是的，插件完全支持 WooCommerce 高性能订单存储。

### 插件是否支持订阅？

是的，插件通过公共网关类中的 `woocommerce_scheduled_subscription_payment_` 操作钩子支持 WooCommerce Subscriptions。

## 安装与设置

### 如何获取我的 API 凭据？

1. 在 [Antom 控制台](https://dashboard.antom.com/global-payments/account/register?bizMode=ISV&isvBizScene=ISO_COMMON&registrationSource=WooCommerce) 注册 Antom 商家账户
2. 进入账户设置查找你的 **Client ID**
3. 生成或上传你的 **RSA 密钥对**（用于签名的私钥，以及提供给 Antom 的公钥）
4. 复制 Antom 的 **公钥** 用于响应验证

### 如何设置 Webhook？

1. 登录 [Antom 商家门户](https://dashboard.alipay.com/global-payments/home)
2. 进入 Webhook/通知配置部分
3. 设置 Webhook URL 为：
   ```
   https://your-store.com/?wc-api=antom_payment_notify
   ```

### 为什么结账时没有显示支付方式？

这通常是由于 **币种筛选**。每种支付方式只支持特定的币种。如果你的商店币种不被该方式支持，它将不会出现在结账页面。

检查：
- 在 **WooCommerce → 设置 → 常规** 中查看商店币种
- 在[支付方式](payment-methods.md)参考中查看每种方式支持的币种
- 在 **WooCommerce → 设置 → 结账** 中确认该支付方式已启用

### 可以使用测试模式吗？

可以。在 Antom Payment Gateway 核心设置中启用 **测试模式**。启用后：
- 所有请求发送到 Antom 沙箱环境
- 结账页面会显示 "Test Mode (Antom Sandbox)" 警告
- 使用 Antom 商家门户中的沙箱凭据

## 结账

### 客户下单后会发生什么？

1. 订单创建，状态为 **等待付款**
2. 对于数字钱包：客户被重定向到 Antom 的支付页面（CKP）
3. 对于卡支付：创建支付会话，客户在结账页面完成支付
4. 支付完成后，Antom 发送 Webhook 通知
5. 订单状态相应更新

### 支持哪些结账模式？

插件同时支持：
- **WooCommerce 经典结算**（服务端渲染的 PHP 模板）
- **WooCommerce 区块结算**（基于 React 的 JavaScript 区块）

### 客户可以为失败订单重试支付吗？

可以。客户可以通过 WooCommerce 的 **订单支付** 页面重试已失败订单的支付。插件同时支持卡支付和数字钱包支付的支付重试。

## 安全

### 卡支付如何确保安全？

卡支付使用 **Antom Elements SDK**——一种符合 PCI-DSS 标准的解决方案。卡字段作为嵌入式 iframe 渲染，卡数据在客户端使用 RSA + AES 加密。无明文卡数据触及商家服务器。

### API 请求如何确保安全？

所有 API 请求使用商家的 RSA 私钥通过 **RSA-SHA256** 签名。来自 Antom 的响应使用 Antom 的 RSA 公钥验证。这确保了请求的真实性和完整性。

### Webhook 如何确保安全？

Webhook 通知通过检查每个通知数据中包含的 RSA 签名进行验证。仅处理经过正确签名的通知。

### 采取了哪些 WordPress 安全措施？

- **Nonce 验证** — 所有 AJAX 端点使用 WordPress nonce 进行 CSRF 防护
- **输入消毒** — 所有用户输入通过 WordPress 核心函数消毒（`sanitize_text_field`、`absint`、`floatval` 等）
- **权限检查** — 管理端点检查正确的 WordPress 能力

## 退款

### 如何处理退款？

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

### 支持部分退款吗？

是的，同时支持全额和部分退款。

## 故障排除

### 插件无法激活

确保 **WooCommerce** 已安装并启用。插件在激活时会检查 WooCommerce，如果没有则无法激活。

### 遇到签名错误

检查你的密钥配置：
1. **私钥 (Private Key)** — 必须是 PKCS#8 格式的商家私钥
2. **公钥 (Public Key)** — 必须是 Antom 的公钥（而不是你自己的）
3. 确保密钥值中没有多余的空格、换行符或不可见字符

### Webhook 通知未收到

1. 确认 Webhook URL 已在 Antom 商家门户中正确配置
2. 确保你的服务器可从互联网访问（没有被防火墙阻止）
3. 检查 Webhook URL 是否完全匹配：`https://your-store.com/?wc-api=antom_payment_notify`
4. 启用 WordPress 调试日志以查看 Webhook 请求是否到达

### 支付方式在区块结算中不显示

1. 确保区块资源已构建：开发时运行 `npm run build`
2. 清除任何缓存插件
3. 确认区块支持类已加载（位于 `includes/blocks/`）
4. 检查浏览器控制台是否有 JavaScript 错误

### 订单一直处于"等待付款"状态

这通常意味着未收到 Webhook 通知：
1. 检查你的 Webhook 配置
2. 插件包含一个回退查询机制，会在后续页面加载时检查支付状态
3. 如果问题持续存在，启用调试日志进行调查

## 支持

### 如何联系支持团队？

- **邮件：** global.service@alipay.com
- **文档：** [Antom WooCommerce 集成指南](https://global.alipay.com/docs/ac/plugins/woocommerce)
- **Antom 控制台：** [dashboard.alipay.com](https://dashboard.alipay.com/global-payments/home)

### 在哪里注册 Antom 账户？

在 [Antom 控制台](https://dashboard.antom.com/global-payments/account/register?bizMode=ISV&isvBizScene=ISO_COMMON&registrationSource=WooCommerce) 注册。

## 参见

- [安装指南](installation.md) — 分步设置
- [配置指南](configuration.md) — 设置参考
- [Webhook 与 API 参考](webhook-api.md) — 技术性 API 详情