拼拼WiFi自定义支付方式对接开发指南

为您的收费WiFi提供灵活的支付解决方案

概述：

拼拼WiFi默认的支付方式主要包括支付宝与微信支付。如希望使用其他的支付形式，或在用户支付时实现更丰富的互动，那么可以使用拼拼WiFi的"自定义支付方式"功能。

启用方法：

  1. 登录 拼拼WiFi后台，进入场所管理菜单，点击"设置"，进入场所设置页面。
  2. 在"支付设置"部分，将"支付方式"选择"自定义支付方式"，并填写自定义支付方式的相关选项。

选项说明：

选项名 说明
支付方式名称 主要用于在认证页面向用户展示支付方式
支付方式LOGO 主要用于在认证页面向用户展示支付方式
币种 用于设置收费价格的币种
密钥 用于自定义支付方式开发对接，例如支付状态回传时的签名
自定义支付链接 用户跳转至第三方系统付款页面，以完成支付或互动等业务逻辑
支付二维码提示文字 用户扫码支付时的提示文字

自定义支付业务流程：

用户有三种付费操作方式，相应的就有三种业务流程。三种流程下仅用户的操作方式有差异，对于第三方系统的对接都是相同的。
用户支付时，会跳转至自定义支付链接，即第三方系统的付款页面。
用户完成支付后，第三方系统必须回传支付状态给拼拼WiFi，并跳转拼拼WiFi的支付完成页面。

第1种流程 - 通过认证页面直接支付：
  1. 用户连接WiFi后打开认证页面后，选择付费套餐价格，选择自定义支付方式，并点击"确认"按钮。
  2. 页面跳转至"自定义支付链接"并附加一些参数，同时，系统自动开放临时上网权限（临时上网时长可在拼拼WiFi后台的场所设置页面中设置）。
  3. 用户在第三方系统中完成支付。
  4. 第三方系统向拼拼WiFi服务器回传用户支付状态。
  5. 页面跳转至拼拼WiFi的支付完成页面。
第2种流程 - 扫码支付：
  1. 用户打开认证页面后，选择付费套餐价格，选择"扫码支付"，并点击"确认"按钮。页面会展示付款二维码。
  2. 用户扫描二维码后进入付费页面，选择付费套餐价格，选择自定义支付方式，并点击"确认"按钮。
  3. 页面跳转至"自定义支付链接"并附加一些参数。注意，此操作方式下，系统不会开放临时上网权限。
  4. 用户在第三方系统中完成支付。
  5. 第三方系统向拼拼WiFi服务器回传用户支付状态。
  6. 页面跳转至拼拼WiFi的支付完成页面。
  7. 用户再次打开认证页面，输入上网码（支付完成页面中显示上网码），点击"确定"按钮。
第3种流程 - 用户手动操作支付：
  1. 用户连接WiFi后打开认证页面后，选择付费套餐价格，选择自定义支付方式，并点击"确认"按钮。
  2. 如果用户使用的是智能手机，系统会尝试将付款链接复制到系统剪切板，并在页面中提示用户可手动打开浏览器访问复制的链接。同时，系统自动开放临时上网权限（临时上网时长可在拼拼WiFi后台的场所设置页面中设置）
  3. 用户打开浏览器访问复制的链接，系统会自动跳转至"自定义支付链接"并附加一些参数。
  4. 用户在第三方系统中完成支付。
  5. 第三方系统向拼拼WiFi服务器回传用户支付状态。
  6. 页面跳转至拼拼WiFi的支付完成页面。
提示：可以通过自定义支付链接实现其他的支付操作体验。例如，页面跳转至"自定义支付链接"后，第三方系统的支付页面中可以要求用户输入手机号或电子信箱，然后将支付链接发送给用户；或者，用户观看一段广告后，可免费上网...

自定义支付链接的附加参数

用户从认证页面或扫码会跳转至自定义支付链接，跳转时传入若干URL参数。通过这个机制，可以将订单的相关信息记录在第三方系统中，也可以定制用户付款的逻辑与业务。例如，与第三方支付、网店、CRM等业务系统对接，或与用户互动等。传入的各个URL参数名及含义如下：

参数名 说明
hotspot_id 场所Hotspot ID
order_id 拼拼WiFi平台订单编号
voucher 拼拼WiFi平台订单关联的上网码
amount 订单金额
cur 币种
mac 用户设备MAC地址
rt_mac 路由器MAC地址
time_length 购买时长
time_length_type 购买时长类型。含义：1:分钟 2:小时 3:天 4:月 5:年
speed_download 下载速率限制
speed_upload 上传速率限制
client_num 最大允许同时使用人数
qrpay 用户扫码标志，含义：1:扫码支付；为空时:非扫码支付
createtime 订单创建时间，例如：2025-09-01 22:03:55
tz 订单创建时区，例如：UTC+8
url_part 支付状态回传地址前缀

回传用户支付状态

用户完成支付后，第三方系统必须及时向拼拼WiFi平台服务器回传用户的支付状态信息。回传通过HTTP POST请求进行（"Content-Type应为application/x-www-form-urlencoded），请求地址为：

<url_part>/cgi/custpaylistener/
例如：
http://cpx.wiwiz.com/ppwf/cgi/custpaylistener/

发送请求时，必须包含以下参数：

参数名 说明
ver 固定值 1.0
order_id 拼拼WiFi平台订单编号
trade_no 自定义业务编号，例如第三方系统中的的流水号、订单号，每笔订单应不同
trade_status 交易状态，固定值 1
sign 校验签名。签名规则：sha256(ver + order_id + trade_no + trade_status + custpay_key)。custpay_key为"启用方法"部分中的"密钥"

拼拼WiFi平台服务器接收到请求后，如一切正常，则返回正常响应：
{"code":"ok", "msg":""}
如发生错误，则返回异常响应：
{"code":"ng", "msg":"xxxxxx"}

注意：
如果拼拼WiFi平台已返回正常响应，请勿重复发送请求，否则可能引发屏蔽。
如果请求超时，则建议等待5秒后重新发送请求。
如果返回异常响应，则不应盲目重发请求，建议优先排障。

跳转至拼拼WiFi的支付完成页面

拼拼WiFi后台确认用户已支付后（即前述的返回正常响应{"code":"ok", "msg":""}），第三方系统的页面应跳转至拼拼WiFi的支付完成页面。跳转URL为：

<url_part>/cgi/chkorder/?id=<order_id>&qrpay=<qrpay>
例如：
http://cp.wiwiz.com/ppwf/cgi/chkorder/?id=123456&qrpay=1

示例下载

我们目前提供Java与PHP的示例程序，可从这里下载。