x-class/omnipay-99bill

快钱支付SDK

omnipay-99bill

, _(*1)

基于Omnipay的快钱支付SDK, _(*2)

该文档共包含以下5个部分：
1、创建交易
2、支付回调
3、交易查询
4、网关退款, _(*3)

Quick Start 快速开始

依赖于Omnipay, _(*4)

PHP版本要求：PHP5.6+, _(*5)

Install 安装

通过 Composer 安装，可以运行：, _(*6)

$ composer require x-class/omnipay-99bill -vvv

注意：
关于商户号：快钱商家帐号需要联系快钱开通之后才能获取，如果商户号为10012138842，在项目中使用的商户号格式为"快钱商户号01"，如1001213884201，退款接口除外，需要的是不带01的格式。
关于密钥：自行根据快钱文档生成公钥和私钥，其中公钥上传到快钱，然后再从快钱下载官方秘钥放到项目当中，自己生成的私钥则用于创建支付时加密使用。
关于支付验证：支付成功后的同步回调和异步回调均为Get方式，需要对回调的参数进行验证，以确保是快钱官方的回调。
关于订单查询：订单交易状态查询接口除了商户号之外，还需要一个查询key，需要联系快钱的销售人员开通该功能，并获取对应的查询key.
关于退款：网关退款接口除了商户号之外，还需要一个退款key，需要联系快钱的销售人员开通该功能，并获取对应的退款key., _(*7)

开启沙盒调试模式

调试过程可以用如下代码开启沙盒环境，正式生产环境请去掉此代码。, _(*8)

$gateway->setTestMode(true);

创建交易

业务字段说明, _(*9)

网站端 - 发起支付代码, _(*10)

$gateway = \Omnipay\Omnipay::create('Bill99');
$gateway->setMchId('mch-id'); //商户号
$gateway->setPrivateKey('private_key'); //私钥内容，可以是文件路径，也可以是内容,如果是内容，保持全在同一行。
$gateway->setReturnUrl('https://www.example.com/return');//支付成功后同步跳转的url
$gateway->setNotifyUrl('https://www.example.com/notify');//支付成功后异步通知url

$request = $gateway->purchase([
    'orderId' => date('YmdHis') . mt_rand(1000, 9999),
    'orderAmount' => 1,
]);

$response = $request->send();
$response->redirect();
exit;

移动端 - 发起支付代码, _(*11)

$gateway = \Omnipay\Omnipay::create('Bill99');
$gateway->setMchId('mch-id'); //商户号
$gateway->setPrivateKey('private_key'); //私钥内容，可以是文件路径，也可以是内容,如果是内容，保持全在同一行。
$gateway->setReturnUrl('https://www.example.com/return');//支付成功后同步跳转的url
$gateway->setNotifyUrl('https://www.example.com/notify');//支付成功后异步通知url

$request = $gateway->wapPurchase([
    'orderId' => date('YmdHis') . mt_rand(1000, 9999),
    'orderAmount' => 1,
]);

$response = $request->send();
$response->redirect();
exit;

支付回调

回调成功的业务参数, _(*12)

说明：把自己的公钥上传到快钱之后，从快钱下载下来的密钥文件名类似"99bill[1].cert.rsa.20140803.cer"格式。, _(*13)

回调验证代码(快钱回调方式为Get), _(*14)

$gateway = Omnipay::create('Bill99');
$gateway->setMchId('mch-id'); //商户号
$gateway->setPublicKey('99bill_publickey'); //快钱下载的密钥内容，可以是文件路径，也可以是内容,如果是内容，保持全在同一行。
$request = $gateway->completePurchase();
$request->setParams(array_merge($_GET));//获取参数的方法可以用$_GET，也可以用某些框架自带的获取方法，总之要传入url中的Get参数

try {
    $response = $request->send();
    if ($response->isPaid()) {
        $data = $response->getData();//业务参数   

        // @todo 支付成功业务逻辑处理，根据返回的业务参数，修改数据库中对应的订单状态

        /** 这里需要注意，如果同步回调和同步回调（两者均为GET）在同一处处理，
         * 需要通过一定方式区分是异步还是同步，两者返回信息不同，如用户登录状态
         */

        //异步回调值，该返回值为快钱必需
        die($response->asyncResult(true,$redirectUrl)); //成功第一个参数为true，第二个参数为要跳转的url
        //同步回调
        // redirect跳转页面...
    } else {
       // @todo 支付失败的业务逻辑
       //异步回调值，该返回值为快钱必需
       die($response->asyncResult(false)); //失败只需要传入false
    }
} catch (Exception $e) {
    // @todo 这里为支付异常业务逻辑
    //异步回调值，该返回值为快钱必需
   die($response->asyncResult(false)); //失败只需要传入false
}

查询交易支付状态

如果因快钱故障或商户自己服务器故障，成功的交易导致回调失败，则可以用该方法进行查单，通过查单的结果进行数据库状态变更。, _(*15)

查询请求业务参数组合一, _(*16)

查询请求业务参数组合二, _(*17)

交易查询 - 实现代码, _(*18)

$gateway = \Omnipay\Omnipay::create('Bill99');
$gateway->setMchId('mch-id'); //商户号
$gateway->setQueryKey('query_key');//交易查询key

//查询方式一
$request = $gateway->query([
    'orderId'  => '201805261456145505',
]);

//查询方式二
/*
$request = $gateway->query([
    'queryType' => 1,
    'startTime' => '20180501000101',
    'endTime'   => '20180527000101',
]);
*/

try {
    $response = $request->send();
    if ($response->isSuccessful()) {
        $data=$response->getData();
        //@todo 支付成功业务逻辑处理，根据返回的业务参数，修改数据库中对应的订单状态
    }else{
        // @todo 这里为支付异常业务逻辑
    }
} catch (Exception $e) {
    // @todo 这里为支付异常业务逻辑
}

订单网关退款

如未开通网关退款，则需要登录快钱官方商家后台进行退款操作，开通网关退款之后，则可以直接调用此接口退款。, _(*19)

警告：此接口为无密退款，因此开发人员需要绝对保证操作后台安全，或加强退款安全验证机制，否则因安全系数太低导致的事故请自行承担。, _(*20)

注意一：这里的商户号为不加01的商户号！！！, _(*21)

注意二：这里面的退款金额以人民币元为单位！！！, _(*22)

注意三：同一笔交易可以分多次退款，但是退款总金额不得超过订单支付总金额, _(*23)

退款请求业务参数, _(*24)

退款成功业务参数, _(*25)

网关退款 - 实现代码, _(*26)

$gateway = \Omnipay\Omnipay::create('Bill99');
$gateway->setMchId('mch-id'); //商户号
$gateway->setRefundKey('refund_key');//退款key

$request = $gateway->refund([
    'orderId'  => 'P270000180502933093',
    'txOrder'  => date('YmdHis'),
    'amount'   => 0.01,
    'postdate' => date('YmdHis'),
]);

try {
    $response = $request->send();
    if ($response->isSuccessful()) {
        $data=$response->getData();
        // @todo 退款成功业务逻辑处理，根据返回的业务参数，修改数据库中对应的订单状态
    }else{
        // @todo 这里为退款异常业务逻辑
    }
} catch (Exception $e) {
    // @todo 这里为退款异常业务逻辑
}