开放平台
信用借还进阶功能
更新时间：2017/05/31
访问次数：20275
订单创建链接异常说明
芝麻信用接收到商户发送的订单创建https请求后，会对商户传递的参数进行有效性检查，如果检查失败会直接提示在芝麻信用提供的通用错误页面上。在对接联调测试过程中，这些异常值需要商户的技术同学重点了解。异常文案及说明处理方式如下：
| 异常文案 | 异常原因 | 解决方案 |
|---|---|---|
| 见图一 | 入参不合法，说明在构建订单创建请求过程中，没有按照参数规范传入。本例以“物品名称”做案例。 | 根据文案的提示，查看订单创建请求入参表，根据字段要求进行传参 |
| 见图二 | 商户创建订单传入app_id对应的商户，没有签约芝麻信用借还产品。 | 技术同学可咨询本公司的业务合作相关人，或者咨询芝麻运营同学(溪木，邮箱：lingling.cll@alipay.com)。 |
| 见图三 | 商户生成的订单创建https请求，URL的bizContent参数对应内容json格式非法 | 参考订单创建接口参数说明，字段值不能包含【“】【，】等特殊字符，Json格式校验可访问如下网站： http://www.bejson.com/ |
| 见图四 | 一笔外部订单被多个人操作，芝麻将外部订单和支付宝用户进行绑定，不允许其他用户再对其进行操作防止篡改。 | 联调测试的情况下，创建订单接口传入新的订单号。 |
订单创建完成后回调通知说明
当用户在芝麻借还平台完成准入识别及订单创建后，芝麻信用会以两种方式把数据反馈给商户。
同步方式：商户在组装订单创建https请求时，会附带invoke_return_url参数，当用户完成借用准入及资金处理后，在借用完成页面会自动回调到商户提供的invoke_return_url地址链接，目前商户链接跳转是通过自动跳转的方式实现。
注1：用户在跳转倒计时未到情况下，可以选择不跳转进入商户回调页面。
注2：此种方式安全性没办法保证，存在伪造等风险，建议同步方式仅作为页面跳转展示使用，商户相关订单创建成功的业务逻辑请在异步通知接收中处理。
注2：此种方式安全性没办法保证，存在伪造等风险，建议同步方式仅作为页面跳转展示使用，商户相关订单创建成功的业务逻辑请在异步通知接收中处理。
异步方式：订单创建完成后，异步通知给商户，见下方文档；
1）商户链接同步通知触发条件
在信用借还订单创建页面接口中，只要商户系统发起了请求，并且被芝麻信用接收到，都会发起通知回调，无论是参数校验失败，信用准入失败，或者是借用成功等
2）商户链接同步跳转方式特性
- 用户在借用成功后会看到一个芝麻信用提供成功的页面，并且显示物品的详细信息，该页面会停留3秒，并且有倒计时，然后会自动跳转回商户指定的同步通知页面（参数invoke_return_url）。
- 该页面中获取参数的方式，需要使用GET方式获取。
- 该方式仅仅在用户借用成功以后进行自动跳转，因此只会进行一次
- 该方式不是芝麻信用主动去调用商户页面，而是芝麻信用的程序利用页面自动跳转的函数，使用户的当前页面自动跳转。
- 该方式可在本机进行调试。
- 设置页面跳转同步通知页面（invoke_return_url）的路径时，不要在页面链接的后面再加上自定义参数。例如：
- 错误的写法：http://www.bing.com/return_url6.php?xx=11
- 正确的写法：http://www.bing.com/return_url.php
- 由于蚂蚁开放平台会对页面跳转同步通知页面（invoke_return_url）的域名进行合法有效性校验，因此设置页面跳转同步通知页面（invoke_return_url）的路径时，不要设置成本机域名，也不能带有特殊字符（如“!”）如：
- 错误的写法：
http://localhost/alipay/return_url.php
http://localhost:80/alipay/return_url.php
http://www.taobao.com/alipay/return!url.php - 正确的写法：
能够正常访问的域名地址：http://www.taobao.com/alipay/return_url.php
能够正常访问的IP地址：http://121.1.1.255/alipay/return_url.php
3）商户链接同步回调参数说明
订单创建成功链接同步返回如下值：
| 参数 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| success | String(10) | 是 | true | 表示调用是否成功，并不表明业务处理结果 true:成功 false:失败 |
| invoke_state | String(50) | 否 | {"xxx":"xxx"} | 商户发起借用服务时，一笔订单调用请求的上下文参数信息，创建成功后原参数返回，如果没有可不传。 |
| out_order_no | String(20) | 是 | 20161001000000XXXX | 商户的借用订单号，商户级别唯一。订单创建成功后原参数返回。 |
| order_no | String(10) | 是 | 100000 | 芝麻信用借还订单号，与商户的订单号（out_order_no）存在关联关系 |
| admit_state | String(5) | 是 | Y | 是否准入（信用）： Y-准入（信用够） N-不准入（信用不够） |
| user_id | String(20) | 是 | 2088202924240029 | 借用者的支付宝用户Id |
订单创建失败链接同步返回如下值：
| 参数 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| success | String(10) | 是 | false | 表示调用是否成功，并不表明业务处理结果 true:成功 false:失败 |
| error_code | String(30) | 否 | GOODS_HAS_BORROW | 表示接口调用失败后的错误码 |
| error_message | String(30) | 否 | 该物品已经借用,请先归还后再借 | 表示接口调用失败后的错误信息 |
4）样例
注意：返回结果统一通过
biz_content返回，内部包括基本参数和业务参数
调用成功：
http://商户自定义地址?biz_content=%7B%22admit_state%22%3A%22Y%22%2C%22invoke_state%22%3A%22invoke_state%22%2C%22order_no%22%3A%22100000%22%2C%22out_order_no%22%3A%2220161001000000XXXX%22%2C%22success%22%3A%22true%22%2C%22user_id%22%3A%222088202924240029%22%7D
调用失败：
http://商户自定义地址?biz_content=%7B%22error_code%22%3A%22ARRANGEMENT_NOT_EXIST%22%2C%22error_message%22%3A%22%E5%95%86%E6%88%B7%E5%AF%B9%E4%BA%A7%E5%93%81%E6%9C%AA%E7%AD%BE%E7%BA%A6%22%2C%22success%22%3A%22false%22%7D
5）商户链接同步回调主要错误码说明
| 统一对外错误码 | 错误描述 | 解决方案 |
|---|---|---|
| INVALID_PARAMETER | 传入的参数为空，或者格式不正确 | 传入的参数为空，或者格式不正确，具体哪个参数不正确，具体哪个参数出现错误，可参考同步回调结果的error_message内容 |
| ARRANGEMENT_NOT_EXIST | 商户对产品未签约 | 请联系商户业务及芝麻借还产品的运营同学(溪木，邮箱：lingling.cll@alipay.com) |
| DEPOSIT_CLOSED | 不支持押金模式 | 商户调用创建订单deposit_state参数传递”N”,表示不支持押金模式，所以当用户不准入（信用不够）时，则中断借用流程，如需要押金流程则deposit_state参数传递”Y” |
| GOODS_HAS_BORROW | 该物品已经借用,请先归还后再借 | 请先归还物品 |
| PREAUTH_FREEZE_ERROR | 该用户预授权冻结押金失败 | 请确认支付宝账号中是否有足够的金额 |
| WITHHOLD_CONTRACT_ERROR | 签约代扣协议错误 | 请联系支付宝客服(电话：95188) |
| ZM_ACCOUT_REGISTER_FAIL | 芝麻会员开通失败 | 请重试或联系支付宝客服(电话：95188) |
| OUT_ORDER_NO_INVALID | 外部订单号重复 | 请更换外部订单号 |
| USER_NOT_LOGON | 该支付宝账号没有登录 | 请重新登录支付宝 |
| OUT_ORDER_INFO_FALSIFY | 一个外部订单被多个人操作 | 用户每次请求借用都重新生成一个新的订单号 |
芝麻借还订单详情“去归还”同步回调说明
创建订单成功后，用户可在芝麻借还“借用中”订单详情页面上，会看到商户订单同步回调按钮（即“去归还”按钮，见下方图示）。
图示：去归还链接跳转效果
此“去归还”按钮回调的外部商户地址为订单创建请求中传入的invoke_return_url参数地址，因为与订单创建成功回调地址相同，此“去归还”按钮链接中，在invoke_return_url的返回的请求参数中，增加“return_type":"order_detail"参数用来做区分，order_detail值表示当前请求是订单详情页面的回调。如下所示：
订单创建回调请求：
http://商户回调地址?biz_content={"admit_state":"Y","order_no":"692","out_order_no":"2017032900000000120","success":"true","user_id":"2088xxxxxxxx005"}
“去归还”订单详情页面回调请求：
http://商户回调地址?biz_content={"admit_state":"Y","order_no":"201704xxxx001","out_order_no":"201704xxxx002","return_type":"order_detail","success":"true","user_id":"2088xxxxxxxx005"}
信用借还订单查询说明
接口业务说明：根据商户传递的外部订单号进行芝麻借还订单数据的查询。可用于订单创建请求后，通过外部轮询订单号轮询此接口，判断用户是否创建订单。
接口技术说明：
- 返回的use_state为borrow，表示订单处于“借用中”，则返回的资金相关字段（pay_status、pay_amount_type、pay_amount、pay_time、alipay_fund_order_no）不具备任何实际含义。
- 返回的use_state为restore，表示订单物品已归还，此时需要分两种情况来判断订单状态。第一种情况：订单不涉及资金，此时表示订单“已归还”，返回的资金相关字段（pay_status、pay_amount_type、pay_amount、pay_time、alipay_fund_order_no）不具备任何实际含义；第二种情况：订单涉及资金，此时还需要观察资金状态（pay_status）。如果为PAY_SUCCESS则表示用户成功支付，此时表示订单“已归还”；如果为PAY_FAILED则表示用户代扣付款失败，此时订单还处于“借用中”，需要用户自行手工付款。其他两个状态（PAY_INIT:待支付、PAY_INPROGRESS:支付中）表示当前处于用户支付的瞬时态，可过几秒钟再次查询订单最终支付状态。
信用借还订单完结说明
接口业务说明：用户归还借用的物品后，调用此接口完成订单核销并扣取相应的租金。当用户物品丢失或者商户指定最晚归还日期（见订单创建接口zhima.merchant.order.rent.create的expiry_time参数）未归还，调用此接口扣取物品赔偿金（deposit_amount物品价值金额）。
接口技术说明：
- 租金归还：传递有效的芝麻借还订单号，并传递pay_amount_type为RENT（租金），pay_amount字段值为租金的金额（单位：元）。
- 赔偿金归还：传递有效的芝麻借还订单号，并传递pay_amount_type为DAMAGE（赔偿金），pay_amount字段值为赔偿金的金额（单位：元）。
关于用户代扣失败的处理说明：
complete接口所有的资金操作都走代扣, 代扣失败大部分的原因是用户账户余额不足，极少数由于支付宝支付受到央行额度限制、银行卡发卡行额度限制等原因，所以一旦发现首次调用complete失败（返回错误码：UNITRADE_WITHHOLDING_PAY_FAILED）没扣钱，商户可适度频率进行定时轮询（例如针对付款失败的订单每日调用一次complete接口）进行循环扣款。
芝麻借还平台具备催收功能，遇到代扣失败情况将会引导用户到订单页面进行手工转账付款，正常情况下用户发现无法付款，会关联新卡，或者转入资金。由于是用户触发的，商户是不知道的，所以用户付款成功后，借还平台会发送异步通知给商户，商户收到付款完成通知后更改自身订单状态。
信用借还订单撤销说明
接口业务说明：撤销用户在借中的订单，且不扣除租金。
接口技术说明：
- 商户系统在线上运行阶段，可能会产生掉单、废单等现象（比如测试订单、无用订单等），可调用此接口进行订单撤销操作。
- 在系统联调测试中，测试人员借用产生的订单，可调用此接口进行撤销，并且不会扣除资金。
注意：撤销接口只能撤销“借用”中状态的订单，非“借用”中状态的订单是不能撤销的。
信用借还订单创建及完结异步通知说明
通知功能描述
1、订单创建事件：
商户调用信用借还订单创建接口（见信用借还订单创建zhima.merchant.order.rent.create文档）后，借用物品的C端用户在芝麻信用借还平台借用成功后，发送的异步通知。
注意：
- 订单创建成功异步通知保证一定会发，但不保证只发一次，处理超时或者网络延迟请求下可能会发2次及以上，所以商户端做好幂等控制。
- 订单创建成功异步通知发送时机是用户在芝麻信用借还平台完成借用后，极端情况下用户可能过了1-2个小时或者1-2天后完成确认借用。所以商户端在这种情况下，一方面是确认用户是否已借用该物品，如果前期未借用成功，请及时调用订单撤销接口（见信用借还订单撤销文档），核销用户在芝麻的借用订单。
2、订单完结事件：
- 借用用户在商户端发起正常归还流程，商户端调用信用借还平台的完结接口（见信用借还订单完结文档），信用借还平台完成借用用户的扣款（存在租金或者赔偿金的情况下）后，发送的异步通知。
- 借用用户如丢失了借用物品，可在信用借还平台订单详情页面发起主动赔偿功能，用户付款完成，也会发送给商户订单完结的异步通知。
注意：订单完结可分为正常租金支付归还完结及物品丢失支付赔偿完结，如果商户需要区分这两种不同的完结，需要调用订单查询接口（见
信用借还订单查询文档），取得pay_amount_type字段，值”RENT”表示租金支付归还完结，值”DAMAGE”表示物品丢失支付赔偿完结。
3、异步通知参数：
| 参数 | 参数名称 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|---|
| notify_type | 通知类型 | String（30） | 是 | 取值范围： ORDER_CREATE_NOTIFY (订单创建异步事件) ORDER_COMPLETE_NOTIFY (订单完结异步事件) |
ORDER_COMPLETE_NOTIFY |
| order_no | 信用借还平台订单号 | String(20) | 是 | 芝麻信用借还平台生成的订单号 | 1231521 |
| out_order_no | 外部商户订单号 | String(36) | 是 | 外部商户生成的订单号，与芝麻信用借还平台生成的订单号存在关联关系 | 2016101821001004580200552288 |
| sign | 签名 | String(256) | 是 | 请参考异步返回结果的验签 | 601510b7970e52cc63db0f44997cf70e |
| sign_type | 签名类型 | String(10) | 是 | 签名算法类型，目前支持RSA及RSA2 | RSA2 |
4、样例：
{
"notify_type":["ORDER_COMPLETE_NOTIFY"],
"order_no":["501"],
"out_order_no":["201611230000400200"],
"sign":["ZXdX9nvSG8O9ADgOlTCiKdFtAjJKW5oapxDpHbkuMvlIffznTDn/wo+/PATt3MzpTswQ1BMzNUJQ4zG+BAnVU7Vs9Hi7fL+ofhCVQkrKNBGJnEhujmnhI/qb6kcZbDws0vjGsYXLKrUF02+WeEBHZ5AYOxzjzI/Ke6nVzHFJaQMnVU7Vs9Hi7fL+ofhCVQkrKNBGJnEhujmoapxDpHbkuMvlIffznT+BAnVU7Vs9HiMvlIffznTDn/w="],
"sign_type":["RSA2"]
}
异步通知技术接入案例
商户异步通知接收地址配置：
使用商户有效的账号登录蚂蚁开放平台，找到您已签约的芝麻信用借还应用，将“应用网关”设置为商户有效的回调地址，请参见配置应用环境。
异步通知商户回调请求编写注意事项及案例
1、回调请求编写
商户提供的回调请求地址需要支撑标准的http或（https）POST请求。
2、异步通知重试策略
- 程序执行完后必须打印输出“success”（不包含引号）。如果商户反馈给芝麻信用的字符不是success这7个字符，芝麻信用服务器会不断重发通知，直到超过24小时22分钟。一般情况下，25小时以内完成8次通知（通知的间隔频率一般是：4m,10m,10m,1h,2h,6h,15h）；
- 程序执行完成后，该页面不能执行页面跳转。如果执行页面跳转，芝麻信用会收不到success字符，会被芝麻信用服务器判定为该页面程序运行出现异常，而重发处理结果通知；
3、商户回调请求编写案例
以java语言代码为例，使用spring mvc框架
@Controller
public class BorrowGoodsNotifyTestController {
/** 日志. */
private static final Logger logger = LoggerFactory
.getLogger(BorrowGoodsNotifyTestController.class);
/**
* 异步通知请求入口.
* @param modelMap
* @param request
* @return
* @throws IOException
*/
@RequestMapping(value = "borrows/borrowNotifyTest.json", method = {RequestMethod.POST })
public void index(final ModelMap modelMap, final HttpServletRequest request, HttpServletResponse response) throws IOException {
//1、签名验证
……
//2、通知参数解析
Map<String, String[]> notifyParams = request.getParameterMap();
String notifyParamStr=JSONObject.toJSONString(notifyParams);
LoggerUtil.warn(logger, "异步通知:" + notifyParamStr);
//3、执行业务逻辑
……
//4、向芝麻反馈处理是否成功
printResponse(response, "success");
}
protected void printResponse(HttpServletResponse response, String content) throws IOException {
PrintWriter writer = null;
try {
writer = response.getWriter();
writer.write(content);
writer.flush();
} finally {
if (writer != null) {
writer.close();
}
}
}
}
4、POST请求参数打印的内容案例：
{
"notify_type":["ORDER_COMPLETE_NOTIFY"],
"order_no":["501"],
"out_order_no":["201611230000400200"],
"sign":["ZXdX9nvSG8O9ADgOlTCiKdFtAjJKW5oapxDpHbkuMvlIffznTDn/wo+/PATt3MzpTswQ1BMzNUJQ4zG+BAnVU7Vs9Hi7fL+ofhCVQkrKNBGJnEhujmnhI/qb6kcZbDws0vjGsYXLKrUF02+WeEBHZ5AYOxzjzI/Ke6nVzHFJaQM9ADgOlTCiKdFtAjJKW5oapxDpHbkurKNBGJnEhujmnhI/qb6kcZb6kcZbDws0vjGsYXLKr="],
"sign_type":["RSA2"]
}
信用借还借用实体地图数据上传说明
接口业务说明：在线下信用借还场景中，需要商户上传借用实体（如充电宝机柜、借还门店点、借用实物自行车等）的地址位置及描述信息数据，供C端用户可以在芝麻信用借还频道地图页中查看。
- 商户下的借用实体信息，保证类目Code（categoryCode）+实体编号（entity_code）唯一，一个商户下相同类目code+实体编号多次调用，将按照上传时间（upload_time）更新，更新规则取最新的upload_time快照数据覆盖旧记录。
- can_borrow字段表示借用实体是否可借用，如果传入【N】表示不可借用，则将从芝麻借还频道地图上隐藏。借用实物为单个实体，如自行车已被人借用，则需要将其从地图上隐藏。借用实体为机器设备，如充电宝机柜设备更换，需要把老的设备设置成不可借用，上线新的设备。
开发人员须知：在接口测试联调过程中，接口入参【类目Code（category_code）】字段必须传【test】，如一旦传入其他类目Code值，会将测试数据直接上线，从而暴露给所有C端用户，将会给商户品牌带来极差影响。
测试代码如下所示：
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
ZhimaMerchantBorrowEntityUploadRequest request = new ZhimaMerchantBorrowEntityUploadRequest();
request.setBizContent("{" +
" \"product_code\":\"w1010100000000002858"," +
" \"category_code\":\"test\"," +
" \"entity_code\":\"2016000100010011\"," +
" \"longitude\":\"83.66\"," +
" \"latitude\":\"5.87\"," +
" \"entity_name\":\"爱心雨伞\"," +
" \"address_desc\":\"杭州市西湖区文三路478号\"," +
" \"office_hours_desc\":\"09:00—22:00\"," +
" \"contact_number\":\"0571-26888888\"," +
" \"collect_rent\":\"Y\"," +
" \"rent_desc\":\"5元/小时\"," +
" \"can_borrow\":\"Y\"," +
" \"can_borrow_cnt\":\"12\"," +
" \"total_borrow_cnt\":\"20\"," +
" \"upload_time\":\"2017-01-01 15:34:38\"" +
" }");
ZhimaMerchantBorrowEntityUploadResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}
可登录手机钱包，用“扫一扫”功能，访问如下二维码即可查询展现联调测试的地图数据。
信用借还订单修改说明
接口业务说明：对“未完结”的借还订单进行修改。
接口技术说明：
- 商户系统在线上运行阶段，可能会有修改订单的需求(比如需要续借)，可调用此接口进行订单修改。
- 目前支持修改“开始借用时间”和“应归还时间(到期时间)”，可一次同时修改这两个时间，也可单独分别修改。
注意：订单修改接口只能修改“未完结”的订单，以下两种是“完结”订单，除此之外都是“未完结”订单。
1) 撤销状态的订单属于“完结”订单。
2) 物品已归还且资金扣取成功的订单属于“完结”订单。
1) 撤销状态的订单属于“完结”订单。
2) 物品已归还且资金扣取成功的订单属于“完结”订单。
