<h1 align="center">Payment使用文档</h1>

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.

![Software license][ico-license] [![Latest development][ico-version-dev]][link-packagist] [![Monthly installs][ico-downloads-monthly]][link-downloads]

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

新版本文档如下

Stargazers over time

![Stargazers over time][starchart-cc]

联系&打赏

打赏名单

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

公告

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

重要通知

2019-04: 提醒：微信CA证书进行了更新，请更新项目到最新版本。否则5月29日后，将无法支付

官方公告： https://pay.weixin.qq.com/index.php/public/cms/content_detail?lang=zh&id=56602

计划

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

Payment

Install / Use

README