指南
WooCommerce
WooCommerce 付款方式：比特币和 USDC/USDT 直接到你的钱包，签名 Webhook 把订单标记为已付款。
Perly Pay 插件为经典结账和 Checkout 区块加上加密货币支付。每个订单都变成一张 Perly Pay 账单；买家在商店上方或单独页面中支付；签名 Webhook 把订单标记为已付款。要求 WordPress 6.5+、WooCommerce 8.6+、PHP 8.1+。服务器上无需安装任何东西：PHP SDK 已内置。
安装
- 1
获取 zip
该插件正在上架 WordPress.org。在上架之前，请联系我们索取
perly-pay-woocommerce.zip。 - 2
安装
在 WordPress 中：插件 → 安装插件 → 上传插件，选择 zip，启用。WooCommerce 必须处于启用状态。
- 3
打开设置
WooCommerce → 设置 → 付款 → Perly Pay。
设置
| 字段 | 填写内容 |
|---|---|
| 密钥 | Dashboard → Developers → API keys。sk_test_… 用于测试模式，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 在订单备注里：
几秒钟内订单变为处理中，并附一条备注：网络、金额和交易链接。账单页上已选好币种时，{"outcome":"short"} 和 {"outcome":"over"} 可测试其他情况。
订单如何跟踪付款
| 在 Perly Pay 中 | 订单 |
|---|---|
已付款，付款人已核查（invoice.fulfilled） | 已付款：设定的状态、库存扣减、给买家的邮件。一条备注列出每笔转账及其交易。 |
| 已发现、部分付款、已付款但仍在核查 | 一条备注。继续等待。 |
| 因核查暂扣 | 保留，附原因。在 Perly Pay 中处理。 |
| 已过期或已取消，未付款 | 已取消。 |
| 已过期，部分付款 | 保留：在 Perly Pay 中退款或接受。 |
| 已退款 | 全额退款，或一条部分退款的备注。 |
每个事件只处理一次，且只作用于为其创建的订单；迟到的“已过期”绝不会取消一笔付款。如果买家在 Webhook 之前回到了感谢页，插件会查询 API 并立即更新订单。
退款
像平常一样在订单页退款：插件会在 Perly Pay 中以买家付款时的币种发起退款（部分退款则退相应部分）。Perly Pay 会通过邮件向买家索取地址并核查；订单备注会告诉你发送什么、发到哪里。你从自己的钱包发出，并把交易 ID 填入 Perly Pay — Perly Pay 从不持有资金。
上线
- 在 Perly Pay 中开启正式模式，并连接钱包公钥。
- 粘贴
sk_live_…密钥。正式密钥和 Webhook 与测试的相互独立：再点一次设置 Webhook。 - 在正式模式下，把正式商店的 https 地址加入 Sites that may embed the checkout。
- 下一个小额真实订单，然后退款。