PingPong Checkout for WooCommerce 安装与运维指南

约 3308 字大约 11 分钟

2025-03-07

插件版本

2.3.6

1. 概述

本指南面向 WordPress + WooCommerce 商户站点的运维人员、对接工程师，描述 PingPong Checkout 收款插件（woocommerce-pppay）的安装、配置、对接、上线与运维行为。

维度	说明
适用对象	自主运营 WooCommerce 商店的商户、为客户搭建站点的建站服务商
不适用	Direct API 自研集成（请改用 Direct API 文档）
支持的结账形态	仅 Classic Checkout（`[woocommerce_checkout]` 短代码）
商品形态	实物商品 + 虚拟商品（`supports = ['refunds', 'products']`）

Checkout 兼容性说明

WooCommerce 自 8.3 起将 Block-Based Checkout 作为默认结账体验。当前 PingPong 插件仅支持 Classic Checkout 短代码模式，暂不支持 Block-Based Checkout。

新建站点请在 WooCommerce → 设置 → 高级中确认结账页使用 [woocommerce_checkout] 短代码
已迁移到 Block Checkout 的站点需恢复 Classic Checkout 后再启用本插件

2. 安装配置

2.1 软件版本

组件	最低版本	推荐版本	说明
WordPress	5.7	最新稳定版	插件头 `Requires at least`
WooCommerce	5.7	5.7+ 已实测	启动时进行版本检查
PHP	7.3	7.4	启动时强制校验

2.2 PHP 扩展

缺失强制扩展时，插件启用会触发 wp_die 阻断。

扩展	必需	用途
bcmath	✅ 强制	金额计算，避免浮点误差
curl	✅ 强制	与 PingPong 网关通信
json	✅	响应解析（PHP 8 起内置）
hash	✅	`md5` / `sha256` 签名（内置）
openssl	建议	TLS 通信依赖，curl 编译时通常已含

扩展缺失自查

2.3 系统权限

范围	要求	说明
WP 角色	`administrator` 或具备 `manage_woocommerce`	启用插件、配置网关
文件系统	Web 进程对 `wp-content/plugins/woocommerce-pppay/` 可读	解压后默认满足
日志目录	`WP_TEMP_DIR` 或 `wp-content/uploads/` 可写	异常时写入排障日志
数据库	当前 WP 数据库用户具备 `CREATE TABLE`	安装时建两张业务表

2.4 网络连通性

方向	目标	用途
出站	`https://acquirer-payment.pingpongx.com`（生产）	下单、查询、退款、Token 请求
出站	`https://sandbox-acquirer-payment.pingpongx.com`（沙箱）	下单、查询、退款、Token 请求
入站	`/wc-api/notify`	PingPong 异步回调，必须公网可达
	`/wc-api/refund`
	`/wc-api/show`

TLS 证书校验强制开启

自 v2.3.6 起，cURL 强制开启 CURLOPT_SSL_VERIFYPEER=true 与 CURLOPT_SSL_VERIFYHOST=2。

请确保服务器 CA 证书库（/etc/ssl/certs/ 或 cURL bundled CA）保持更新，否则下单请求会因证书校验失败而抛错。不要在排障时回退关闭校验。

2.5 性能建议（避免 504）

PingPong 收单接口超时上限 50 秒，建议同步放宽 Web 层超时：

php.ini：max_execution_time = 60
Nginx：fastcgi_read_timeout 60s;
Apache：Timeout 60

2.6 上传与启用

方式 A：后台上传（推荐）

WP 后台 → 插件 → 添加新插件 → 上传插件
选择 woocommerce-pppay.zip → 立即安装
安装完成后点击 启用

方式 B：FTP/SFTP 解压

解压 zip，将 woocommerce-pppay/ 目录上传到 wp-content/plugins/
WP 后台 → 插件 → 启用 PingPong-Checkout

启用后，WordPress 会触发 register_activation_hook，自动创建业务表（见 2.7 数据库变更）。

2.7 数据库变更（自动执行）

表名	用途	关键字段
`ping_pong_payment_log`	首次交易记录	`transaction_id`（唯一）、`pp_status`、`query_response`、`notify_response`
`ping_pong_secondary_payment_log`	二次交易（退款等）记录	`transaction_id`、`merchant_transaction_id`（均唯一）、`payment_type`、`amount`

卸载保留数据

卸载时这两张表不会被删除，仅清除 woocommerce_pppay_settings 选项，便于合规留痕。如需彻底清除，请手动执行 DROP TABLE。

