---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/integrate/zenCart/index.md
description: >-
  ZenCart-PPPay 插件安装说明提供了在 ZenCart 平台上集成 PPPay 支付插件的详细步骤。适用于 ZenCart 1.7
  及以上版本，需满足 PHP 7.1 及其扩展要求。文档涵盖了从上传文件到配置环境参数的全过程，并强调了订单号唯一性和单调递增的重要性。
---
# ZenCart-PPPay 插件安装说明

### 安装前提

> - ZenCart version>=1.7
> - php version >=7.1
> - php Extensions:curl bcmath  
> - chmod 777 /zenCartRoot/logs 

---

以下为非必要设置，若出现504错误可以检查下列选项

- [ ] php ini执行超时时间 
- [ ] nginx 或者 apache 设置执行超时时间

---

::: danger
1. 同一个accId下订单号不能重复，必须是单调递增的，否则会引发订单状态问题；
2. 来源于不同数据库的订单不能共用同一个accId；
3. accId下已经有过交易，安装插件之前应该将id起始值设置为大于当前订单id最大的值；
4. 重置数据库，商店，或者accId迁往别的商店，应该检查accId下订单号最大值。
:::

###

### ZenCart安装路径规则
#### 解压文件
解压之后，目录结构如下。
这四个目录和zenCart/inclues 下面的目录对应。
![image.png](/zencart/1629463595657-e90b21d9-ff38-4fe4-8a28-b1941f5be7df.png)

### 安装过程

#### 登录FTP
使用FTP工具上服务器，上传插件压缩包。
没有FTP工具，可以使用命令行，windwos下使用powershell。
SFTP命令-连接远程服务器：
```shell:line-numbers title="terminal"
sftp username@ip  # [!code focus]
```

#### 文件上传
没有FTP工具，使用SFTP命令-将文件上传到服务器上：
```shell:line-numbers title="terminal"
put [本地文件的地址] [服务器上文件存储的位置]  # [!code focus]
```
#### 文件解压
使用unzip命令
ZenCart-PPPay 带有完整的目录结构, 插件解压后带有inclues/目录，在zenCart根目录解压后，插件文件会自动合并到原有文件下。

### 配置过程
#### 登录网站后台
前往页面 `Modules->Payments->PingPongCheckout`
![image.png](/zencart/1629465534493-004c763c-8f10-4b14-b668-fb1ffcd7d3fa.png)

#### 安装并启用模块
选择模块`PingPongCheckout`，并点击安装
![image.png](/zencart/1629465589636-05ede39b-fb30-4200-850c-042ce15b678f.png)

#### 配置环境
按下面图片所示，配置支付所需的环境参数。
![image.png](/zencart/1629465797236-c80930dd-85e0-4550-9aed-e502bcb2e4c5.png)

#### 保存配置
![image.png](/zencart/1629465944926-5bb4e5c2-cfa4-4b82-8b72-656d4a963a86.png)

### 环境参数
#### 沙箱环境店铺参数
```ini:line-numbers title="config/sandbox.ini"
clientId: 2018092714313010016  # [!code focus]
accId: 2018092714313010016291  # [!code focus]
salt: F78BC96A55548B2319EE68E0  # [!code focus]
```
#### 沙箱环境测试卡号
```text:line-numbers title="config/test-cards.txt"
卡号：4200000000000000
有效期：12/22
cvv: 123
cvv需为3位纯数字
3DS交易卡：4711100000000000
```
####  环境地址
```text:line-numbers title="config/environment-urls.txt"
沙箱环境    https://sandbox-acquirer-payment.pingpongx.com
生产环境    https://acquirer-payment.pingpongx.com
```

### 对接过程
#### 沙箱环境对接

1. 按照文件安装插件。
1. 插件安装完成之后，需要进行支付自测，并完成以下事项：
- [ ] 截图输入卡号的页面
- [ ] 截图支付完成的最终跳转页面
- [ ] 将截图发送到对接群，并通知技术支持

安装过程，有任何问题可以在对接群里需求技术支持。

---

注意事项：
> 沙箱环境下，不会对持卡人发起扣款，支付之后发货将造成损失，不发货将持卡人可能会发起投诉。因此在对接期间，需要谨慎操作，对接测试通过之后，因立即关闭支付通道，等待生产环境上线之后打开。

---

#### 生产环境对接

1. 插件在技术支持下完成第一轮的沙箱环境对接后将进入，网站资料和账户审查阶段，通过之后，会发放生产环境参数。
1. 获取到生产参数之后，完成以下事项
- [ ] 将沙箱环境参数替换为生产参数。
- [ ] 自测支付，并完成截图
- [ ] 准备一个$1的商品链接。
3. 发送截图和商品链接，并通知技术支持，将由客户/技术支持对该商品链接发起真实交易测试。以验证对接结果和网站支付可用性。
3. 完成真实交易测试之后，需要商户发起退款，以便于验证退款流程。
3. 完成以上流程，网站对接结束，支付通道正式上线，支付可用。

### 生产环境配置
#### 审核过程
从对接群中或者商务/客户处获得通知，审核通过。
登录[商户后台](https://pay.pingpongx.com/aq/websiteList)
```text:line-numbers title="urls/merchant-backend.txt"
https://pay.pingpongx.com/aq/websiteList
```
#### 前往网站列表
如图所示，前往群组管理->查看详情->网站列表
#### 群组管理
> - ⚫  从菜单栏选择【网站管理】-【群组管理】进入群组管理页面
> - ⚫  该功能实现当前商户可点击“创建群组”新建群组;系统默认会给一个默认的群组
> - ⚫  网站下挂于群组。
> - ⚫  点击“查看详情”进入群组详情页面，可修改群组名称、查看复制 ID 号、查看群组下的网站。

![image.png](/zencart/1629468866673-c4edef47-9708-4141-959c-feab1b3f6c26-20210821003240351.png)
#### 选择网站
根据当前对接网站的域名，在列表中选择对应的网站
![image.png](/zencart/1629468928427-be88d189-e850-4479-a279-f853446fc371-20210821003248766.png)

#### 获取对应域名网站的accId
![image.png](/zencart/1629468994781-7e5ba639-38ca-4593-a6cb-a3d213d71bb0-20210821003259460.png)

#### 获取秘钥

> 从菜单栏选择【系统管理】-【秘钥管理】默认进入秘钥管理页，可在此页面查 看网站秘钥。
进入秘钥管理后，可查看所有网站对应的秘钥，点击“秘钥详情”查看具体秘
> 钥字段。
> 状态为“正常”的秘钥可使用，当状态为“异常”时，将无法使用可联系相关业务 人员处理。

![image.png](/zencart/1629469253929-79e2ba85-c8c9-460f-bb79-e6b9301ae557-20210821003307842.png)