总体流程
【1】 用户选择商品,购物结帐
用户在APP中选择商品后,直接通过POST请求将购物车提交给支付平台(http://app.baidu.com/pay/submitorder)。由于百度应用开放平台是允许非登录用户访问应用的,而应用内支付功能应该只针对登录并授权了当前应用的用户开放的,
因此开发者务必要在提交购物车请求给百度支付平台之前引导用户登录并授权您的应用。
【2】 平台向APP服务器获取订单
支付平台将购物车的信息通过APP在开发者后台注册的【支付回调地址】URL以HTTP POST协议发送数据。
【3】 APP生成订单
APP收到请求后生成对应的订单,并返回其订单号;【2】和【3】步中的发送数据约定和返回数据约定详见【获取订单ID接口】详细说明。
【4】支付成功回调
当用户确认付款后,平台完成订单的相应处理操作后,将会向APP在开发者后台注册的【支付回调地址】发送一个POST请求告知APP此订单已完成付款,可以给用户发放虚拟道具/商品。
【5】APP完成发货并返回确认值
APP收到回调请求后确认订单无误后应该立刻给用户发放虚拟道具/商品,并返回平台约定的JSON数据;【4】和【5】步中的发送数据约定和返回数据约定详见【支付成功回调接口】详细说明。
【6】 操作完成提示
用户操作完成后将会有对应的提示消息。
购物车提交请求
描述:
用户在APP中选择商品后,APP需要将以下数据通过POST请求提交到百度支付平台的http://app.baidu.com/store/submitorder 地址。
注意:所有参数都必须是utf-8编码。
参数:
RequiredNameTypeDescription
requiredapp_idintapp ID
amountint金额,pay_type=1时表示人民币金额,单位元,pay_type=2时表示百度币数量
messagestring商品描述信息,不超过32个字符
parametersstringAPP的自定义参数,需要进行urlencode,用户完成支付后,平台在回调支付回调地址时会将其传回给APP服务器
itemsstring购物车信息的json字符串
otpionpay_typeint支付方式,1为现金 2为百度币
sandboxint0表示关闭沙盒模式,1表示开启沙盒模式,只在测试支付功能时使用,上线后应该关闭沙盒模式
其中items的格式为,
"items": [{"vitid":"test_vit1", "price":20, "count":2, "description":"xxxx"},] ,
目前只支持包含一个购买项。
RequiredNameTypeDescription
requiredvitidstring虚拟物品交易id,预留用
priceint商品单价
countint商品数量
descriptionstring商品描述,不超过255个字符
获取订单ID接口
此接口由APP在开发者后台注册的支付回调地址提供,接收平台的HTTP POST请求。
接口描述:
百度支付平台主动向第三方服务器获取一个订单,平台将会POST以下必要参数给第三方服务器,第三方根据这些信息给用户生成一条订单,然后返回一段包含订单号的JSON数据给平台,这样平台就能记录并生成对应的订单给用户付款。
平台POST给第三方服务器的参数如下:
RequiredNameTypeDescription
requiredbd_sig_callback_typeint固定为1,表示当前支付回调请求是获取订单请求
bd_sig_userint用户uid
bd_sig_app_idint应用id
bd_sig_sandboxint沙盒模式,是否为支付测试,为1时为假支付,不扣除百度币,仅为开发者测试用。建议APP上线支付产品时将沙盒模式关闭,即不接收1请求
bd_sig_paymentstring订单详细信息,见下表
bd_sigstring参数的md5校验串,生成方法与REST API请求的bd_sig生成方法相同
过段时间会改成用md5(支付密码 + userid)方式
bd_sig_payment的示例值:
{"amount":"1","message":"xxx.","parameters":"{type:'xxx',quantity:2}","paymentType":"payment","sandbox":1,"items":[{"vitid":"","price":20,"count":2,"description":"2 items"},],"orderedTime":1261633596528}
具体定义如下:
RequiredNameTypeDescription
requiredamountint总支付金额
messagestring商品描述信息,不超过32个字符
parametersstringAPP的自定义参数,需要进行urlencode,用户完成支付后,平台在回调支付回调地址时会将其传回给APP服务器
parametersstringAPP的自定义参数,需要进行urlencode,用户完成支付后,平台在回调支付回调地址时会将其传回给APP服务器
pay_typeint支付方式,1为现金 2为百度币
sandboxint是否为测试,以bd_sig_sandbox为准
itemsstring购物车信息的json字符串
orderedTimeint下订单时间
Items中字段定义如下:
RequiredNameTypeDescription
requiredvitidstring虚拟物品交易id,预留用
priceint商品单价
countint商品数量
descriptionstring商品描述,不超过255个字符
APP返回的参数定义:
RequiredNameTypeDescription
requiredapp_res_orderidlong订单号,要求在百度支付平台全局唯一,总长度不超过19位的64位无符号整数,建议采用appid + 应用内自增id作为订单号,例如app_id=10001,符合规则的订单号为100011234534567
app_res_codestringOK / APP_LOGIC_ERROR 状态值,任何情况不能生成订单时可以返回APP_LOGIC_ERROR,平台会尝试重新获取并提示用户错误信息。成功则返回OK
app_res_userint用户uid
例如:{"app_res_orderid":100011234534567,"app_res_code":"OK", "app_res_user":"111223"}
支付成功回调接口
接口描述:
用户为订单付款后,百度支付平台将通过APP在开发者后台注册的【支付回调地址】URL发送HTTP POST请求来通知APP其订单已经完成支付。
回调参数:
RequiredNameTypeDescription
requiredbd_sig_callback_typeint固定为2,表示当前支付回调请求是支付成功回调请求
amountint金额,pay_type=1时表示人民币金额,单位元,pay_type=2时表示百度币数量
bd_sig_orderidstring订单号
bd_sig_userint用户uid
bd_sigstring参数校验串,计算方法同REST API
过段时间会改成用md5(支付密码 + userid)方式
回调返回值:
APP应当发挥一个JSON字符串来表示此次消费的3个关键信息:用户uid、订单号、支付金额,格式如下:
{"app_res_user":12345,"app_res_orderid":1000001,"app_res_amount":100}
支付平台获得这个返回值后会进行数据校验,如果校验失败,也认为此次回调失败。 (增加这种约束的目的是为了强调上述三个关键数据,并且确保回调时app给用户加道具的逻辑已经顺利完成)
重复回调说明:
用户支付成功后,百度支付平台会立即回调APP一次以通知发货,如果在3s内收到http响应码为200,且回调返回值通过数据校验,则认为此次回调成功,否则认为回调失败。
对于失败的回调,平台会每隔5分钟重新回调一次,直到回调成功,最多持续回调72小时。
如果一个app每天回调失败的订单数超过总量1%,我们会认为此app提供的支付服务不够稳定,为了保证用户的权益,我们会暂时取消该app的支付功能。
在处理回调请求时需要注意以下几点:
收到回调请求后,app应该通过调用REST API 中的pay.isCompleted来确认订单的支付状态(可选)。
由于对于一个订单,app可能收到多次来自平台的回调,所以请注意程序逻辑,以免造成不必要的损失
App应当保证第N(N>=2)次收到平台回调的时候也能够正确地返回上述json对象,在正常情况下,平台在第一次回调成功后就不再继续回调了,但是如果在交互过程中网络出错或者其他原因造成App收到了回调,但是平台没有收到正确的应答,平台也会认为回调不成功,稍后会重新回调
bd_sig校验串计算方法
bd_sig校验串的计算方法为:
$str = ''; //签名字符串
//先将参数以其参数名的字母升序进行排序
ksort($params);
//遍历排序后的参数数组中的每一个key/value对
foreach( $params as $k => $v )
{
//为key/value对生成一个key=value格式的字符串,并拼接到签名字符串后面
$str .= "$k=$v";
}
//将签名密钥拼接到签名字符串最后面
$str .= $secret;
//通过md5算法为签名字符串生成一个md5签名,该签名就是我们的bd_sig值
$bd_sig = md5($str);