接口说明及规范V2

了解接口协议、签名算法与 V2 版本接入要求。

协议规则

• 提交数据格式：application/x-www-form-urlencoded
• 返回数据格式：JSON
• 字符编码：UTF-8
• 签名算法：SHA256WithRSA

V2 升级说明

• V2 接口全面使用 RSA 签名算法；V1 接口使用 MD5 签名算法
• V2 接口改用全新的接口地址，支持退款、代付等功能；V1 接口使用 submit.php 和 mapi.php 提交订单
• V2 接口新增 timestamp 入参和返回值用于校验时间戳

获取 RSA 密钥对

在 商户后台 -> 个人资料 -> API 信息 页面，点击【生成商户 RSA 密钥对】，生成后注意保存【商户私钥】。对接接口时只需要用到【平台公钥】与【商户私钥】。

旧版接口文档

查看 V1 旧版接口文档

签名规则V2

请求签名、返回验签及 RSA 密钥使用规范。

签名步骤

对本平台接口发起的请求，需要进行签名。

1. 获取请求报文所有非空 请求参数，不包括数组、字节类型参数，如文件、字节流，剔除 sign、sign_type 字段，并按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推。
2. 将排序后的参数和对应值，组合成"参数=参数值"的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串。
3. 使用商户私钥，对待签名字符串计算 RSA 签名（SHA256WithRSA），得到签名 sign。

验签步骤

针对接口返回的数据，以及异步通知回调的数据，需进行验签。

1. 先根据签名步骤里面的 1～2，获取到待签名字符串。
2. 使用平台公钥，根据签名字符串 sign，对待签名字符串进行 RSA 验签（SHA256WithRSA）。

注意事项

1. 商户私钥（private key）需填写到代码中供签名时使用。生成的私钥需妥善保管，避免遗失，不要泄露。
2. 平台公钥（public key）用于接口返回数据、异步通知回调数据的验签。
3. 具体发起支付相关流程的示例代码可下载 SDK 查看。

支付方式列表V2

平台标准支付方式调用值与名称对照。

实际可用的支付方式由平台及商户通道配置决定，以下为系统内置调用值。

页面跳转支付V2

通过表单或 URL 跳转到收银台完成支付。此接口可用于用户前台直接发起支付，使用 form 表单跳转或拼接成 url 跳转。

请求地址

https://pay.bestpurchase.cn/api/pay/submit

请求方式

POST 或 GET（推荐 POST，不容易被劫持）

请求参数说明

其他说明

• 支付方式（type）不传会跳转到收银台支付

统一下单接口V2

服务端创建支付订单并获取二维码或跳转地址。此接口可用于服务器后端发起支付请求，会返回支付二维码链接、支付跳转 url 等。

请求地址

https://pay.bestpurchase.cn/api/pay/create

请求方式

POST

请求参数说明

返回参数说明

返回示例

二维码：

{
  "code": 0,
  "trade_no": "20160806151343349",
  "pay_type": "qrcode",
  "pay_info": "weixin://wxpay/bizpayurl?pr=04IPMKM"
}

JSAPI：

{
  "code": 0,
  "trade_no": "20160806151343351",
  "pay_type": "jsapi",
  "pay_info": "{\"appId\":\"wx2421b1c4370ec43b\",\"timeStamp\":\"1395712654\",\"nonceStr\":\"e61463f8efa94090b1f366cccfbbb444\",\"package\":\"prepay_id=up_wx21201855730335ac86f8c43d1889123400\",\"signType\":\"RSA\",\"paySign\":\"oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\"}"
}

付款码（scan）：

{
  "code": 0,
  "trade_no": "2024072320222180092",
  "pay_type": "scan",
  "pay_info": "{\"type\":\"wxpay\",\"trade_no\":\"2024072320222180092\",\"api_trade_no\":\"4200002345202407238253501450\",\"buyer\":\"o9uAcc6VlZxhcujpKIqQuWWoDQc\",\"money\":\"1.00\"}"
}

微信小程序插件（wxplugin）：

{
  "code": 0,
  "trade_no": "2024072320222180018",
  "pay_type": "wxplugin",
  "pay_info": "{\"appId\":\"wxc237fd59fbb634ae\",\"supplierId\":\"123456\",\"shopId\":\"123456\",\"orderId\":\"2024072320222180092\"}"
}

APP拉起小程序（wxapp）：

