javareact/easypay

支付宝支付、微信支付一行接入

2.1.3 2020-07-24 01:55 UTC

This package is auto-updated.

Last update: 2024-04-29 03:41:50 UTC


README

支付宝/微信支付/招商银行 支付/退款/转账/发红包/查账 一行接入

use Payment\Client\Charge;
use Payment\Common\PayException;

try {
    $str = Charge::run(支付类型, 配置文件, 支付数据);
} catch (PayException $e) {
    echo $e->errorMessage();
    exit;
}

目录

重要通知

  • 2020-7-22 自动过滤参数中的特殊字符,避免签名错误
  • 2020-7-8 兼容PHP7.4
  • 2020-5-14: 提醒:支付宝新增公钥证书方式,后续不再支持普通公钥方式,请注意升级

官方公告: https://opendocs.alipay.com/open/00ou7f?click_from=LETTER&_bdType=adchcdadbegcgbdiifbb&messageId=b2c0926f99ef0c90887eab9c044e12cb

  • 目前项目兼容支付宝公钥证书方式和普通公钥方式

EasyPay解决什么问题

EasyPay 的目的是简化大家在对接主流第三方时需要频繁去阅读第三方文档,还经常遇到各种问题。EasyPay 将所有第三方的接口进行了合理的建模分类,对大家提供统一的接入入口,大家只需要关注自身业务并且支付系统设计上。

目前已经集成:支付宝、微信、招商绝大部分功能。 贡献指南

如何使用

安装

当前 EasyPay 项目仅支持 PHP version > 7.0 的版本,并且仅支持通过 composer 进行安装。

需要 PHP 安装以下扩展:

- ext-curl
- ext-mbstring
- ext-bcmath
- package-Guzzle

composer安装方式:

直接在命令行下安装:

composer require "javareact/easypay:*"

通过项目配置文件方式安装:

"require": {
    "javareact/easypay": "*"
}

项目集成

参数选项说明:

  • Y: 必须
  • N: 非必须

支付宝

配置文件模板

$config = [
    'use_sandbox' => true, // 是否使用沙盒模式
    'app_id'    => '2016073100130857',
    'sign_type' => 'RSA2', // RSA  RSA2
    // 支付宝公钥字符串
    'ali_public_key' => '',
    // 自己生成的密钥字符串
    'rsa_private_key' => '',
    'limit_pay' => [
        //'balance',// 余额
        //'moneyFund',// 余额宝
        //'debitCardExpress',// 	借记卡快捷
        //'creditCard',//信用卡
        //'creditCardExpress',// 信用卡快捷
        //'creditCardCartoon',//信用卡卡通
        //'credit_group',// 信用支付类型(包含信用卡卡通、信用卡快捷、花呗、花呗分期)
    ], // 用户不可用指定渠道支付当有多个渠道时用“,”分隔

    // 与业务相关参数
    'notify_url' => 'https://test.cn/notify/ali',
    'return_url' => 'https://test.cn',
];

APP支付请求参数

对应channel: \EasyPay\Client::ALI_CHANNEL_APP

字段 解释 必须
amount 订单总金额,单位为元,精确到小数点后两位,取值范围[0.01,100000000] Y
goods_type 商品主类型 :0-虚拟类商品,1-实物类商品 Y
body 对一笔交易的具体描述信息。如果是多种商品,请将商品描述字符串累加传给body。 Y
subject 商品的标题/交易标题/订单标题/订单关键字等。 Y
product_code 销售产品码,商家和支付宝签约的产品码 N
trade_no 商户网站唯一订单号 N
promo_params 优惠参数 注:仅与支付宝协商后可用 N
return_params 公用回传参数,如果请求时传递了该参数,则返回给商户时会回传该参数。 N
extend_params 业务扩展参数 N
store_id 商户门店编号 N
ext_user_info 外部指定买家 N
business_params 商户传入业务信息,具体值要和支付宝约定,应用于安全,营销等参数直传场景,格式为json格式 N
time_expire 该笔订单允许的最晚付款时间,逾期将关闭交易。时间戳 N

条码支付请求参数

