UseePay Messaging Element for WooCommerce — 商户配置指南

本插件用于在 WooCommerce 店铺中嵌入 UseePay 的 Payment Method Messaging Element（先买后付提示控件），帮助商户在用户购物路径的关键节点展示 Klarna、Afterpay/Clearpay、Affirm 等分期付款选项，提升转化率与客单价。

---

目录

• 一、系统要求
• 二、安装插件
• 三、配置说明
  • 1. General — 基础设置
  • 2. Display — 显示设置
  • 3. Pages — 展示页面
• 四、支持的货币与支付方式
• 五、短代码用法（高级）
• 六、上线 Checklist
• 七、常见问题（FAQ）
• 八、技术支持

---

插件下载地址

useepay-messaging-element-for-woocommerce

一、系统要求

项目	要求
WordPress	5.8 及以上
WooCommerce	6.0 及以上
PHP	7.4 及以上
店铺货币	必须为下方"支持的货币"列表中的币种
UseePay 账号	已在 UseePay 商户后台开通，并已签约 Klarna / Afterpay / Affirm 中的至少一项

---

二、安装插件

1. 登录 WordPress 后台
2. 进入 插件 → 安装插件 → 上传插件
3. 选择 useepay-messaging-element-for-woocommerce.zip 上传
4. 上传完成后点击 启用
5. 启用后会在左侧菜单 WooCommerce → UseePay Messaging 看到配置入口

---

三、配置说明

进入 WooCommerce → UseePay Messaging 进行配置。配置页面分为三大块：General（基础）、Display（显示）、Pages（页面）。

1. General — 基础设置

Enable on-site messaging（启用站内消息）

总开关。关闭后，所有页面均不会显示 messaging element。

⚠️ 启用前请先完成下方所有必填项的配置，否则即使开启也不会显示。

Environment（运行环境）

自动识别，无需手动选择。

公钥前缀	识别为
UseePay_PK_TEST_ 开头	Sandbox（沙箱 / 测试环境）
UseePay_PK	Production（生产 / 正式环境）

在 Public Key 输入并保存后，本字段会自动识别并提示当前环境。

OpenAPI Public Key（OpenAPI 公钥）★必填

从 UseePay 商户后台获取：

1. 登录 UseePay Merchant Dashboard
2. 进入 开发者 → API 密钥 页面
3. 复制 公钥（Public Key）
4. 粘贴到此输入框

填入后，输入框右侧会显示对应环境徽章：

• 黄色 Sandbox 徽章 → 测试环境
• 绿色 Live 徽章 → 生产环境

💡 测试公钥以 UseePay_PK_TEST_ 开头；生产公钥以 UseePay_PK_LIVE_ 开头。请不要把测试公钥用于线上店铺。

App ID (x-app-id)（应用 ID / 交易主体）

UseePay 分配的 App ID，作为 x-app-id 请求头传递。填入您在 UseePay 商户后台注册的应用域名或唯一标识，例如 www.your-store.com。

⚠️ 如果商户后台对您的账户启用了 App ID 校验，此字段为必填；否则可留空。请向 UseePay 对接人员确认。

---

2. Display — 显示设置

Payment Methods（支付方式）

勾选希望展示的分期付款方式。可多选：

• ☐ Klarna — 北欧、欧洲、北美主流先买后付
• ☐ Afterpay / Clearpay — 澳洲 Afterpay / 英国 Clearpay
• ☐ Affirm — 美国 / 加拿大

💡 全部不勾选 = 自动展示所有支持的方式（推荐）。
不同支付方式对货币、国家、最低订单金额有不同要求，UseePay 后端会根据买家所在国家与店铺货币自动筛选可用项。

---

3. Pages — 展示页面

控制 messaging element 在哪些页面显示。每个开关独立，位置已根据最佳实践固化，不需要手动调整。

开关	展示位置	默认	适用场景
Product page	商品详情页，价格下方、加购按钮上方	开	让买家在做购买决策时看到分期选项
Cart page	购物车页，订单总额下方	开	在最终结算前再提醒一次
Checkout page	结账页，订单 review 区域	关	多数情况下结账页已展示完整支付方式，可按需开启
Shop / category pages	商品列表 / 分类页，每个商品标题下方	关	在浏览阶段强化分期心智，但可能拖累列表加载性能

💡 商品价格 ≤ 0 的情况下不会显示（避免无意义的展示）。
💡 当前店铺货币不在支持列表中时，整个插件不会加载。

---

四、支持的货币与支付方式

支持的店铺货币

USD, GBP, EUR, DKK, NOK, SEK, CAD, AUD, NZD, PLN, CZK, CHF, RON

若 WooCommerce 设置的店铺货币不在以上列表，messaging element 不会显示，配置页面顶部会出现红色提示。

支持的买家所在国

