# WooCommerce

> WooCommerce 付款方式：比特币和 USDC/USDT 直接到你的钱包，签名 Webhook 把订单标记为已付款。

Perly Pay 插件为经典结账和 Checkout 区块加上加密货币支付。每个订单都变成一张 Perly Pay 账单；买家在商店上方或单独页面中支付；签名 Webhook 把订单标记为已付款。要求 WordPress 6.5+、WooCommerce 8.6+、PHP 8.1+。服务器上无需安装任何东西：[PHP SDK](https://pay.perly.io/docs/sdks.md) 已内置。

> **注意:** 账单以 USD 或 EUR 开具。使用其他币种的商店会隐藏该付款方式，设置页会说明原因。

## 安装

1. **获取 zip** — 该插件正在上架 WordPress.org。在上架之前，请[联系我们](https://pay.perly.io/zh/contact)索取 `perly-pay-woocommerce.zip`。
2. **安装** — 在 WordPress 中：插件 → 安装插件 → 上传插件，选择 zip，启用。WooCommerce 必须处于启用状态。
3. **打开设置** — WooCommerce → 设置 → 付款 → **Perly Pay**。

## 设置

| 字段 | 填写内容 |
| --- | --- |
| 密钥 | Dashboard → Developers → API keys。`sk_test_…` 用于[测试模式](https://pay.perly.io/docs/test-mode.md)，`sk_live_…` 用于真实资金。设置页会显示你处于哪种模式。 |
| Webhook 签名密钥 | `whsec_…`。**设置 Webhook** 会自动填写。 |
| 付款页 | **弹窗**在商店上方打开付款窗口（pay.js）。**跳转**把买家带到付款页。手机上始终打开付款页本身。 |
| 付款后状态 | 由 WooCommerce 决定（处理中；可下载商品为已完成），或始终处理中，或始终已完成。 |
| 标题、描述 | 买家结账时看到的内容。 |
| 调试日志 | 事件和错误记录在 WooCommerce → 状态 → 日志中。绝不记录密钥、签名密钥或买家数据。 |

1. **粘贴密钥** — 然后点击**检查连接**：可以看到密钥是否可用、它的模式，以及 Perly Pay 中是否有这个商店的 Webhook。
2. **设置 Webhook** — 点击**设置 Webhook**。它会把商店地址（在按钮上方，`…/wp-json/perly-pay/v1/webhook`）添加到 Perly Pay 并保存签名密钥。也可以自己在 Developers → Webhooks 中添加，再粘贴签名密钥。
3. **允许弹窗** — 在 Dashboard → Settings 中，把商店地址加入 **Sites that may embed the checkout**。否则弹窗会提示在新标签页中打开付款页。
4. **启用** — 勾选**通过 Perly Pay 接收加密货币**并保存。

## 测试

使用 `sk_test_…` 密钥，在你的商店下一个订单并选择 Perly Pay。订单状态为**等待付款中**。用测试币支付账单，或通过 API 支付 — 账单 ID 在订单备注里：

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

几秒钟内订单变为**处理中**，并附一条备注：网络、金额和交易链接。账单页上已选好币种时，`{"outcome":"short"}` 和 `{"outcome":"over"}` 可测试其他情况。

## 订单如何跟踪付款

| 在 Perly Pay 中 | 订单 |
| --- | --- |
| 已付款，付款人已核查（`invoice.fulfilled`） | 已付款：设定的状态、库存扣减、给买家的邮件。一条备注列出每笔转账及其交易。 |
| 已发现、部分付款、已付款但仍在核查 | 一条备注。继续等待。 |
| 因[核查](https://pay.perly.io/docs/screening.md)暂扣 | 保留，附原因。在 Perly Pay 中处理。 |
| 已过期或已取消，未付款 | 已取消。 |
| 已过期，部分付款 | 保留：在 Perly Pay 中退款或接受。 |
| 已退款 | 全额退款，或一条部分退款的备注。 |

每个事件只处理一次，且只作用于为其创建的订单；迟到的“已过期”绝不会取消一笔付款。如果买家在 Webhook 之前回到了感谢页，插件会查询 API 并立即更新订单。

## 退款

像平常一样在订单页退款：插件会在 Perly Pay 中以买家付款时的币种发起[退款](https://pay.perly.io/docs/refunds.md)（部分退款则退相应部分）。Perly Pay 会通过邮件向买家索取地址并核查；订单备注会告诉你发送什么、发到哪里。你从自己的钱包发出，并把交易 ID 填入 Perly Pay — Perly Pay 从不持有资金。

## 上线

- 在 Perly Pay 中开启正式模式，并连接钱包公钥。
- 粘贴 `sk_live_…` 密钥。正式密钥和 Webhook 与测试的相互独立：再点一次**设置 Webhook**。
- 在正式模式下，把正式商店的 https 地址加入 **Sites that may embed the checkout**。
- 下一个小额真实订单，然后退款。