对应channel: \EasyPay\Client::ALI_CHANNEL_BAR

字段 解释 必须
trade_no 商户订单号,64个字符以内、可包含字母、数字、下划线;需保证在商户端不重复 Y
auth_code 支付授权码,2530开头的长度为1624位的数字,实际字符串长度以开发者获取的付款码长度为准 Y
amount 订单总金额,单位为元 Y
subject 订单标题 Y
body 订单描述 Y
scene 支付场景 条码支付,取值:bar_code(默认);声波支付,取值:wave_code N
product_code 销售产品码 N
buyer_id 买家的支付宝用户 id,如果为空,会从传入的码值信息中获取买家 ID N
seller_id 如果该值为空,则默认为商户签约账号对应的支付宝用户ID N
settle_currency 商户指定的结算币种,默认:CNY N
discountable_amount 参与优惠计算的金额,单位为元 N
goods_detail 订单包含的商品列表信息,json格式,其它说明详见商品明细说明 N
operator_id 商户操作员编号 N
store_id 商户门店编号 N
terminal_id 商户机具终端编号 N
extend_params 业务扩展参数 N
time_expire 该笔订单允许的最晚付款时间,逾期将关闭交易 N
auth_confirm_mode 预授权确认模式,授权转交易请求中传入,适用于预授权转交易业务使用,目前只支持PRE_AUTH(预授权产品码) N
terminal_params 商户传入终端设备相关信息,具体值要和支付宝约定 N
promo_params 优惠明细参数,通过此属性补充营销参数 N
advance_EasyPay_type 支付模式类型,若值为ENJOY_PAY_V2表示当前交易允许走先享后付2.0垫资 N

查询对账单请求参数

字段 解释 必须
bill_type 账单类型,默认是 trade N
bill_date 账单时间:日账单格式为yyyy-MM-dd Y

扫码支付请求参数

对应channel: \EasyPay\Client::ALI_CHANNEL_QR

字段 解释 必须
trade_no 商户订单号,64个字符以内、可包含字母、数字、下划线;需保证在商户端不重复 Y
seller_id 如果该值为空,则默认为商户签约账号对应的支付宝用户ID N
amount 订单总金额,单位为元 Y
discountable_amount 参与优惠计算的金额,单位为元 N
subject 订单标题 Y
goods_detail 订单包含的商品列表信息,json格式,其它说明详见商品明细说明 N
body 订单描述 Y
operator_id 商户操作员编号 N
store_id 商户门店编号 N
terminal_id 商户机具终端编号 N
extend_params 业务扩展参数 N
time_expire 该笔订单允许的最晚付款时间,逾期将关闭交易 N
settle_info 描述结算信息,json格式,详见结算参数说明 N
merchant_order_no 商户原始订单号,最大长度限制32位 N
business_params 商户传入业务信息,具体值要和支付宝约定,应用于安全,营销等参数直传场景,格式为json格式 N

手机网站支付请求参数

对应channel: \EasyPay\Client::ALI_CHANNEL_WAP

字段 解释 必须
body 对一笔交易的具体描述信息。如果是多种商品,请将商品描述字符串累加传给body。 Y
subject 商品的标题/交易标题/订单标题/订单关键字等。 Y
trade_no 商户网站唯一订单号 Y
time_expire 该笔订单允许的最晚付款时间,逾期将关闭交易,时间戳 N
amount 订单总金额,单位为元,精确到小数点后两位,取值范围[0.01,100000000] N
auth_token 针对用户授权接口,获取用户相关数据时,用于标识用户授权关系注:若不属于支付宝业务经理提供签约服务的商户,暂不对外提供该功能,该参数使用无效 N
goods_type 商品主类型:0—虚拟类商品,1—实物类商品 Y
return_params 公用回传参数,如果请求时传递了该参数,则返回给商户时会回传该参数 N
quit_url 添加该参数后在h5支付收银台会出现返回按钮,可用于用户付款中途退出并返回到该参数指定的商户网站地址。 N
promo_params 优惠参数注:仅与支付宝协商后可用 N
extend_params 业务扩展参数,详见下表的“业务扩展参数说明” N
store_id 商户门店编号 N
specified_channel 指定渠道,目前仅支持传入pcredit若由于用户原因渠道不可用,用户可选择是否用其他渠道支付。 N
business_params 商户传入业务信息,具体值要和支付宝约定,应用于安全,营销等参数直传场景,格式为json格式 N
ext_user_info 外部指定买家 N

