信用借还快速接入

更新时间：2017/05/31 访问次数：19240

第一步：创建应用
第二步：配置密钥
第三步：搭建和配置开发环境
第四步：接口调用示例

第一步：创建应用

要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（open.alipay.com），在管理中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限，通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步：配置密钥

开发者调用接口前需要先生成RSA密钥，RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY）。生成密钥后在开放平台管理中心进行密钥配置，配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步：搭建和配置开发环境

1.下载服务端SDK

为了帮助开发者调用开放接口，我们提供了开放平台服务端SDK，包含JAVA、PHP和.NET三个语言版本，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。

2.接口调用配置

各语言版本服务端SDK详细使用说明，请参考《服务端SDK使用说明》

在SDK调用前需要进行初始化，代码如下：

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

关键参数说明:

配置参数	示例值解释	获取方式/示例值
URL	支付宝网关（固定）	https://openapi.alipay.com/gateway.do
APPID	APPID 即创建应用后生成	获取见上面创建应用
FORMAT	参数返回格式，只支持json	json（固定）
APP_PRIVATE_KEY	开发者私钥，由开发者自己生成	获取详见上面配置密钥
CHARSET	编码集，支持GBK/UTF-8	开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY	支付宝公钥，由支付宝生成	获取详见上面配置密钥
SIGN_TYPE	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2

第四步：接口调用示例

接口调用流程

1、信用借还订单创建zhima.merchant.order.rent.create

申请借用并完成相关支付方式签约的接口。

页面接口，跳转至芝麻借用页面。用户完成后，页面回调至商户指定页面并返回结果。

如果商家设置了通知地址，会将订单创建结果异步通知商户。

2、信用借还订单查询zhima.merchant.order.rent.query

订单创建后，用户可根据商户外部订单号查询订单状态。

3、信用借还订单完结zhima.merchant.order.rent.complete

用户归还物品后，调用该接口，完成订单的核销，并扣取相应的租金费用；

用户逾期未归还物品，调用该接口，扣取物品赔偿金

如果商家设置了通知地址，会将订单完结结果异步通知商户。

4、信用借还订单撤销zhima.merchant.order.rent.cancel（可选）

订单创建后，用户可根据订单号撤销订单。

5、信用借还借用实体数据上传接口zhima.merchant.borrow.entity.upload

在线下信用借还场景中，需要商户上传借用实体（如充电宝机柜、借还门店点等）的地址位置及描述信息数据，C端用户可以在芝麻信用借还频道地图页中查看。

6、信用借还订单修改接口zhima.merchant.order.rent.modify

在订单创建后，可根据订单号对订单的相关信息进行修改。

SDK接入

1）信用借还订单创建接口（zhima.merchant.order.rent.create）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your_private_key","json","GBK","alipay_public_key"); // your_private_key:商户私钥；alipay_public_key:蚂蚁公钥
ZhimaMerchantOrderRentCreateRequest request = new ZhimaMerchantOrderRentCreateRequest();
request.setBizContent("{" +
" \"invoke_type\":\"WINDOWS\"," +  // 访问蚂蚁的对接模式：windows-支付宝服务窗
" \"invoke_return_url\":\"https://www.bing.com\"," +  // 回调到商户的url地址
" \"invoke_state\":\"{\\\"xxx\\\":\\\"xxx\\\"}\"," +  // 商户发起借用服务时，需要在借用结束后返回给商户的参数
" \"out_order_no\":\"2016100100000xxxx\"," +          // 外部订单号
" \"product_code\":\"w1010100000000002858\"," +  // 信用借还的产品码，固定不变
" \"goods_name\":\"充电宝\"," + // 物品名称
" \"rent_info\":\"2小时内免费，超过2小时 2元/小时\"," + // 租金信息描述
" \"rent_unit\":\"DAY_YUAN\"," + // 租金单位
" \"rent_amount\":\"100.00\"," +  // 租金 
" \"deposit_amount\":\"200.00\"," + //押金，同时也是物品价值，用户需根据该字段金额进行赔偿
" \"deposit_state\":\"Y\"," +   // 是否允许不准入的用户支持支付押金借用：Y支持，N不支持
" \"borrow_cycle\":\"2\"," +    // 借用周期，必须是正整数
" \"borrow_cycle_unit\":\"HOUR\"," + // 借用周期单位
" \"borrow_shop_name\":\"肯德基文三路门店\"" + // 物品借用门店
" \"rent_settle_type\":\"alipay\"" + // 租金的结算方式
" }");
ZhimaMerchantOrderRentCreateResponse response = alipayClient.pageExecute(request, "GET"); // 这里一定要用GET模式
String url = response.getBody(); // 从body中获取url
System.out.println("generateRentUrl url:" + url);

重点业务入参说明