2.8 日志目录配置

通过 FTP 编辑 wp-config.php，在 ABSPATH 定义之后追加：

wp-config.php
/** WordPress 目录的绝对路径。 */
if ( !defined('ABSPATH') ) {
    define('ABSPATH', dirname(__FILE__) . '/');
}

define('WP_TEMP_DIR', ABSPATH . 'wp-content/tmp');

确保该目录存在且可写：

shell
mkdir -p wp-content/tmp
chmod 755 wp-content/tmp
chown www-data:www-data wp-content/tmp  # 按实际 Web 用户调整

2.9 支付网关配置

WP 后台 → WooCommerce → 设置 → 支付
找到 Credit Card (PingPong Checkout) → 打开启用开关 → 管理

填写参数并保存：

字段	沙箱示例	说明
`gateway`	sandbox / production	环境切换
`clientId`	`2018092714313010016`	商户后台 → 系统管理 → 秘钥管理
`accId`	`2018092714313010016291`	商户后台 → 群组管理 → 网站详情
`salt`	`F78BC96A55548B2319EE68E0`	与 clientId 一一对应，严禁泄露
`allowedCountries`	ANY / SPECIFIC	是否按国家限制
`specificCountries`	国家码列表	仅在上一项为 SPECIFIC 时生效

3. 对接上线流程

3.1 安装前检查清单

WordPress 与 WooCommerce 均已激活
PHP ≥ 7.3 且已加载 bcmath、curl 扩展
已从对接群或商务获取 clientId / accId / salt
已确认订单号在同一 accId 下单调递增、不重复（见 4.2 订单号规则）
服务器可访问 PingPong 网关域名，CA 证书已更新

3.2 插件下载

woocommerce-pppay.zip

安装包约 213 KB，237 个文件，已内置 vendor/ 依赖，无需执行 composer install。

3.3 沙箱对接流程

按第 2 节完成安装，配置沙箱参数

沙箱环境店铺参数
# PingPong 沙箱环境店铺参数
clientId: 2018092714313010016
accId: 2018092714313010016291
salt: F78BC96A55548B2319EE68E0

使用沙箱测试卡自测：

沙箱环境测试卡号
# 标准测试卡号
卡号：4200000000000000
有效期：12/22
cvv：123  （cvv 需为 3 位纯数字）

# 3DS 交易测试卡号
3DS 交易卡：4711100000000000

PingPong 支付环境地址
# 沙箱环境地址
沙箱环境    https://sandbox-acquirer-payment.pingpongx.com

# 生产环境地址
生产环境    https://acquirer-payment.pingpongx.com

截图留存：
- 输入卡号页
- 支付完成跳转页
将截图发到对接群，通知技术支持

沙箱测试纪律

沙箱不会真扣款，但测试期间严禁发货：发货将造成实际损失；不发货则持卡人可能发起投诉。对接测试通过后，应立即关闭支付通道，等待生产环境上线后再打开。

3.4 生产上线流程

详细步骤：

沙箱对接通过后，进入 PingPong 商务/合规审核阶段（网站资料 + 账户资质）
审核通过后，发放生产 clientId / accId / salt
商户在 WP 后台将参数切换为生产值
商户自测 1 笔小额（建议 $1 商品链接），完成截图
将截图与商品链接发到对接群 → 由技术支持对该商品链接发起真实交易
真实交易成功后，商户发起退款，验证退款链路
完成以上流程后，支付通道正式上线

3.5 商户后台获取 accId 与秘钥

从对接群或商务/客户处获得审核通过通知后，登录商户后台。

进入网站列表
从菜单栏选择【网站管理】→【群组管理】→【查看详情】→【网站列表】
群组管理支持以下操作：
- 创建群组：点击「创建群组」新建群组；系统默认会提供一个默认群组
- 网站归属：网站下挂于群组，每个网站必须归属于一个群组
- 详情管理：点击「查看详情」可修改群组名称、查看复制 ID 号、查看群组下的网站
选择网站
根据当前对接网站的域名，在列表中选择对应的网站
获取网站 accId
获取秘钥
从菜单栏选择【系统管理】→【秘钥管理】→ 点击「秘钥详情」查看具体秘钥字段。
秘钥状态说明：
- 正常：可正常使用
- 异常：将无法使用，请联系相关业务人员处理

4. 资金安全与风险

4.1 状态核对与对账

状态优先原则