电脑网站支付请求参数

对应channel: \EasyPay\Client::ALI_CHANNEL_WEB

字段 解释 必须
trade_no 商户网站唯一订单号 Y
amount 订单总金额,单位为元,精确到小数点后两位,取值范围[0.01,100000000] N
body 对一笔交易的具体描述信息。如果是多种商品,请将商品描述字符串累加传给body。 Y
subject 商品的标题/交易标题/订单标题/订单关键字等。 Y
time_expire 该笔订单允许的最晚付款时间,逾期将关闭交易,时间戳 N
goods_detail
return_params 公用回传参数,如果请求时传递了该参数,则返回给商户时会回传该参数 N
extend_params 业务扩展参数,详见下表的“业务扩展参数说明” N
goods_type 商品主类型:0—虚拟类商品,1—实物类商品 Y
promo_params 优惠参数注:仅与支付宝协商后可用 N
royalty_info 描述分账信息,json格式,详见分账参数说明 N
sub_merchant 间连受理商户信息体,当前只对特殊银行机构特定场景下使用此字段 N
store_id 商户门店编号 N
qr_pay_mode PC扫码支付的方式,支持前置模式和,默认是2 N
qrcode_width 商户自定义二维码宽度 N
settle_info 描述结算信息,json格式,详见结算参数说明 N
invoice_info 开票信息 N
agreement_sign_params 签约参数,支付后签约场景使用 N
integration_type 请求后页面的集成方式 N
request_from_url 请求来源地址。如果使用ALIAPP的集成方式,用户中途取消支付会返回该地址。 N
business_params 商户传入业务信息,具体值要和支付宝约定,应用于安全,营销等参数直传场景,格式为json格式 N
ext_user_info 外部指定买家 N

交易查询请求参数

字段 解释 必须
trade_no 订单支付时传入的商户订单号,和支付宝交易号不能同时为空。trade_no,transaction_id如果同时存在优先取transaction_id Y
transaction_id 支付宝交易号,和商户订单号不能同时为空 Y
query_options 查询选项,商户通过上送该字段来定制查询返回信息 N
org_pid 银行间联模式下有用,其它场景请不要使用 N

退款请求参数

字段 解释 必须
trade_no 订单支付时传入的商户订单号,和支付宝交易号不能同时为空。trade_no,transaction_id如果同时存在优先取transaction_id Y
transaction_id 支付宝交易号,和商户订单号不能同时为空 Y
refund_fee 需要退款的金额,该金额不能大于订单金额,单位为元,支持两位小数 Y
refund_currency 订单退款币种信息,默认 CNY N
reason 退款的原因说明 N
refund_no 标识一次退款请求,同一笔交易多次退款需要保证唯一,如需部分退款,则此参数必传。 Y
operator_id 商户的操作员编号 N
store_id 商户的门店编号 N
terminal_id 商户的终端编号 N
goods_detail 退款包含的商品列表信息,Json格式。其它说明详见:“商品明细说明” N
refund_royalty_parameters 退分账明细信息 N
org_pid 银行间联模式下有用,其它场景请不要使用 N

退款查询请求参数

字段 解释 必须
trade_no 订单支付时传入的商户订单号,和支付宝交易号不能同时为空。trade_no,transaction_id如果同时存在优先取transaction_id Y
transaction_id 支付宝交易号,和商户订单号不能同时为空 Y
refund_no 请求退款接口时,传入的退款请求号,如果在退款请求时未传入,则该值为创建交易时的外部交易号 Y
org_pid 银行间联模式下有用,其它场景请不要使用 N

关闭交易请求参数

字段 解释 必须
trade_no 订单支付时传入的商户订单号,和支付宝交易号不能同时为空 Y
transaction_id 该交易在支付宝系统中的交易流水号。最短 16 位,最长 64 位。和transaction_id不能同时为空,如果同时传了 transaction_id和 trade_no,则以 transaction_id为准 Y
operator_id 卖家端自定义的的操作员 ID N

