---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/integrate/woocommerce/index.md
description: >-
  面向 WordPress + WooCommerce 商户站点的 PingPong Checkout 收款插件（woocommerce-pppay
  v2.3.6）完整指南，覆盖运行环境、安装配置、沙箱对接、生产上线、订单号规则、密钥与 TLS 安全、退款与二次交易、卸载行为、故障排查及钩子附录。适用于
  Classic Checkout 短代码模式，支持实物与虚拟商品，强制依赖 PHP 7.3+、bcmath、curl 扩展。
---
# PingPong Checkout for WooCommerce 安装与运维指南

::: note **插件版本**
 `2.3.6`
:::

## 1. 概述

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

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

::: warning 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 编译时通常已含 |

::: tip 扩展缺失自查
在服务器执行 `php -m | grep -E 'bcmath|curl|json|hash|openssl'` 查看已加载扩展。
:::

### 2.3 系统权限

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

### 2.4 网络连通性

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

::: warning TLS 证书校验强制开启
自 **WooCommerce 插件 `v2.3.6`** 起，cURL 强制开启 **`CURLOPT_SSL_VERIFYPEER=true`** 与 **`CURLOPT_SSL_VERIFYHOST=2`**。

这里的 `v2.3.6` 指 **插件版本**，不是 TLS 协议版本。TLS 协议要求仍按现有平台安全要求执行（当前文档口径为 `TLS 1.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：后台上传（推荐）**

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

**方式 B：FTP/SFTP 解压**

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

启用后，WordPress 会触发 `register_activation_hook`，自动创建业务表（见 [2.7 数据库变更](#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` |

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

### 2.8 日志目录配置

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

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

define('WP_TEMP_DIR', ABSPATH . 'wp-content/tmp');  // [!code highlight]
```

确保该目录存在且可写：

```bash:line-numbers title="shell"
mkdir -p wp-content/tmp
chmod 755 wp-content/tmp
chown www-data:www-data wp-content/tmp  # 按实际 Web 用户调整
```

![image-9](/wordpress/image-9.png)

### 2.9 支付网关配置

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

![image-7](/wordpress/image-7.png)

3. 填写参数并保存：

![image-8](/wordpress/image-8.png)

| 字段 | 沙箱示例 | 说明 |
|---|---|---|
| `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 订单号规则](#4-2-订单号规则)）
- [ ] 服务器可访问 PingPong 网关域名，CA 证书已更新

### 3.2 插件下载

<a :href="$withBase('/wordpress/woocommerce-pppay.zip')" download="woocommerce-pppay.zip">woocommerce-pppay.zip</a>

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

### 3.3 沙箱对接流程

1. 按 [第 2 节](#2-安装配置) 完成安装，配置沙箱参数

```text:line-numbers title="沙箱环境店铺参数"
# [!code highlight] PingPong 沙箱环境店铺参数
clientId: 2018092714313010016
accId: 2018092714313010016291
salt: F78BC96A55548B2319EE68E0
```

2. 使用沙箱测试卡自测：

```text:line-numbers title="沙箱环境测试卡号"
# [!code highlight] 标准测试卡号
卡号：4200000000000000
有效期：12/22
cvv：123  （cvv 需为 3 位纯数字）

# [!code highlight] 3DS 交易测试卡号
3DS 交易卡：4711100000000000
```

```text:line-numbers title="PingPong 支付环境地址"
# [!code highlight] 沙箱环境地址
沙箱环境    https://sandbox-acquirer-payment.pingpongx.com

# [!code highlight] 生产环境地址
生产环境    https://acquirer-payment.pingpongx.com
```

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

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

### 3.4 生产上线流程

```mermaid
flowchart TD
    A[🚀 沙箱对接通过] --> B[📋 商务/合规审核]
    B --> C[🔑 发放生产 clientId/accId/salt]
    C --> D[⚙️ 商户后台切换为生产参数]
    D --> E[💰 商户自测小额商品]
    E --> F[📤 截图与商品链接发对接群]
    F --> G[🎯 技术支持发起真实交易]
    G --> H[🔄 商户发起退款验证链路]
    H --> I[✅ 支付通道正式上线]

    style A fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style B fill:#FF7043,stroke:#E64A19,color:#fff,stroke-width:2px
    style C fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style D fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style E fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style F fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style G fill:#FF7043,stroke:#E64A19,color:#fff,stroke-width:2px
    style H fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style I fill:#4CAF50,stroke:#388E3C,color:#fff,stroke-width:2px
```

**详细步骤**：

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

### 3.5 商户后台获取 accId 与秘钥

从对接群或商务/客户处获得审核通过通知后，登录[商户后台](https://checkout.pingpongx.com/aq/websiteList)。

::: steps
1. 进入网站列表

   从菜单栏选择【网站管理】→【群组管理】→【查看详情】→【网站列表】

   ![image-4](/wordpress/image-4.png)

   群组管理支持以下操作：

   - **创建群组**：点击「创建群组」新建群组；系统默认会提供一个默认群组
   - **网站归属**：网站下挂于群组，每个网站必须归属于一个群组
   - **详情管理**：点击「查看详情」可修改群组名称、查看复制 ID 号、查看群组下的网站

2. 选择网站

   根据当前对接网站的域名，在列表中选择对应的网站

   ![image-5](/wordpress/image-5.png)

3. 获取网站 accId

   ![image-6](/wordpress/image-6.png)

4. 获取秘钥

   从菜单栏选择【系统管理】→【秘钥管理】→ 点击「秘钥详情」查看具体秘钥字段。

   秘钥状态说明：

   - **正常**：可正常使用
   - **异常**：将无法使用，请联系相关业务人员处理

   ![image](/wordpress/image-9475334.png)
:::

---

## 4. 资金安全与风险

### 4.1 状态核对与对账

::: danger 状态优先原则
真实生产环境运营中，**始终以[收单商户后台](https://checkout.pingpongx.com/)的支付状态为准**，发货前必须登录商户后台核对订单状态。

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

### 4.2 订单号规则

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

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

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

::: danger 资金安全红线
PingPong 服务端强制以下规则，商户有责任遵守：

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

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

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

### 4.3 密钥安全

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

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

### 4.4 网络与 TLS

- WooCommerce 插件 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 性能建议](#2-5-性能建议-避免-504)，调整 PHP / Nginx / Apache 超时 |
| 支付成功但订单状态未更新 | 确认 `/wc-api/notify` 公网可达、未被 WAF 拦截 |
| 退款失败 "duplicate" | `merchant_transaction_id` 已存在，需更换退款流水号 |
| 同一 accId 出现历史订单冲突 | 见 [4.2 订单号规则](#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` |