参数	描述
invoke_return_url	在用户创建订单操作完成后，同步回调到商户的url地址。注：是页面按钮级的回调，是用户触发的，用户可以选择不点击进入回调页面。
out_order_no	商户的借用订单号，商户级别唯一。当用户完成借用后，芝麻借还的订单号将会与商户的订单号建立关联关系，方便商户查询，同时也作为芝麻内部做幂等控制使用。推荐格式：yyyyMMddHHmmss+随机数
deposit_amount	押金，金额单位：元。注：不允许免押金的用户按此金额支付押金；当物品丢失时，赔偿金额不得高于该金额。
name	借用用户的真实姓名，非必填字段。但name和cert_no必须同时非空，或者同时为空，一旦传入会对用户身份进行校验。
cert_no	借用用户的真实身份证号，非必填字段。但name和cert_no必须同时非空，或者同时为空，一旦传入会对用户身份进行校验。
rent_settle_type	租金的结算方式，非必填字段，默认是支付宝租金结算支付 merchant：表示商户自行结算，信用借还不提供租金支付能力； alipay：表示使用支付宝支付功能，给用户提供租金代扣及赔偿金支付能力；

2）信用借还订单查询（zhima.merchant.order.rent.query）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your_private_key","json","GBK","alipay_public_key");  // your_private_key:商户私钥；alipay_public_key:蚂蚁公钥
ZhimaMerchantOrderRentQueryRequest request = new ZhimaMerchantOrderRentQueryRequest();
request.setBizContent("{" +
" \"out_order_no\":\"2016100100000xxxx\"," +        // 外部订单号
" \"product_code\":\"w1010100000000002858\"" +  // 信用借还的产品码，固定不变
" }");
ZhimaMerchantOrderRentQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

3）信用借还订单完结（zhima.merchant.order.rent.complete）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your_private_key","json","GBK","alipay_public_key");  // your_private_key:商户私钥；alipay_public_key:蚂蚁公钥
ZhimaMerchantOrderRentCompleteRequest request = new ZhimaMerchantOrderRentCompleteRequest();
request.setBizContent("{" +
" \"order_no\":\"100000\"," + // 信用借还订单号
" \"product_code\":\"w1010100000000002858\"," + // 信用借还的产品码，固定不变
" \"restore_time\":\"2016-10-01 12:00:00\"," +          // 物品归还时间
" \"pay_amount_type\":\"RENT\"," +  // 金额类型：RENT(租金)，DAMAGE(赔偿金)
" \"pay_amount\":\"100.00\"," +         // 支付金额
" \"restore_shop_name\":\"肯德基文三路门店\"" +    // 物品归还门店名称
" }");
ZhimaMerchantOrderRentCompleteResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

重点业务入参说明

参数	描述
order_no	芝麻信用借还平台的订单号
pay_amount_type	金额类型： RENT:租金 DAMAGE:赔偿金金额类型+支付金额需要组合起来才有实际含义
pay_amount	支付金额，单位：元金额类型+支付金额需要组合起来才有实际含义

4）信用借还订单撤销（zhima.merchant.order.rent.cancel）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your_private_key","json","GBK","alipay_public_key");  // your_private_key:商户私钥；alipay_public_key:蚂蚁公钥
ZhimaMerchantOrderRentCancelRequest request = new ZhimaMerchantOrderRentCancelRequest();
request.setBizContent("{" +
" \"order_no\":\"100000\"," +   // 信用借还订单号
" \"product_code\":\"w1010100000000002858\"" + // 信用借还的产品码，固定不变
" }");
ZhimaMerchantOrderRentCancelResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

5）信用借还借用实体数据上传接口（zhima.merchant.borrow.entity.upload）

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("调用失败");
}

重点业务入参说明

参数	描述
category_code	类目Code，传入芝麻借还规定的类目Code，其他值会认为非法参数，参数值如下：雨伞：umbrella 充电宝：power_bank 注意：联调测试情况下，类目Code必须传test
entity_code	外部实体编号，唯一标识一个实体，如自行车编号，机柜编号注意：商户维度下，类目Code（categoryCode）+实体编号（entity_code）唯一，一个商户下相同类目code+实体编号多次调用，将按照上传时间（upload_time）更新，更新规则取最新的upload_time快照数据
can_borrow	是否可借用，Y：可借，N：不可借。如果不可借用，则不在芝麻借还频道地图展示
upload_time	实体上传时间，某一借还实体信息多次上传，以最新上传时间数据为当前最新快照，格式：yyyy-mm-dd hh:MM:ss

6）信用借还订单修改（zhima.merchant.order.rent.modify）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
ZhimaMerchantOrderRentModifyRequest request = new ZhimaMerchantOrderRentModifyRequest();
request.setBizContent("{" +
"    \"order_no\":\"100000\"," +
"    \"product_code\":\"w1010100000000002858\"," +
"    \"borrow_time\":\"2017-04-06 15:34:38\"," +
"    \"expiry_time\":\"2017-04-06 15:34:38\"" +
"  }");
ZhimaMerchantOrderRentModifyResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

重点业务入参说明

参数	描述
order_no	芝麻信用借还平台的订单号
borrow_time	1、芝麻借还订单的开始借用时间，格式：yyyy-mm-dd hh:MM:ss 2、如果同时传入另一参数：应归还时间expiry_time，则传入的开始借用时间不能晚于传入的应归还时间，如果没有传入应归还时间，则传入的开始借用时间不能晚于原有应归还时间。 3、borrow_time 与 expiry_time 须至少传入一个，可同时传入。
expiry_time	1、芝麻借还订单的应归还时间(到期时间)，格式：yyyy-mm-dd hh:MM:ss 2、传入的应归还时间不能早于原有应归还时间。 3、borrow_time 与 expiry_time 须至少传入一个，可同时传入。

FAQ

关于此文档暂时还没有FAQ

有用(24) 我要提问