PHP支付系统接口文档 - V2

前言

通用约定

线下场景支付域名：https://dm-pay.yinghuochongfu.cn

请求参数格式：JSON

*号后缀标识该字段必填

公共请求参数

• *sign // 签名
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号
• *terminal_id // 终端号
• client_ip // 客户端IP

签名方法

1. 过滤到提交参数值为空的内容
2. 参数名 按照 ascii 码 升序排列
3. 各参数格式化成 参数名=参数值 的形式
4. 用&符号拼接格式化后的各个参数 形成字符串 A
5. 在字符串 A 尾部拼接秘钥 key 形成新的字符串 B
6. 对字符串 B 进行 hash256 签名 最后把签名后的字符串统一转成大写

// PHP 示例代码
public static function buildSign(Array $params,String $secret): string
{
    unset($params['sign']);
    $params = array_filter($params);
    ksort($params);
    return strtoupper(\hash("sha256",http_build_query($params).$secret));
}

举例

提示：下面示例中的双引号和分号不参与签名过程，仅作为PHP代码示例遵循的语法，仅用于说明它是字符串。

<?php
// 演示数据
[
    "out_trade_no" => "03002205240094",
    "auth_code" => "282201336187471528",
    "serial_number" => "s1653300168304323",
    "total_amount" => "13.80",
    "mark" => ''
];
// 秘钥
"2da56645e89e7d7992e6af3bcc637808";

// 第一步 过滤空值字段
[
    "out_trade_no" => "03002205240094",
    "auth_code" => "282201336187471528",
    "serial_number" => "s1653300168304323",
    "total_amount" => "13.80",
];

// 第二步 键名排序
[
    "auth_code" => "282201336187471528",
    "out_trade_no" => "03002205240094",
    "serial_number" => "s1653300168304323",
    "total_amount" => "13.80",
];

// 第三四步 拼接成字符串
"auth_code=282201336187471528&out_trade_no=03002205240094&serial_number=s1653300168304323&total_amount=13.80";

// 第五步  末尾拼接秘钥
"auth_code=282201336187471528&out_trade_no=03002205240094&serial_number=s1653300168304323&total_amount=13.802da56645e89e7d7992e6af3bcc637808";

// 第六步 hash256
"8593fbb2cdc5fc5ca74cd2ee10e9297dd09f0090f066e5eaf2694fba8f7dae58";
// 最后转成大写
"8593FBB2CDC5FC5CA74CD2EE10E9297DD09F0090F066E5EAF2694FBA8F7DAE58";

一、B 扫 C 扫码支付

接口地址: /api/v2/pay/scan_pay

请求方式：POST

请求参数

• *sign // 签名
• *out_trade_no // 订单号
• *total_amount // 金额(元)
• *auth_code // 付款码
• *terminal_id // 终端ID
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号
• remarks // 备注
• notify_url // 通知地址。目前暂不支持回调

返回值

• out_trade_no //商户订单号
• trade_no //平台交易号
• total_amount //总金额(元)
• serial_number //序列号
• payment_method_code // 支付方式编码

  • alipay // 支付宝
  • wxpay // 微信支付
  • unionpay //云闪付
  • bankcard //银行卡

• status //支付状态

  • NOTPAY = 0; //未支付
  • USERPAYING = 1; //用户支付中
  • CLOSED = 2; //已关闭
  • SUCCESS = 3; //支付成功
  • PAYERROR = 4; //支付失败(其他原因，如银行返回失败)
  • REFUND_PART = 5; //部分退款
  • REFUND = 6; //已退款
  • REVOKED = 7; //已撤销(刷卡支付)
  • ACCEPT = 8; //已接收，等待扣款

• status_code //支付状态编码
• created_time //订单创建时间

二、C 扫 B 扫码支付

接口地址: /api/v2/pay/qr_pay

请求方式：POST

请求参数

• *sign // 签名
• *payment_code // 支付方式

  • alipay // 支付宝
  • wxpay // 微信

• *terminal_id // 终端ID
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号
• *out_trade_no // 订单号
• *total_amount // 金额(元)
• remarks // 备注
• notify_url// 通知地址。目前暂不支持回调
• code // 消费者小程序或公众号code

返回值

• out_trade_no //商户订单号
• trade_no //平台交易号
• total_amount //总金额(元)
• serial_number //序列号
• qr_url //支付 url
• payment_method_code // 支付方式编码

  • alipay // 支付宝
  • wxpay // 微信支付
  • unionpay //云闪付
  • bankcard //银行卡

• status //支付状态

  • NOTPAY = 0; //未支付
  • USERPAYING = 1; //用户支付中
  • CLOSED = 2; //已关闭
  • SUCCESS = 3; //支付成功
  • PAYERROR = 4; //支付失败(其他原因，如银行返回失败)
  • REFUND_PART = 5; //部分退款
  • REFUND = 6; //已退款
  • REVOKED = 7; //已撤销(刷卡支付)
  • ACCEPT = 8; //已接收，等待扣款