取消交易请求参数

字段 解释 必须
trade_no 订单支付时传入的商户订单号,和支付宝交易号不能同时为空 Y
transaction_id 该交易在支付宝系统中的交易流水号。最短 16 位,最长 64 位。和transaction_id不能同时为空,如果同时传了 transaction_id和 trade_no,则以 transaction_id为准 Y

这个接口与 关闭交易 测试了一下,效果是一样的。具体场景不太清楚,但是官方文档描述是在当面付的时候使用

转账到支付宝请求参数

字段 解释 必须
trans_no 商户转账唯一订单号 Y
payee_type 收款方账户类型。默认:ALIPAY_LOGONID 详见 Y
payee_account 收款方账户。与payee_type配合使用 Y
amount 转账金额,单位:元。 Y
payer_show_name 付款方姓名 N
payee_real_name 收款方真实姓名 N
remark 转账备注 N

查询转账到支付宝请求参数

字段 解释 必须
trans_no 商户转账唯一订单号 Y
transaction_id 支付宝转账单据号:和商户转账唯一订单号不能同时为空。当和商户转账唯一订单号同时提供时,将用本参数进行查询,忽略商户转账唯一订单号。 Y

微信

对于每一个微信支持的能力,并不是所有参数都支持了,有些参数绝大多数场景并不需要用到。如果确实需要请自行对源码进行修改。

配置文件模板

$config = [
    'use_sandbox' => false, // 是否使用 微信支付仿真测试系统

    'app_id'       => 'wxxxxxxxx',  // 公众账号ID
    'sub_appid'    => 'wxxxxxxxx',  // 公众子商户账号ID
    'mch_id'       => '123123123', // 商户id
    'sub_mch_id'   => '123123123', // 子商户id
    'md5_key'      => '23423423dsaddasdas', // md5 秘钥
    'app_cert_pem' => 'apiclient_cert.pem',
    'app_key_pem'  => 'apiclient_key.pem',
    'sign_type'    => 'MD5', // MD5  HMAC-SHA256
    'limit_pay'    => [
        //'no_credit',
    ], // 指定不能使用信用卡支付   不传入,则均可使用
    'fee_type' => 'CNY', // 货币类型  当前仅支持该字段

    'notify_url' => 'https://test.cn/v1/notify/wx',

    'redirect_url' => 'https://test.cn/', // 如果是h5支付,可以设置该值,返回到指定页面
];

支付请求参数

对应channel: \EasyPay\Client::WX_CHANNEL_APP、WX_CHANNEL_BAR、WX_CHANNEL_LITE、WX_CHANNEL_PUB、WX_CHANNEL_QR、WX_CHANNEL_WAP

字段 解释 必须
subject 商品简单描述,该字段须严格按照规范传递,具体请见参数规定 Y
body 单品优惠字段(暂未上线) Y
trade_no 商户系统内部的订单号,32个字符内、可包含字母, 其他说明见商户订单号 Y
amount 订单总金额,单位为元 Y
client_ip 必须传正确的用户端IP,支持ipv4、ipv6格式,获取方式详见获取用户ip指引 Y
device_info 终端设备号(门店号或收银设备ID),注意:PC网页或公众号内支付请传"WEB" N
return_param 附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据 N
time_expire 订单失效时间,时间戳 N
goods_tag 商品标记,代金券或立减优惠功能的参数,说明详见代金券或立减优惠 N
scene_info 该字段用于上报支付的场景信息,具体见微信文档 N

使用时,自行使用上面的字段构建好一个数组,并传入到 \EasyPay\Client 实例对应的方法中。后面均是相同,不在重复。

账单请求参数

字段 解释 必须
bill_date 对账单日期 Y
bill_type ALL(默认值),返回当日所有订单信息(不含充值退款订单)SUCCESS,返回当日成功支付的订单(不含充值退款订单)REFUND,返回当日退款订单(不含充值退款订单) RECHARGE_REFUND,返回当日充值退款订单 N