真实生产环境运营中，始终以收单商户后台的支付状态为准，发货前必须登录商户后台核对订单状态。

本插件不提供对账功能。商户需自行登录商户后台下载账单，与站点订单定期核对，确保订单状态、金额、退款记录一致。

4.2 订单号规则

订单号由 WooCommerce 提供，可能来源于：

WooCommerce 数据库自增的默认订单号
商户安装的「自定义订单号」插件（如 Sequential Order Number、Custom Order Numbers 等）

无论订单号来自哪种方式，商户必须保证同一 accId 下的订单号不重复且单调递增。

资金安全红线

PingPong 服务端强制以下规则，商户有责任遵守：

同一个 accId 下订单号不能重复，必须单调递增，否则会引发订单状态错乱
来源于不同数据库的订单不能共用同一个 accId（多站点共用 accId 不可行）
accId 下已有历史交易时，启用插件前应将订单号起始值调整为大于当前订单号最大值
重置数据库、迁移商店或 accId 迁往别的商店时，应先核查该 accId 下订单号最大值

违反以上规则会引发订单状态错乱、回调错配，直接影响资金对账。

如使用了「自定义订单号」插件，请确认其生成的订单号在重启、迁移、并发场景下仍满足"不重复且单调递增"的要求；建议优先选择基于数据库序列或带强校验的方案。

4.3 密钥安全

salt 是签名密钥，泄露后他人可伪造合法请求发起退款。请严格遵循：

❌ 严禁把 salt 写入前端可见的 JS / 模板
❌ 严禁在控制台、日志、截图、聊天工具中明文传递
❌ 严禁将含 salt 的 wp-options 导出文件发送给第三方
✅ 仅在 WP 后台配置字段与对接群内可信渠道中传递

4.4 网络与 TLS

v2.3.6 起 cURL 强制开启 SSL_VERIFYPEER + SSL_VERIFYHOST=2
服务器必须维护有效的 CA 证书库
若订单接口报 SSL 错误，先排查 CA 是否过期，不要回退关闭校验
回调入站路径 /wc-api/notify 应保持公网可达，建议在 WAF / Nginx 仅放行 PingPong 出口 IP 段

4.5 退款与二次交易

插件 process_refund 仅校验金额为正数，不会拦截超额退款，商户发起退款前需自查金额
部分退款记录在 ping_pong_secondary_payment_log，状态进入 PROCESSING 时订单状态会被冻结，直到 PingPong 服务端回写最终结果
退款流水号 merchant_transaction_id 与原交易号 transaction_id 均有唯一约束，重复发起会被数据库拦截

4.6 卸载行为

Uninstall 仅删除 woocommerce_pppay_settings 选项
两张业务表保留，便于合规追溯；如需彻底清除，请手动执行 DROP TABLE

5. 故障排查

现象	排查方向
启用后白屏	PHP 版本 < 7.3 或缺 `bcmath` / `curl`，查看后台 admin notice
下单返回 SSL 错误	检查服务器 CA 证书是否过期；不要关闭证书校验
下单 504	见 2.5 性能建议，调整 PHP / Nginx / Apache 超时
支付成功但订单状态未更新	确认 `/wc-api/notify` 公网可达、未被 WAF 拦截
退款失败 "duplicate"	`merchant_transaction_id` 已存在，需更换退款流水号
同一 accId 出现历史订单冲突	见 4.2 订单号规则，需在商户后台或数据库层面调整起始订单号

6. 附录

6.1 插件注册的关键钩子

钩子	类型	用途
`plugins_loaded` (0)	action	加载入口、环境检查、注册网关
`woocommerce_payment_gateways`	filter	注册 `WC_Pppay`
`woocommerce_api_{notify/refund/show}`	action	异步回调端点
`woocommerce_thankyou_pppay`	action	支付完成页
`wc_ajax_ppc_token_request`	action	前端换取 token
`wc_ajax_ppc_polling_order_status`	action	订单状态轮询
`wc_ajax_ppc_get_order_detail`	action	取订单详情
`add_meta_boxes`	action	后台订单 MetaBox
`register_activation_hook`	hook	建表
`register_uninstall_hook`	hook	清理配置

6.2 版本信息

项	值
当前插件版本	`2.3.6`
安装包	`woocommerce-pppay.zip`（约 213 KB，237 文件）
依赖	包内已含 `vendor/`，无需 `composer install`

无代码接入

开发者接入

PingPong 收银台

Native SDK

合规接入指南

Direct API