• status_code //支付状态编码
• created_time //订单创建时间

三、订单查询

接口地址: /api/v2/pay/order_query

请求方式：POST

请求参数

• *sign // 签名
• *trade_no // 平台交易号。两个单号二选一即可
• *out_trade_no // 商户订单号。两个单号二选一即可
• *terminal_id // 终端ID
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号

返回值

• out_trade_no //商户订单号
• trade_no //平台交易号
• total_amount //总金额(元)
• pay_amount //实际付款金额(元)
• serial_number //序列号
• payment_method_code // 支付方式编码

  • alipay // 支付宝
  • wxpay // 微信支付
  • unionpay //云闪付
  • bankcard //银行卡

• status // 支付状态

  • NOTPAY = 0; //未支付
  • USERPAYING = 1; //用户支付中
  • CLOSED = 2; //已关闭
  • SUCCESS = 3; //支付成功
  • PAYERROR = 4; //支付失败(其他原因，如银行返回失败)
  • REFUND_PART = 5; //部分退款
  • REFUND = 6; //已退款
  • REVOKED = 7; //已撤销(刷卡支付)
  • ACCEPT = 8; //已接收，等待扣款

• status_code //支付状态编码
• created_time //订单创建时间

四、退款

接口地址: /api/v2/pay/refund

请求方式：POST

请求参数

• *sign // 签名
• *trade_no // 平台订单号或渠道交易订单号
• *out_refund_no // 商户退款单号
• *terminal_id // 终端ID
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号
• *refund_password // 退款确认密码（6位数字）
• refund_amount // 退款金额，不填默认全额退款（单位：元）。目前暂不支持多次部分退款
• remarks // 备注
• notify_url// 通知地址。目前暂不支持回调

返回值

• out_refund_no //商户退款单号
• refund_no //平台退款交易号
• refund_amount //退款总金额(元)
• serial_number //序列号
• payment_method_code // 支付方式编码

  • alipay // 支付宝
  • wxpay // 微信支付
  • unionpay //云闪付
  • bankcard //银行卡

• status //支付状态

  • DEFAULT = 0; //未处理
  • PENDDING = 1; //处理中
  • SUCCESS = 2; //退款成功
  • REFUNDERROR = 3; //退款失败

• status_code //支付状态编码
• created_time //订单创建时间

五、退款查询

接口地址: /api/v2/pay/refund_query

请求方式：POST

请求参数

• *sign // 签名
• *terminal_id // 终端ID
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号
• *out_refund_no // 商户退款单号。两个单号二选一即可
• *refund_no // 平台退款交易号。两个单号二选一即可

返回值

• out_refund_no //商户退款单号
• refund_no //平台退款交易号
• refund_amount //退款总金额(元)
• serial_number //序列号
• payment_method_code // 支付方式编码

  • alipay // 支付宝
  • wxpay // 微信支付
  • unionpay //云闪付
  • bankcard //银行卡

• status //支付状态

  • DEFAULT = 0; //未处理
  • PENDDING = 1; //处理中
  • SUCCESS = 2; //退款成功
  • REFUNDERROR = 3; //退款失败

• status_code //支付状态编码
• created_time //订单创建时间

六、小程序支付

接口地址: /api/v2/pay/applet_pay

请求方式：POST

请求参数

• *sign // 签名
• *payment_code // 支付方式

  • alipay // 支付宝
  • wxpay // 微信

• *terminal_id // 终端ID
• *sub_version // 子版本号。固定值传100
• *merchant_no // 商户号
• *out_trade_no // 订单号
• *total_amount // 金额(元)
• remarks // 备注
• notify_url// 通知地址。目前暂不支持回调
• *code // 用户小程序code

返回值

• 返回微信/支付宝小程序相关支付参数

附录

更新记录

更新日期	更新内容	版本号	作者
2024.05.19	公共参数新增商户号等必填参数	v2.1.100	Freddy
2024.04.25	订单查询接口返回实际付款金额	v2.1.2	Freddy
2024.04.11	新增小程序支付接口	v2.1.1	Freddy
2024.04.11	删除无用接口	v2.1.0	Freddy
2023.11.22	终端概念抽象：使用终端ID替代序列号	v2.0.0	Freddy
2023.11.29	新增接口：交接班、终端信息	v2.0.1	Freddy
2023.11.30	交接班、终端接口更新	v2.0.2	Freddy
2023.12.02	交接班无需收银员登录、新增是否已签到接口	v2.0.3	Freddy
2023.12.04	交接班重构无需签到	v2.0.4	Freddy
2023.12.04	交接班：新增订单列表查询接口	v2.0.5	Freddy
2023.12.05	交接班：新增交班列表查询接口	v2.0.6	Freddy
2023.12.13	- 退款接口新增必填参数退款密码 - 新增公共字段上报地理位置信息	v2.1.0	Freddy

粤ICP备2023071642号