{
  "code": 0,
  "trade_no": "2024072320222180018",
  "pay_type": "wxapp",
  "pay_info": "{\"appId\":\"wxbb48bac536053072\",\"miniProgramId\":\"gh_bf9cd8cf50b5\",\"path\":\"pages/fromAppPay/index?orderid=123456\",\"extraData\":\"\"}"
}

接口类型列表

设备类型列表

发起支付类型说明

其他说明

• 代码中需根据接口返回的 pay_type 值来展示具体的支付页面，例如扫码页面等。如果不懂怎么展示支付页面，可在 method 传入 jump，这样 pay_type 就只会返回 jump，直接跳转支付即可。
• 付款码支付可不传支付类型 type 字段，会根据 auth_code 的数字自动判断支付类型。
• 微信小程序插件支付，不同支付平台拉起支付方式不一样，可联系客服获取对接小程序插件的文档。
• APP 拉起微信小程序可参考 微信官方文档。

订单查询V2

根据平台订单号或商户订单号查询支付状态。

请求地址

https://pay.bestpurchase.cn/api/pay/query

请求方式

POST

请求参数说明

返回参数说明

支付状态列表

支付结果通知V2

处理服务器异步通知和页面跳转通知。

通知类型

服务器异步通知（notify_url）、页面跳转通知（return_url）

请求方式

GET

请求参数说明

返回内容说明

收到异步通知后，需返回 success 以表示服务器接收到了订单通知。

其他说明

• 商户系统代码内务必对返回的签名 sign 进行校验，并且判断 trade_status 的值是否等于 TRADE_SUCCESS。
• 支付平台可能会增加回调字段，验证签名时必须支持增加的扩展字段。

订单退款V2

对已支付订单发起全额或部分退款。需要先在商户后台开启订单退款 API 接口开关，才能调用该接口发起订单退款。

请求地址

https://pay.bestpurchase.cn/api/pay/refund

请求方式

POST

请求参数说明

返回参数说明

其他说明

• 少数插件对接的第三方平台不支持部分金额退款。

订单退款查询V2

查询退款请求的处理状态与退款金额。

请求地址

https://pay.bestpurchase.cn/api/pay/refundquery

请求方式

POST

请求参数说明

返回参数说明

关闭订单V2

关闭尚未完成支付的平台订单。

请求地址

https://pay.bestpurchase.cn/api/pay/close

请求方式

POST

请求参数说明

返回参数说明

其他说明

• 只有部分支付插件支持关闭订单操作。

查询商户信息V2

查询商户状态、支付权限及账户余额。

请求地址

https://pay.bestpurchase.cn/api/merchant/info

请求方式

POST

请求参数说明

返回参数说明

结算方式列表

查询订单列表V2

按时间和状态分页查询商户订单。查询订单列表可用于对账或同步订单状态等。

请求地址

https://pay.bestpurchase.cn/api/merchant/orders

请求方式

POST

请求参数说明

返回参数说明

转账发起V2

向支付宝、微信或银行卡账户发起转账。平台需开通代付功能，且在商户后台开启代付 API 接口开关，才能调用本接口发起转账。

请求地址

https://pay.bestpurchase.cn/api/transfer/submit

请求方式

POST

请求参数说明

返回参数说明

转账方式列表

其他说明

• 如果返回的转账状态 status=0，则需稍后调用转账查询接口查询转账状态。

转账查询V2

查询转账订单状态和处理结果。

请求地址

https://pay.bestpurchase.cn/api/transfer/query

请求方式

POST

请求参数说明

返回参数说明

可用余额查询V2

查询当前商户的代付可用余额。

请求地址

https://pay.bestpurchase.cn/api/transfer/balance

请求方式

POST

请求参数说明

返回参数说明

SDK 下载V2

下载 PHP SDK 与接口接入示例。

PHP-SDK

SDK.zip

版本：V2.0

文档概述V1

本文档为聚合支付平台 V1 接口开发文档，适用于使用 MD5 签名的旧版商户，包含接口规范、签名规则、支付方式、下单、查询、退款、回调通知等功能。建议新商户优先使用 V2 接口（RSA 签名）。

对接流程

1. 注册成为商户并创建应用，获取商户 ID（pid）和商户密钥（key）。
2. 阅读本接口文档并根据 SDK Demo 进行程序对接。
3. 接入测试账号进行支付、回调、查询、退款等测试。
4. 测试无误后，配置正式账号，进入上线运营。

接口基础地址

所有 V1 接口均基于以下域名：