关闭交易请求参数

字段 解释 必须
trade_no 商户系统内部订单号,要求32个字符内,且在同一个商户号下唯一。 Y

撤销交易请求参数

字段 解释 必须
trade_no 商户系统内部的订单号,transaction_id、trade_no二选一,如果同时存在优先级:transaction_id> trade_no Y
transaction_id 微信的订单号,优先使用 Y

退款请求参数

字段 解释 必须
transaction_id 微信生成的订单号,在支付通知中有返回 Y
trade_no 商户系统内部订单号,要求32个字符内,且在同一个商户号下唯一。transaction_id、trade_no二选一,如果同时存在优先级:transaction_id> trade_no Y
refund_no 商户系统内部的退款单号,商户系统内部唯一 ,同一退款单号多次请求只退一笔。 Y
total_fee 订单总金额,单位为元 Y
refund_fee 退款总金额,订单总金额,单位为元 Y
refund_desc 若商户传入,会在下发给用户的退款消息中体现退款原因 N
refund_account 仅针对老资金流商户使用 N

退款查询请求参数

字段 解释 必须
transaction_id 微信订单号查询的优先级是: refund_id > refund_no > transaction_id > trade_no Y
trade_no 商户系统内部订单号,要求32个字符内 ,且在同一个商户号下唯一。 Y
refund_no 商户系统内部的退款单号,商户系统内部唯一,同一退款单号多次请求只退一笔。 Y
refund_id 微信生成的退款单号,在申请退款接口有返回 Y
offset 偏移量,当部分退款次数超过10次时可使用,表示返回的查询结果从这个偏移量开始取记录 N

资金账单请求参数

字段 解释 必须
bill_date 下载对账单的日期,格式:20140603 Y
bill_type 账单的资金来源账户:Basic 基本账户 Operation 运营账户 Fees 手续费账户 Y

交易查询请求参数

字段 解释 必须
transaction_id 微信的订单号,建议优先使用 Y
trade_no 商户系统内部订单号,要求32个字符内 ,且在同一个商户号下唯一 Y

付款到零钱请求参数

字段 解释 必须
channel 付款的渠道 bank:付款到银行;account:付款到账号 Y
device_info 微信支付分配的终端设备号 N
trans_no 商户订单号,需保持唯一性(只能是字母或者数字,不能包含有其它字符) Y
openid 商户appid下,某用户的openid Y
check_name NO_CHECK:不校验真实姓名;FORCE_CHECK:强校验真实姓名 Y
re_user_name 收款用户真实姓名。如果check_name设置为FORCE_CHECK,则必填用户真实姓名 Y
amount 企业付款金额,单位为元 Y
desc 企业付款备注,必填。注意:备注中的敏感词会被转成字符* Y
client_ip 该IP同在商户平台设置的IP白名单中的IP没有关联,该IP可传用户端或者服务端的IP。 Y

付款到银行请求参数

字段 解释 必须
channel 付款的渠道 bank:付款到银行;account:付款到账号 Y
trans_no 商户订单号,需保持唯一性(只能是字母或者数字,不能包含有其它字符) Y
enc_bank_no 收款方银行卡号(采用标准RSA算法,公钥由微信侧提供),详见获取RSA加密公钥API Y
enc_true_name 收款方用户名(采用标准RSA算法,公钥由微信侧提供) Y
bank_code 银行卡所在开户行编号,详见银行编号列表 Y
amount 企业付款金额,单位为元 Y
desc 企业付款到银行卡付款说明,即订单备注 N

付款到零钱/银行查询请求参数

字段 解释 必须
trans_no 商户订单号,需保持唯一(只允许数字[09]或字母[AZ]和[a~z]最短8位,最长32位) Y

招商银行

配置文件模板