AT, AU, BE, CA, CH, CZ, DE, DK, ES, FI, FR, GB, GR, IE, IT, NL, NO, NZ, PL, PT, RO, SE, US

国家识别优先级：买家填写的账单国家 → 店铺所在国。

支持的支付方式

方式	主要市场
Klarna	北欧、欧洲、英国、美国
Afterpay (US/AU) / Clearpay (UK)	美国、澳洲、英国
Affirm	美国、加拿大

---

五、短代码用法（高级）

如果希望在自定义位置展示 messaging element，可使用短代码：

基本用法（取当前商品价格）

[useepay_messaging]

在商品详情页或循环中使用，会自动读取当前商品的含税价。

指定金额

[useepay_messaging amount="99.00"]

适用于固定价格的促销页、Landing Page。

指定币种

[useepay_messaging amount="99.00" currency="USD"]

默认使用 WooCommerce 店铺货币，仅在多币种特殊场景下需要指定。

---

六、上线 Checklist

正式上线前请逐项确认：

• 已在 UseePay 商户后台开通对应分期产品（Klarna / Afterpay / Affirm）
• OpenAPI Public Key 填入的是 生产公钥（UseePay_PK_LIVE_*），不是测试公钥
• 配置页右上角 Public Key 徽章显示为绿色 Live
• App ID 已填入（如对接人员要求）
• 店铺货币是支持的币种之一
• 已选择需要展示的页面（建议至少开启 Product 和 Cart）
• 在前台访问商品详情页、购物车页，确认 messaging 控件正常显示且无报错
• 在浏览器开发者工具 Console 中确认无 [UseePay Messaging] 红色错误

---

七、常见问题（FAQ）

Q1. 配置完成后页面上没有显示 messaging element？

按以下顺序排查：

1. 总开关是否开启？ 进入配置页确认 "Enable on-site messaging" 处于开启状态。
2. 是否填了 Public Key？ Public Key 为空时不会加载脚本。
3. 店铺货币是否支持？ 配置页顶部若有红色货币不支持提示，所有展示都会被禁用。
4. 当前页面是否启用？ 比如 Checkout 页默认是关闭的，需要主动开启。
5. 商品价格是否大于 0？ 价格为 0 的商品不会显示。
6. 打开浏览器开发者工具 Console，查看是否有 [UseePay Messaging] 开头的错误日志。

Q2. 显示了控件但内容是空白 / 加载圈一直转？

通常是后端请求被拒。检查：

• Public Key 是否输入正确、对应环境
• App ID 是否填写正确（如必填）
• 您的 UseePay 账户是否已开通对应的分期产品
• 当前买家所在国家是否在支持列表中

可以在浏览器 Network 面板中查看 iframe 内 /elements/messages 请求的响应。

Q3. 我能让控件出现在自定义模板的其他位置吗？

可以。使用短代码 [useepay_messaging] 插入到任意页面/模板/编辑器中即可。详见上方"短代码用法"小节。

Q4. 切换了商品 variation，价格更新了，但 messaging 没有刷新？

本插件已绑定 WooCommerce 的 found_variation 和 reset_data 事件。如发现没刷新，请：

• 清空浏览器缓存重试（旧版本插件可能有缓存）
• 确认主题没有自定义覆盖 WooCommerce 的 variation JS 事件

Q5. 沙箱环境一直报错 (intermediate value).find is not a function？

这是 UseePay SDK 1.0.1 与新版沙箱后端 API 契约不兼容导致的已知问题。本插件已升级到 SDK 2.0.0 并修复。如果你仍然看到此报错：

• 强制刷新浏览器（Cmd/Ctrl + Shift + R）清掉旧 SDK 缓存
• 确认浏览器 Network 面板中加载的是 useepay.min.js 的 2.0.0 路径，而不是 1.0.1

Q6. App ID 不填会怎样？

如果商户后台未对您的账户启用 App ID 校验，留空可正常使用。如果启用了，留空会导致后端请求被拒，messaging element 显示空白或控件挂载失败。请向 UseePay 对接人员确认。

Q7. 配置改了之后没生效？

WP 缓存 / 浏览器缓存导致。请：

1. 保存设置后清空 WordPress 站点缓存（若有 WP Super Cache、W3 Total Cache 等插件）
2. 浏览器强制刷新（Cmd/Ctrl + Shift + R）
3. 必要时清空 CDN 缓存

---

八、技术支持

• 商户技术对接：联系您的 UseePay 商务/技术对接人员
• UseePay 官方文档：https://docs-v2.useepay.com/
• Messaging Element 文档：https://docs-v2.useepay.com/7511542m0
• UseePay 商户后台：https://mc.useepay.com/

提交问题时请附上：

• WordPress 版本、WooCommerce 版本、PHP 版本
• 本插件版本号（见 WordPress 后台插件列表）
• 问题页面的 URL
• 浏览器 Console 错误截图
• 浏览器 Network 面板中相关请求的 Response 截图