https://pay.bestpurchase.cn/

版本信息

签名规范 (MD5)V1

确保请求的完整性和不可篡改。

签名过程

1. 将请求参数（除 sign 外）按参数名 字母升序 排序。
2. 如果参数值为空则不参与签名。
3. 以 URL 键值对格式拼接：参数1=值1&参数2=值2……
4. 在末尾拼接商户密钥：&key=商户密钥
5. 将拼接后的字符串进行 MD5 运算（32 位小写），得到签名值。

PHP 示例

/**
 * 生成签名
 * @param $params 参与签名的参数数组
 * @param $key 商户密钥
 * @return string
 */
function generateSign($params, $key){
    // 去除空值和 sign
    $params = array_filter($params, function($v){
        return $v !== '' && $v !== null;
    });
    if(isset($params['sign'])) unset($params['sign']);
    
    // 按字母升序排序
    ksort($params);
    
    // 拼接成 url 参数格式
    $query = http_build_query($params);
    $query .= '&key=' . $key;
    
    // md5 签名
    return md5($query);
}

/**
 * 验证签名
 */
function verifySign($params, $key){
    $sign = $params['sign'];
    $newSign = generateSign($params, $key);
    return $sign === $newSign;
}

注意事项

• sign_type 仅支持 MD5，可不传。
• 所有 POST 字段必须使用 http_build_query 或 x-www-form-urlencoded 编码格式提交。
• 务必在服务端校验 sign，否则可能造成支付伪造漏洞。

支付方式列表V1

在接口参数 type 中使用下表中的值。

API 发起支付V1

通过 POST 请求向平台提交订单，返回二维码链接或跳转 URL。

请求地址

https://pay.bestpurchase.cn/mapi.php

请求方式

POST application/x-www-form-urlencoded

请求参数说明

返回参数说明

返回示例：

{
  "code": 1,
  "msg": "success",
  "trade_no": "202401011234567890",
  "payurl": "https://pay.bestpurchase.cn/submit.php?trade_no=...",
  "code_url": "weixin://wxpay/bizpayurl?pr=abc",
  "sign": "abcd1234..."
}

页面跳转支付V1

构造表单跳转到平台支付页，由用户在网页内选择支付方式并完成支付。

请求地址

https://pay.bestpurchase.cn/submit.php

请求方式

GET / POST，推荐使用表单 POST 提交。

请求参数说明

HTML 表单示例

<form action="https://pay.bestpurchase.cn/submit.php" method="post">
<input type="hidden" name="pid" value="1001">
<input type="hidden" name="type" value="alipay">
<input type="hidden" name="out_trade_no" value="20160806151343349">
<input type="hidden" name="notify_url" value="http://www.pay.com/notify_url.php">
<input type="hidden" name="return_url" value="http://www.pay.com/return_url.php">
<input type="hidden" name="name" value="VIP会员">
<input type="hidden" name="money" value="1.00">
<input type="hidden" name="sign" value="...">
<input type="hidden" name="sign_type" value="MD5">
<input type="submit" value="立即支付">
</form>

支付结果通知V1

接收平台通知后完成业务处理。

通知方式

异步通知（notify_url）：平台服务器 GET 方式请求商户服务器，商户返回 success 即认为已接收。

页面跳转（return_url）：用户浏览器 GET 方式跳转，仅用于展示支付结果，不做业务凭据，实际业务应依赖异步通知。

通知参数

业务处理建议

• 异步通知收到后，先验证 sign，再验证 trade_status=TRADE_SUCCESS，再判断订单金额和订单号是否匹配，最后更新业务订单状态并返回 success。
• 对同一笔订单的多次回调，必须做幂等处理。

订单查询V1

查询订单状态，用于对账或补偿回调。

请求地址

https://pay.bestpurchase.cn/api.php?act=order

请求方式

GET / POST

请求参数说明

返回参数说明

订单退款V1

对已支付订单发起退款。

请求地址

https://pay.bestpurchase.cn/api.php?act=refund

请求方式

POST

请求参数说明

返回示例

{
  "code": 1,
  "msg": "退款成功",
  "trade_no": "20160806151343349",
  "out_trade_no": "20160806151343351",
  "refund_money": "1.00"
}

SDK 下载V1

下载 PHP SDK 与接口接入示例。

PHP-SDK

SDK.zip

版本：V1.0

包含：API 发起支付示例、页面跳转支付示例、支付通知处理示例、订单查询示例、订单退款示例。