$config = [
    'use_sandbox' => true, // 是否使用 招商测试系统

    'branch_no' => 'xxx',  // 商户分行号,4位数字
    'mch_id'    => 'xxxx', // 商户号,6位数字
    'mer_key'   => 'xxxxxx', // 秘钥16位,包含大小写字母 数字

    // 招商的公钥,建议每天凌晨2:15发起查询招行公钥请求更新公钥。
    'cmb_pub_key' => 'xxxxx',

    'op_pwd'    => 'xxxxx', // 操作员登录密码。
    'sign_type' => 'SHA-256', // 签名算法,固定为“SHA-256”
    'limit_pay' => 'A', // 允许支付的卡类型,默认对支付卡种不做限制,储蓄卡和信用卡均可支付   A:储蓄卡支付,即禁止信用卡支付

    'notify_url' => 'https://test.cn/notify/cmb', // 支付成功的回调

    'sign_notify_url' => 'https://test.cn/notify/cmb', // 成功签约结果通知地址
    'sign_return_url' => 'https://test.cn', // 成功签约结果通知地址

    'return_url' => 'https://test.cn', // 如果是h5支付,可以设置该值,返回到指定页面
];

支付请求参数

字段 解释 必须
date 订单的日期,时间戳 Y
trade_no 订单号,6-32位的数字和字母组合,由商户生成 Y
amount 格式:xxxx.xx 固定两位小数,最大11位整数 Y
time_expire 过期时候的时间戳 Y
return_param 发送成功支付结果通知时,将原样返回商户 N
body 显示在PC端扫码支付页面,pc支付才需要该参数 N
client_ip 商户取得的客户IP,如果有多个IP用逗号”,”分隔。 N
sub_mch_id 当前订单为商户的二级商户的订单时需要传送 N
sub_mch_name 当前订单为商户的二级商户的订单时需要传送 N
sub_mch_tp_code 当前订单为商户的二级商户的订单时需要传送;必须为数字或字母 N
sub_mch_tp_name 当前订单为商户的二级商户的订单时需要传送 N
mode_type 默认不设限制,允许微信支付。 N
agr_no 客户协议号 N
merchant_serial_no 协议开通请求流水号,开通协议时必填。 N
user_id 用于标识商户用户的唯一ID N
mobile 手机号码 N
lon 经度 N
lat 纬度 N
risk_level 用户在商户系统内风险等级标识 N

查询公钥请求参数

不需要参数,直接条用即可

退款请求参数

字段 解释 必须
date 商户订单日期,支付时的订单日期 格式:yyyyMMdd Y
trade_no 商户订单号,支付时的订单号 Y
refund_no 退款流水号,商户生成,同一笔订单内,同一退款流水号只能退款一次。可用于防重复退款。 Y
refund_fee 退款金额,格式xxxx.xx,单位元 Y
reason 退款描述 N
operator_id 商户结账系统的操作员号,选填,若填了则会对操作员号和密码进行校验,若不填则不校验。 N

查询订单请求参数

字段 解释 必须
type 查询类型,A:按银行订单流水号查询(默认) B:按商户订单日期和订单号查询 N
transaction_id 银行订单流水号,type=A时必填 Y
date 商户订单日期,格式:yyyyMMdd Y
trade_no type=B时必填商户订单号 N
operator_id 商户结账系统的操作员号 N

已结账单请求参数

字段 解释 必须
mode 查询模式, bank:按照银行日期查询,默认; mch:按照商户日期查询 Y
start_time 开始日期,时间戳 Y
end_time 结束日期,时间戳 Y
operator_id 操作员号,商户结账系统的操作员号 Y
next_key_value 续传键值,长度只能为0或40;首次查询填“空”;后续查询,按应答报文中返回的nextKeyValue值原样传入。 N

退款查询请求参数

字段 解释 必须
type 查询类型 A:按银行退款流水号查单笔(默认) B:按商户订单号+商户退款流水号查单笔 C: 按商户订单号查退款 Y
trade_no 商户订单号 Y
date 商户订单日期,时间戳 Y
refund_no 商户退款流水号长度不超过20位 Y
bank_serial_no 银行退款流水号长度不超过20位 Y

对账单查询请求参数

字段 解释 必须
date 商户订单日期,时间戳 Y
message_key 交易流水,合作方内部唯一流水 Y

支持的接口

对应到第三方的具体接口

支付宝

微信

支持 普通商户与服务商两个版本

招商

第三方文档