Home

Awesome

omnipay-99bill

Latest Version on Packagist Total Downloads Software License

基于Omnipay的快钱支付SDK

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

Quick Start 快速开始

依赖于Omnipay

PHP版本要求:PHP5.6+

Install 安装

通过 Composer 安装,可以运行:


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

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

开启沙盒调试模式

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

$gateway->setTestMode(true);

创建交易

业务字段说明

字段名是否必传说明
orderIdYes商户订单号,商户可以根据自己订单号的定义规则来定义该值
orderAmountYes订单金额,金额以“分”为单位,商户测试以1分测试即可,切勿以大金额测试。
payerNameNo支付人姓名
payerContactTypeNo支付人联系类型,1 代表电子邮件方式;2 代表手机联系方式
payerContactNo支付人联系方式,与payerContactType设置对应,payerContactType为1,则填写邮箱地址;payerContactType为2,则填写手机号码
productIdNo商品代码
productNameNo商品名称
productNumNo商品数量
productDescNo商品描述
ext1No扩展字段1,商户可以传递自己需要的参数,支付完快钱会原值返回
ext2No扩展字段2,商户可以传递自己需要的参数,支付完快钱会原值返回

网站端 - 发起支付代码

$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;

移动端 - 发起支付代码

$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;

支付回调

回调成功的业务参数

字段名说明
orderId商户订单号
orderAmount订单金额,金额以“分”为单位
orderTime订单交易创建时间
dealId快钱交易号
dealTime交易成功时间
payAmount实际交易金额,金额以“分”为单位
bankDealId银行交易号
bankId银行简码
fee手续费
bindMobile绑定的手机号
bindCard绑定的卡号
payType支付方式,详见快钱官方文档说明
ext1扩展字段1
ext2扩展字段2

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

回调验证代码(快钱回调方式为Get)

$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
}

查询交易支付状态

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

查询请求业务参数组合一

字段名是否必传说明
orderIdYes商户订单号
queryTypeNo查询方式默认为2,即根据商户订单号查询
requestPageNo在查询结果数据总量很大时,快钱会将支付结果分多次返回。本参数表示商户需要得到的记录集页码。默认为1,表示第1 页

查询请求业务参数组合二

字段名是否必传说明
queryTypeYes值固定为1,即根据日期查询
startTimeYes开始时间,数字串,一共14 位,格式为:年[4 位]月[2 位]日[2 位]时[2 位]分[2 位]秒[2位],例如:20071117020101
endTimeYes结束时间,数字串,一共14 位,格式为:年[4 位]月[2 位]日[2 位]时[2 位]分[2 位]秒[2位],例如:20071117020101
requestPageNo在查询结果数据总量很大时,快钱会将支付结果分多次返回。本参数表示商户需要得到的记录集页码。默认为1,表示第1 页

交易查询 - 实现代码


$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 这里为支付异常业务逻辑
}

订单网关退款

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

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

注意一:这里的商户号为不加01的商户号!!!

注意二:这里面的退款金额以人民币元为单位!!!

注意三:同一笔交易可以分多次退款,但是退款总金额不得超过订单支付总金额

退款请求业务参数

字段名是否必传说明
orderIdYes商户订单号
txOrderYes退款流水号,长度不超过50,英文和数字组成
amountYes退款金额,整数或小数位为两位,以人民币元为单位。
postdateYes退款提交时间,数字串,一共14 位,格式为:年[4 位]月[2 位]日[2 位]时[2 位]分[2 位]秒[2位],例如:20071117020101

退款成功业务参数

字段名说明
orderId商户订单号
txOrder退款流水号
amount退款金额

网关退款 - 实现代码

$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 这里为退款异常业务逻辑
}