yatang/vendor/riverslei/payment

Payment使用文档

JetBrains OS licenses

payment had been being developed with PhpStorm under the free JetBrains Open Source license(s) granted by JetBrains s.r.o., hence I would like to express by thanks here.

老版本文档：http://helei112g.github.io/payment

新版本文档如下

Stargazers over time

---

联系&打赏

打赏名单

请大家使用时根据示例代码来，有bug直接提交 issue；提供付费技术支持。

目录

• 公告
  • 重要通知
  • 计划
• Payment解决什么问题
• 如何使用
  • 安装
  • 项目集成
  • 设计支付系统
  • 支持的接口
• 贡献指南
  • 代码设计
  • 接入支付指南
• 第三方文档
• License

公告

第三方支付的一些重要更新提示，以及项目相关的计划信息。

重要通知

1. 2019-04: 提醒：微信CA证书进行了更新，请更新项目到最新版本。否则5月29日后，将无法支付 > 官方公告： https://pay.weixin.qq.com/index.php/public/cms/content_detail?lang=zh&id=56602

计划

1. 2019/3/28 开始重构整个项目，doing... ... > 重构后的项目与 4.x 以前的版本不兼容，请使用者注意！

Payment解决什么问题

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

目前已经集成：支付宝、微信、招商绝大部分功能。也欢迎各位贡献代码。 贡献指南

如何使用

安装

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

需要 PHP 安装以下扩展：

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

composer安装方式：

直接在命令行下安装：

composer require "riverslei/payment:*"

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

"require": {
    "riverslei/payment": "*"
}

项目集成

按照上面的步骤完成安装后，即可在项目中使用。

对于整个过程，提供了唯一的入口类 \Payment\Client，每一个渠道，均只介绍 APP支付 与 异步/同步通知 该如何接入。会重点说明每个请求支持的参数。

APP支付demo

$config = [
    // 配置信息，各个渠道的配置模板见对应子目录
];

// 请求参数，完整参数见具体表格
$payData = [
    'body'         => 'test body',
    'subject'      => 'test subject',
    'trade_no'     => 'trade no',// 自己实现生成
    'time_expire'  => time() + 600, // 表示必须 600s 内付款
    'amount'       => '5.52', // 微信沙箱模式，需要金额固定为3.01
    'return_param' => '123',
    'client_ip'    => isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : '127.0.0.1', // 客户地址
];``

// 使用
try {
    $client = new \Payment\Client(\Payment\Client::WECHAT, $wxConfig);
    $res    = $client->pay(\Payment\Client::WX_CHANNEL_APP, $payData);
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    exit;
} catch (\Payment\Exceptions\GatewayException $e) {
    echo $e->getMessage();
    var_dump($e->getRaw());
    exit;
} catch (\Payment\Exceptions\ClassNotFoundException $e) {
    echo $e->getMessage();
    exit;
} catch (Exception $e) {
    echo $e->getMessage();
    exit;
}

异步/同步通知

// 自己实现一个类，继承该接口
class TestNotify implements \Payment\Contracts\IPayNotify
{
    /**
     * 处理自己的业务逻辑，如更新交易状态、保存通知数据等等
     * @param string $channel 通知的渠道，如：支付宝、微信、招商
     * @param string $notifyType 通知的类型，如：支付、退款
     * @param string $notifyWay 通知的方式，如：异步 async，同步 sync
     * @param array $notifyData 通知的数据
     * @return bool
     */
    public function handle(
        string $channel,
        string $notifyType,
        string $notifyWay,
        array $notifyData
    ) {
        //var_dump($channel, $notifyType, $notifyWay, $notifyData);exit;
        return true;
    }
}

$config = [
    // 配置信息，各个渠道的配置模板见对应子目录
];

// 实例化继承了接口的类
$callback = new TestNotify();

try {
    $client = new \Payment\Client(\Payment\Client::ALIPAY, $config);
    $xml = $client->notify($callback);
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    exit;
} catch (\Payment\Exceptions\GatewayException $e) {
    echo $e->getMessage();
    exit;
} catch (\Payment\Exceptions\ClassNotFoundException $e) {
    echo $e->getMessage();
    exit;
} catch (Exception $e) {
     echo $e->getMessage();
     exit;
 }

从上面的例子简单总结下，所有的支持的能力，通过 \Payment\Client 对外暴露方法；所有需要的常量也在这个类中进行了定义。其次需要一个 $config，关于config的模板，在每个渠道下面去看。最后一个传入请求的参数，完整的参数会在每个渠道中列出来，需要说明的是这些参数名字根据第三方文档部分进行了改写。在使用的时候请注意。

参数选项说明：

• 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://dayutalk.cn/notify/ali',
    'return_url' => 'https://dayutalk.cn',
];

APP支付请求参数

对应channel： \Payment\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： \Payment\Client::ALI_CHANNEL_BAR

字段	解释	必须
trade_no	商户订单号,64个字符以内、可包含字母、数字、下划线；需保证在商户端不重复	Y
auth_code	支付授权码，25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准	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_payment_type	支付模式类型,若值为ENJOY_PAY_V2表示当前交易允许走先享后付2.0垫资	N

查询对账单请求参数

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

扫码支付请求参数

对应channel： \Payment\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： \Payment\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： \Payment\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://dayutalk.cn/v1/notify/wx',

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

支付请求参数

对应channel： \Payment\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

使用时，自行使用上面的字段构建好一个数组，并传入到 \Payment\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	商户订单号，需保持唯一（只允许数字[0~9]或字母[A~Z]和[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://dayutalk.cn/notify/cmb', // 支付成功的回调

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

    'return_url' => 'https://dayutalk.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

设计支付系统

Payment 解决了对接第三方渠道的各种问题，但是一个合理的支付完整系统该如何设计？估计大家还有很多疑问。关于支付系统的设计大家可以参考该项目：https://github.com/skr-shop/manuals

这是我与小伙伴开源的另外一个关于电商的项目，里边对电商的各个模块设计进行了详细的描述。

支持的接口

对应到第三方的具体接口

支付宝

• 条码支付
• 扫码支付
• APP支付
• H5支付
• 电脑网站支付
• 退款
• 关闭交易
• 撤销交易 条码/扫码支付会用到
• 交易查询
• 退款查询
• 下载对账单
• 转账到支付宝
• 支付宝转账查询
• 交易创建 条码/扫码支付会用到

微信

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

• 付款码支付
• JSAPI支付
• Native支付
• APP支付
• H5支付
• 小程序支付
• 退款
• 关闭交易
• 撤销交易
• 交易查询
• 退款查询
• 下载对账单
• 下载资金账单
• 转账到银行卡 该接口还有些问题待处理
• 转账到微信零钱
• 银行转账查询
• 微信转账查询

招商

• APP支付
• H5支付
• PC扫码支付
• 二维码支付
• 退款
• 交易查询
• 退款查询
• 查询协议
• 取消协议
• 查询入账明细
• 下载退款对账单
• 下载已结账单for商户
• 下载已结账单for银行
• 下载对账单
• 查询招行公钥

贡献指南

代码设计

整个代码结构的设计，待补充

开发指南

接入一个新的能力该如何操作，待补充

第三方文档

• 支付宝
• 微信
• 招商银行

License

The code for Payment is distributed under the terms of the MIT license (see LICENSE).