本项目的官方GitHub地址是 https://github.com/beecloud/beecloud-php

本SDK 基于 BeeCloud RESTful API

依赖:PHP 5.3+, PHP-curl

1. BeeCloud注册账号
2. BeeCloud中创建应用，填写支付渠道所需参数

使用中遇到的问题欢迎来QQ群-321545822提问

###使用composer 在你的composer.json中添加如下依赖

{
  {
  "require": {
    "beecloud.cn/rest": "{version}"
  }
}

其中composer支持需要version>=v2.2.0
version ＝ dev-master为主干分支开发版本,请酌情使用

然后命令行执行

composer install

在需要使用的php文件中使用 Composer 的 autoload 引入

require_once('vendor/autoload.php');

###手动使用 适合不能使用composer（PHP < 5.3.2）或者namespace(PHP < 5.3)的情况 拷贝当前所有文件（demo可以忽略）到你指定的目录下，你的代码中

require_once("<YourPath>/loader.php");

####原有使用v2.2.0以下的用户和不使用namespace的用户则请修改为

require_once("<YourPath>/degrade/beecloud.php");	

$data参数和返回参数请参考BeeCloud RESTfull API,同时可以参考demo中各渠道的代码示例）

1. 发起支付订单

   \beecloud\rest\api::bill(array $data);
   

   不使用namespace的用户和2.2.0之前的v2版本用户请使用

   BCRESTApi::bill(array $data);
   

   data参数（array类型）:

   参数名	类型	含义	描述	例子	是否必填
   app_id	String	BeeCloud平台的AppID	App在BeeCloud平台的唯一标识	0950c062-5e41-44e3-8f52-f89d8cf2b6eb	是
   timestamp	Long	签名生成时间	时间戳，毫秒数	1435890533866	是
   app_sign	String	加密签名	算法: md5(app_id+timestamp+app_secret)，32位16进制格式,不区分大小写	b927899dda6f9a04afc57f21ddf69d69	是
   channel	String	渠道类型	根据不同场景选择不同的支付方式	WX_APP、WX_NATIVE、WX_JSAPI、ALI_APP、ALI_WEB、ALI_QRCODE、ALI_OFFLINE_QRCODE、ALI_WAP、UN_APP、UN_WEB、JD_WAP、JD_WEB、YEE_WAP、YEE_WEB、KUAIQIAN_WAP、KUAIQIAN_WEB、BD_WAP、BD_WEB(详见附注）	是
   total_fee	Integer	订单总金额	必须是正整数，单位为分	1	是
   bill_no	String	商户订单号	8到32位数字和/或字母组合，请自行确保在商户系统中唯一，同一订单号不可重复提交，否则会造成订单重复	201506101035040000001	是
   title	String	订单标题	UTF8编码格式，32个字节内，最长支持16个汉字	白开水	是
   optional	Map	附加数据	用户自定义的参数，将会在webhook通知中原样返回，该字段主要用于商户携带订单的自定义数据	{"key1":"value1","key2":"value2",...}	否
   return_url	String	同步返回页面	支付渠道处理完请求后,当前页面自动跳转到商户网站里指定页面的http路径	beecloud.cn/returnUrl.jsp	当channel参数为 ALI_WEB 或 ALI_QRCODE 或 UN_WEB时为必填

   注：channel的参数值含义：
   WX_APP: 微信手机原生APP支付
   WX_NATIVE: 微信公众号二维码支付
   WX_JSAPI: 微信公众号支付
   ALI_APP: 支付宝手机原生APP支付
   ALI_WEB: 支付宝PC网页支付
   ALI_QRCODE: 支付宝内嵌二维码支付
   ALI_OFFLINE_QRCODE: 支付宝线下二维码支付
   ALI_WAP: 支付宝移动网页支付
   UN_APP: 银联手机原生APP支付
   UN_WEB: 银联PC网页支付
   JD_WAP: 京东移动网页支付
   JD_WEB: 京东PC网页支付
   YEE_WAP: 易宝移动网页支付
   YEE_WEB: 易宝PC网页支付
   KUAIQIAN_WAP: 快钱移动网页支付
   KUAIQIAN_WEB: 快钱PC网页支
   BD_WAP: 百度移动网页支付
   BD_WEB: 百度PC网页支付

   • 以下是微信公众号支付(WX_JSAPI)的**必填**参数

   参数名	类型	含义	例子
   openid	String	用户相对于微信公众号的唯一id	0950c062-5e41-44e3-8f52-f89d8cf2b6eb

   • 以下是支付宝网页支付(ALI_WEB)的**选填**参数

   参数名	类型	含义	例子
   show_url	String	商品展示地址以http://开头	http://beecloud.cn

   • 以下是支付宝内嵌二维码支付(ALI_QRCODE)的**选填**参数

   参数名	类型	含义	例子
   qr_pay_mode	String	二维码类型	0,1,3

   注： 二维码类型含义
   0： 订单码-简约前置模式, 对应 iframe 宽度不能小于 600px, 高度不能小于 300px
   1： 订单码-前置模式, 对应 iframe 宽度不能小于 300px, 高度不能小于 600px
   3： 订单码-迷你前置模式, 对应 iframe 宽度不能小于 75px, 高度不能小于 75px

   返回结果（Object类型）:

   • 公共返回参数

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息，OK为正常
   err_detail	String	具体错误信息

   • 公共返回参数取值及含义参见支付公共返回参数部分, 以下是退款所特有的

   result_code	result_msg	含义
   8	NO_SUCH_BILL	没有该订单
   9	BILL_UNSUCCESS	该订单没有支付成功
   10	REFUND_EXCEED_TIME	已超过可退款时间
   11	ALREADY_REFUNDING	该订单已有正在处理中的退款
   12	REFUND_AMOUNT_TOO_LARGE	提交的退款金额超出可退额度
   13	NO_SUCH_REFUND	没有该退款记录

   当channel为ALI_APP、ALI_WEB、ALI_QRCODE时，以下字段在result_code为0时有返回

   参数名	类型	含义
   url	String	支付宝退款地址，需用户在支付宝平台上手动输入支付密码处理

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息， OK为正常
   err_detail	String	具体错误信息

   • 公共返回参数取值列表及其含义

   result_code	result_msg	含义
   0	OK	调用成功
   1	APP_INVALID	根据app_id找不到对应的APP或者app_sign不正确
   2	PAY_FACTOR_NOT_SET	支付要素在后台没有设置
   3	CHANNEL_INVALID	channel参数不合法
   4	MISS_PARAM	缺少必填参数
   5	PARAM_INVALID	参数不合法
   6	CERT_FILE_ERROR	证书错误
   7	CHANNEL_ERROR	渠道内部错误
   14	RUN_TIME_ERROR	实时未知错误，请与技术联系帮助查看

   当result_code不为0时，如需详细信息，请查看err_detail字段

   以下字段在result_code为0时有返回

   • WX_APP

   参数名	类型	含义
   app_id	String	微信应用APPID
   partner_id	String	微信支付商户号
   package	String	微信支付打包参数
   nonce_str	String	随机字符串
   timestamp	String	当前时间戳，单位是毫秒，13位
   pay_sign	String	签名值
   prepay_id	String	微信预支付id

   • WX_NATIVE

   参数名	类型	含义
   code_url	String	二维码地址

   • WX_JSAPI

   参数名	类型	含义
   app_id	String	微信应用APPID
   package	String	微信支付打包参数
   nonce_str	String	随机字符串
   timestamp	String	当前时间戳，单位是毫秒，13位
   pay_sign	String	签名
   sign_type	String	签名类型，固定为MD5

   • ALI_APP

   参数名	类型	含义
   order_string	String	支付宝签名串

   • ALI_WEB

   参数名	类型	含义
   html	String	支付宝跳转form，是一段HTML代码，自动提交
   url	String	支付宝跳转url，推荐使用html

   • ALI_OFFLINE_QRCODE

   参数名	类型	含义
   qr_code	String	二维码码串,可以用二维码生成工具根据该码串值生成对应的二维码

   • ALI_QRCODE

   参数名	类型	含义
   html	String	支付宝跳转form，是一段HTML代码，自动提交
   url	String	支付宝内嵌二维码地址，是一个URL

   • UN_APP

   参数名	类型	含义
   tn	String	银联支付ticket number

   • UN_WEB、JD_WAP、JD_WEB、KUAIQIAN_WAP、KUAIQIAN_WEB

   参数名	类型	含义
   html	String	支付页自动提交form表单内容

   • YEE_WAP、YEE_WEB、BD_WAP、BD_WEB

   参数名	类型	含义
   url	String	支付页跳转地址

2. 查询支付订单

   \beecloud\rest\api::bills(array $data);
   

   不使用namespace的用户和2.2.0之前的v2版本用户请使用

   BCRESTApi::bills(array $data);
   

   data参数（array类型）:

   参数名	类型	含义	描述	例子	是否必填
   app_id	String	BeeCloud应用APPID	BeeCloud的唯一标识	0950c062-5e41-44e3-8f52-f89d8cf2b6eb	是
   timestamp	Long	签名生成时间	时间戳，毫秒数	1435890533866	是
   app_sign	String	加密签名	算法: md5(app_id+timestamp+app_secret)，32位16进制格式,不区分大小写	b927899dda6f9a04afc57f21ddf69d69	是
   channel	String	渠道类型	根据不同场景选择不同的支付方式	WX、WX_APP、WX_NATIVE、WX_JSAPI、ALI、ALI_APP、ALI_WEB、ALI_QRCODE、ALI_OFFLINE_QRCODE、ALI_WAP、UN、UN_APP、UN_WEB、JD_WAP、JD_WEB、YEE_WAP、YEE_WEB、KUAIQIAN_WAP、KUAIQIAN_WEB、BD_WAP、BD_WEB、JD、YEE、KUAIQIAN、BD(详见附注）	否
   bill_no	String	商户订单号	发起支付时填写的订单号	201506101035040000001	否
   start_time	Long	起始时间	毫秒时间戳, 13位	1435890530000	否
   end_time	Long	结束时间	毫秒时间戳, 13位	1435890540000	否
   skip	Integer	查询起始位置	默认为0. 设置为10表示忽略满足条件的前10条数据	0	否
   limit	Integer	查询的条数	默认为10，最大为50. 设置为10表示只返回满足条件的10条数据	10	否

   注：

   1. bill_no, trace_id, start_time, end_time等查询条件互相为**且**关系
   2. start_time, end_time指的是订单生成的时间，而不是订单支付的时间

   返回结果（Object类型）:

   • 公共返回参数

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息， OK为正常
   err_detail	String	具体错误信息
   count	Integer	查询订单结果数量
   bills	List	订单列表

   公共返回参数取值及含义参见支付公共返回参数部分

   • bills说明，每个Map的key-value

   参数名	类型	含义
   bill_no	String	订单号
   total_fee	Integer	订单金额，单位为分
   channel	String	WX、WX_NATIVE、WX_JSAPI、WX_APP、ALI、ALI_APP、ALI_WEB、ALI_QRCODE、ALI_OFFLINE_QRCODE、ALI_WAP、UN、UN_APP、UN_WEB(详见 1. 支付 附注）
   title	String	订单标题
   spay_result	Bool	订单是否成功
   created_time	Long	订单创建时间, 毫秒时间戳, 13位

3. 发起退款

   \beecloud\rest\api::refund(array $data);
   

   不使用namespace的用户和2.2.0之前的v2版本用户请使用

   BCRESTApi::refund(array $data);
   

   data参数（array类型）:

   参数名	类型	含义	描述	例子	是否必填
   app_id	String	BeeCloud应用APPID	BeeCloud的唯一标识	0950c062-5e41-44e3-8f52-f89d8cf2b6eb	是
   timestamp	Long	签名生成时间	时间戳，毫秒数	1435890533866	是
   app_sign	String	加密签名	算法: md5(app_id+timestamp+app_secret)，32位16进制格式,不区分大小写	b927899dda6f9a04afc57f21ddf69d69	是
   channel	String	渠道类型	根据不同渠道选不同的值	WX ALI UN KUAIQIAN YEE JD BD	否
   refund_no	String	商户退款单号	格式为:退款日期(8位) + 流水号(3~24 位)。请自行确保在商户系统中唯一，且退款日期必须是发起退款的当天日期,同一退款单号不可重复提交，否则会造成退款单重复。流水号可以接受数字或英文字符，建议使用数字，但不可接受“000”	201506101035040000001	是
   bill_no	String	商户订单号	发起支付时填写的订单号	201506101035040000001	是
   refund_fee	Integer	退款金额	必须为正整数，单位为分，必须小于或等于对应的已支付订单的total_fee	1	是
   optional	Map	附加数据	用户自定义的参数，将会在webhook通知中原样返回，该字段主要用于商户携带订单的自定义数据	{"key1":"value1","key2":"value2",...}	否

   返回结果（Object类型）:

   • 公共返回参数

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息，OK为正常
   err_detail	String	具体错误信息

   • 公共返回参数取值及含义参见支付公共返回参数部分, 以下是退款所特有的

   result_code	result_msg	含义
   8	NO_SUCH_BILL	没有该订单
   9	BILL_UNSUCCESS	该订单没有支付成功
   10	REFUND_EXCEED_TIME	已超过可退款时间
   11	ALREADY_REFUNDING	该订单已有正在处理中的退款
   12	REFUND_AMOUNT_TOO_LARGE	提交的退款金额超出可退额度
   13	NO_SUCH_REFUND	没有该退款记录

   当channel为ALI_APP、ALI_WEB、ALI_QRCODE时，以下字段在result_code为0时有返回

   参数名	类型	含义
   url	String	支付宝退款地址，需用户在支付宝平台上手动输入支付密码处理

4. 退款状态查询

   \beecloud\rest\api::refunds(array $data);
   

   不使用namespace的用户和2.2.0之前的v2版本用户请使用

   BCRESTApi::refunds(array $data);
   

   data参数（array类型）:

   参数名	类型	含义	描述	例子	是否必填
   app_id	String	BeeCloud应用APPID	BeeCloud的唯一标识	0950c062-5e41-44e3-8f52-f89d8cf2b6eb	是
   timestamp	Long	签名生成时间	时间戳，毫秒数	1435890533866	是
   app_sign	String	加密签名	算法: md5(app_id+timestamp+app_secret)，不区分大小写	b927899dda6f9a04afc57f21ddf69d69	是
   channel	String	渠道类型	根据不同场景选择不同的支付方式	WX、WX_APP、WX_NATIVE、WX_JSAPI、ALI、ALI_APP、ALI_WEB、ALI_QRCODE、ALI_OFFLINE_QRCODE、ALI_WAP、UN、UN_APP、UN_WEB、JD_WAP、JD_WEB、YEE_WAP、YEE_WEB、KUAIQIAN_WAP、KUAIQIAN_WEB、BD_WAP、BD_WEB、JD、YEE、KUAIQIAN、BD(详见附注）	否
   bill_no	String	商户订单号	发起支付时填写的订单号	201506101035040000001	否
   refund_no	String	商户退款单号	发起退款时填写的退款单号	201506101035040000001	否
   start_time	Long	起始时间	毫秒时间戳, 13位	1435890530000	否
   end_time	Long	结束时间	毫秒时间戳, 13位	1435890540000	否
   skip	Integer	查询起始位置	默认为0. 设置为10，表示忽略满足条件的前10条数据	0	否
   limit	Integer	查询的条数	默认为10，最大为50. 设置为10，表示只查询满足条件的10条数据	10	否

   注：

   1. bill_no, refund_no, start_time, end_time等查询条件互相为**且**关系.
   2. start_time, end_time指的是订单生成的时间，而不是订单支付的时间.

   返回结果（Object类型）:

   • 公共返回参数

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息， OK为正常
   err_detail	String	具体错误信息
   count	Integer	查询退款结果数量
   refunds	List	退款列表

   公共返回参数取值及含义参见支付公共返回参数部分

   • refunds说明，每个Map的key-value

   参数名	类型	含义
   bill_no	String	订单号
   refund_no	String	退款号
   total_fee	Integer	订单金额，单位为分
   refund_fee	Integer	退款金额，单位为分
   title	String	订单标题
   channel	String	WX、WX_APP、WX_NATIVE、WX_JSAPI、ALI、ALI_APP、ALI_WEB、ALI_QRCODE、ALI_OFFLINE_QRCODE、ALI_WAP、UN、UN_APP、UN_WEB、JD_WAP、JD_WEB、YEE_WAP、YEE_WEB、KUAIQIAN_WAP、KUAIQIAN_WEB、BD_WAP、BD_WEB、JD、YEE、KUAIQIAN、BD(详见 1. 支付 附注）
   finish	bool	退款是否完成
   result	bool	退款是否成功
   created_time	Long	退款创建时间, 毫秒时间戳, 13位

5. 退款状态更新(仅微信需要)

   \beecloud\rest\api::refundStatus(array $data);
   

   不使用namespace的用户和2.2.0之前的v2版本用户请使用

   BCRESTApi::refundStatus(array $data);
   

   data参数（array类型）:

   参数名	类型	含义	描述	例子	是否必填
   app_id	String	BeeCloud应用APPID	BeeCloud的唯一标识	0950c062-5e41-44e3-8f52-f89d8cf2b6eb	是
   timestamp	Long	签名生成时间	时间戳，毫秒数	1435890533866	是
   app_sign	String	加密签名	算法: md5(app_id+timestamp+app_secret)，32位16进制格式，不区分大小写	b927899dda6f9a04afc57f21ddf69d69	是
   channel	String	渠道类型	根据不同场景选择不同的支付方式	目前只支持WX	是
   refund_no	String	商户退款单号	发起退款时填写的退款单号	201506101035040000001	是

   返回结果（Object类型）:

   • 公共返回参数

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息， OK为正常
   err_detail	String	具体错误信息
   refund_status	String	退款状态

   公共返回参数取值及含义参见支付公共返回参数部分

6. 批量打款

   \beecloud\rest\api::transfers(array $data);
   

   不使用namespace的用户和2.2.0之前的v2版本用户请使用

   BCRESTApi::transfers(array $data);
   

   data参数（array类型）:

   参数名	类型	含义	描述	例子	是否必填
   app_id	String	BeeCloud应用APPID	BeeCloud的唯一标识	0950c062-5e41-44e3-8f52-f89d8cf2b6eb	是
   timestamp	Long	签名生成时间	时间戳，毫秒数	1435890533866	是
   app_sign	String	加密签名	算法: md5(app_id+timestamp+app_key)，32位16进制格式，不区分大小写	b927899dda6f9a04afc57f21ddf69d69	是
   channel	String	渠道类型	----	目前只支持ALI	是
   batch_no	String	批量付款批号	此次批量付款的唯一标示，11-32位数字字母组合	201506101035040000001	是
   account_name	String	付款方的支付宝账户名	支付宝账户名称	毛毛	是
   transfer_data	List	付款的详细数据	每一个Map对应一笔付款的详细数据, list size 小于等于 1000。 Map的参数结构如下表	是

   transfer_data:

   参数名	类型	含义	例子
   transfer_id	String	付款流水号，32位以内数字字母	1507290001
   receiver_account	String	收款方支付宝账号	someone@126.com
   receiver_name	String	收款方支付宝账户名	某某人必须和支付宝账号的一致
   transfer_fee	int	付款金额，单位为分	100
   transfer_note	String	付款备注	打赏

   返回结果（Object类型）:

   参数名	类型	含义
   result_code	Integer	返回码，0为正常
   result_msg	String	返回信息， OK为正常
   err_detail	String	具体错误信息
   url	String	需要跳转到支付宝输入密码确认批量打款

• BeeCloud企业认证后还需要做各个渠道的注册么？

  BeeCloud还未提供代理申请各渠道支付账户和资质服务，企业认证只确保用户信息真实，支付渠道还需要用户自己申请

• 页面不是预期结果如何捕获代码错误？

  代码请使用try catch处理异常情况，并对返回的数据结果错误做处理

try { $result = \beecloud\rest\api::transfers($data); if ($result->result_code != 0) { //返回结果提示错误，此处显示错误或者打印到log中 echo json_encode($result); exit(); }

$htmlContent = $result->html;
$url = $result->url;
echo $url."<br>";
echo $htmlContent;

} catch (Exception $e) { //处理异常情况 echo $e->getMessage(); } ?> ~~~

• 如何获取特定订单支付结果

  1.使用bills接口，指定bill_no参数可以查询

  2.服务器上处理webhook消息，异步被动通知获取到结果

  3.return_url参数指定支付页面完成后的跳转的url，在url指定的页面中处理（强烈不建议，客户可能关闭页面导致不成功）

• return_url, webhook区别， 支付宝参数中为啥没有notify_url

  1.return_url为商品支付完成后，在支付方浏览器自动跳转访问的地址 2.webhook集中处理各渠道异步通知结果，然后再转发支付结果到你指定的webhook的url中，使用方式请前往webhook指南

• 如何处理webhook

  请参考demo文件夹下webhook.php的处理方式

• 微信公众号支付无法调起(demo/wx.jsapi.php)

  1. 请检查获取到的jsApiParams是否正确,不正确可能BeeCloud的APP下微信公众号的支付参数填写错误

  2. jsApiParams正确，请将js中alert打开Debug：

     ....
     WeixinJSBridge.invoke(
         'getBrandWCPayRequest',
         <?php echo json_encode($jsApiParam);?>,
         function(res){
             WeixinJSBridge.log(res.err_msg);
              //下面这行
     			//alert(res.err_code+res.err_desc+res.err_msg);
         }
     );
     ....
     

     提示无支付权限请检查微信公众平台下”微信支付-＞支付授权目录“是否设置了文件所在目录，只有授权目录下的文件才能发起支付

     提示openid不正确，请检查”开发者中心->网页服务->网页授权获取用户基本信息"的域名是否设置正确，并检查你是否正确获取到了openid

• 微信公众平台内扫码支付回调URL是否需要设置

  BeeCloud使用的扫码模式二，扫码结果也会通过webhook传递；

  扫码支付回调URL是模式一中需要填写的，故如果你使用BeeCloud实现的扫码不需要再设置该url

• 常见BeeCloud错误提示定位

  支付宝BeeCloud的Demo提示"ILLEGAL_PARTNER": 
  由于支付宝不允许跨域调用支付功能，在非beecloud域名下发起支付会被加入黑名单，所以我们不再提供真实的参数，请替换为自己的参数后测试
  

  支付宝即时到账提示"illegal_partner_exterface":
  支付宝对应产品未开通,[参考问题](http://www.oschina.net/question/163899_23976)
  

  xxx字段必填：
  	PHP接口中$data中必填参数未填写
  

  字段不合法，需要xxx类型：
  $data参数字段有类型要求，请对照文档中的说明确认类型
  

   微信提示"CHANNEL_ERROR:签名错误",微信提示"CHANNEL_ERROR:渠道方错误":  
   请确认BeeCloud微信公众号的参数和证书正确，微信APPID和证书密码对应,证书和API密码应该是从微信商户平台下获取的
  

   支付宝支付跳转后提示"ALI59": 
   bill_no字段只能是字母和数字组合
  

   银联支付跳转后提示"HTTP Status 400 - Invalid request": 
   请确认BeeCloud的银联参数填写正确，根据[银联文档](http://7xavqo.com1.z0.glb.clouddn.com/证书下载、导出及上传流程.docx)确认证书正确
  

   银联跳转后提示"Signature verification failed": 
   请确认使用的证书为生产证书而非测试证书，并且证书密码正确
  

• 如果有什么问题，可以到BeeCloud开发者1群:321545822 或 BeeCloud开发者2群:427128840 提问
• 如果发现了bug，欢迎提交issue
• 如果有新的需求，欢迎提交issue

The MIT License (MIT).