固定金额模式
完整接口时序图
服务开通
用户在商户平台上,在芝麻先享产品介绍等场景下,开通芝麻先享服务。
业务规则
- 开通芝麻先享服务需要达到芝麻分准入条件,以与支付宝约定芝麻分为准。
- 用户开通服务后,实时生效。
- 用户在同一商家下,只需要开通一次,即可使用芝麻先享服务。
服务开通示意图
流程说明
支持 APP/H5、支付宝小程序接入:
APP/H5接入
流程说明:
- 用户在商家侧 App 上点击开通。
- 商户服务端调用 zhima.credit.payafteruse.creditagreement.sign(信用服务开通/授权接口)对应的支付宝 SDK,如下代码示例。
- 接口会返回一个地址,通过这个地址截取问号后面的内容,作为 加签串 signStr。
**注意:**请求调用时需要传入 GET 参数: alipayClient.pageExecute(request, "GET")。
package com.java.sdk.demo;
import com.alipay.v3.ApiClient;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiResponse;
import com.alipay.v3.Configuration;
import com.alipay.v3.util.GenericExecuteApi;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.util.model.CustomizedParams;
import com.alipay.v3.util.model.OpenApiGenericRequest;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class GenericExecute {
public static void main(String[] args) throws ApiException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// 初始化alipay参数(全局设置一次)
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->");
defaultClient.setAlipayConfig(alipayConfig);
GenericExecuteApi api = new GenericExecuteApi();
Map<String, Object> bizParams = new HashMap<>();
try {
String response = api.sdkExecute("zhima.credit.payafteruse.creditagreement.sign", bizParams);
System.out.println(response);
} catch (ApiException e) {
System.out.println("调用失败");
}
}
}
例子:
https://openapi.alipay.com/gateway.do?charset=GBK&biz_content=%7B%22zm_service_id%22%3A%2220200507220014400310061082%22%2C%22category_id%22%3A%22credit_pay_after_use%22%2C%22cancel_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22return_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22product_code%22%3A%22CREDIT_PAY_AFTER_USE%22%2C%22extra_param%22%3A%22%7B%5C%22merchantExt%5C%22%3A%5C%22key%3Dvalue%5C%22%7D%22%2C%22out_agreement_no%22%3A%222014070700166653%22%7D&method=zhima.credit.payafteruse.creditagreement.sign&format=json&sign=rBLvTzvkSL%2BW%2FAxb%2B7%2FBTJKB7z7iiXKusW5689FiiQuVGjwAaWyzR1QmIywPgZm0gFqhL1ZCAgwpInBrJO1RSGCaupH3hPO%2F7%2FR1JOVvr12tdReocHxYj%2FP52mbnVsWk2EN%2F2IihA9sX94KZSMovP5dVx2ooq4PDV11RvZnhfXorsS3iGfHD9O7WvGKp4F4nMsmFDzrGUsMVsm06XPRjwzh7WNiJzC0%2FRN3OJrgZNjUsX2GfMAuzeh1sm1PD5FV%2Bd6OUEROf6NZOmeS5349qrnaJYG0yry69FkSmhvnOA9%2BQW9KopxSefk%2BcfYfXv3E6jNDXV5k4A5w%3D%3D&app_id=2019101168279633&version=1.0&sign_type=RSA2×tamp=2021-06-30+14%3A23%3A39
// 加签串signStr为
charset=GBK&biz_content=%7B%22zm_service_id%22%3A%2220200507220014400310061082%22%2C%22category_id%22%3A%22credit_pay_after_use%22%2C%22cancel_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22return_back_link%22%3A%22https%3A%2F%2Fwww.taobao.com%22%2C%22product_code%22%3A%22CREDIT_PAY_AFTER_USE%22%2C%22extra_param%22%3A%22%7B%5C%22merchantExt%5C%22%3A%5C%22key%3Dvalue%5C%22%7D%22%2C%22out_agreement_no%22%3A%222014070700166653%22%7D&method=zhima.credit.payafteruse.creditagreement.sign&format=json&sign=rBLvTzvkSL%2BW%2FAxb%2B7%2FBTJKB7z7iiXKusW5689FiiQuVGjwAaWyzR1QmIywPgZm0gFqhL1ZCAgwpInBrJO1RSGCaupH3hPO%2F7%2FR1JOVvr12tdReocHxYj%2FP52mbnVsWk2EN%2F2IihA9sX94KZSMovP5dVx2ooq4PDV11RvZnhfXorsS3iGfHD9O7WvGKp4F4nMsmFDzrGUsMVsm06XPRjwzh7WNiJzC0%2FRN3OJrgZNjUsX2GfMAuzeh1sm1PD5FV%2Bd6OUEROf6NZOmeS5349qrnaJYG0yry69FkSmhvnOA9%2BQW9KopxSefk%2BcfYfXv3E6jNDXV5k4A5w%3D%3D&app_id=2019101168279633&version=1.0&sign_type=RSA2×tamp=2021-06-30+14%3A23%3A39
- 根据步骤 3 得到的 **signStr,**按不同的情况构造不同的唤起支付宝页面的地址,然后跳转到这个地址:
需要前置判断一下用户是否安装了支付宝。
-
- 如果安装了支付宝
根据 **signStr,**构造 **schemeUrl。
**注意:appId=20000067 用于唤起支付宝,请固定保持不变。
构造规则:
- 如果安装了支付宝
'alipays://platformapi/startapp?appId=20000067&url=' + encodeURIComponent('https://render.alipay.com/p/yuyan/180020010000706007/index.html?signStr='+ encodeURIComponent(signStr))
// 示例
alipays://platformapi/startapp?appId=20000067&url=https%3A%2F%2Frender.alipay.com%2Fp%2Fyuyan%2F180020010000706007%2Findex.html%3FsignStr%3Dbizmock_trace_id%253D5fcca2b0c6254b01b3df99be03e61af2189008%2526charset%253DGBK%2526biz_content%253D%25257B%252522zm_service_id%252522%25253A%2525222021020500000000000004336900%252522%25252C%252522category_id%252522%25253A%252522credit_payment_000001%252522%25252C%252522cancel_back_link%252522%25253A%252522https%25253A%25252F%25252Fwww.taobao.com%252522%25252C%252522external_logon_id%252522%25253A%252522138552852877%252522%25252C%252522return_back_link%252522%25253A%252522https%25253A%25252F%25252Fwww.taobao.com%252522%25252C%252522out_request_no%252522%25253A%252522120139139882423%252522%25252C%252522extra_param%252522%25253A%252522%25257B%25255C%252522merchantExt%25255C%252522%25253A%25255C%252522key%25253Dvalue%25255C%252522%25257D%252522%25252C%252522out_agreement_no%252522%25253A%2525222014070ddd70550166653%252522%25257D%2526method%253Dzhima.credit.payafteruse.creditagreement.sign%2526format%253Djson%2526sign%253DRGKmqiVk3DfkGJT4ZetTKcieqVXRXr64kO9SudS4j4VA6vlsHp5mAUKgB9JqbHMUpdcXm8YY%25252BgiqZqZn%25252BkQj%25252BEkiIr%25252BRDhivv0m8%25252FHSxO2nYWCdT86OZ%25252BrmVbVZP3H3vDA5whLLBG7sS6E1jnBvNN1ppPJhCCfvxSwQRHbg8qSaf8Ue7kovf%25252Ftfs5dJ9%25252FXRXVYmMJSKibDHoD%25252BDSMsSBNOfr6uDdXNtIHMK%25252FjXijhb7WUFntyxlJl6eJN3BDHSgB9RIdaiFgnfj5Xh1QyD%25252B2W%25252BH%25252B178MJ6%25252FF6r6BHyZIKqAQeaVs2vIlsHtQtTILQ0u01ugBfoTxvCfkXGHcm8hDIg%25253D%25253D%2526app_id%253D2017090501336036%2526version%253D1.0%2526sign_type%253DRSA2%2526timestamp%253D2021-07-12%252B19%25253A59%25253A49
直接跳转这个 schemeUrl。
-
- 如果没有安装支付宝
根据上文中得到的 **schemeUrl,**去构造 landingUrl。
构造规则:
- 如果没有安装支付宝
'https://render.alipay.com/p/s/i/?scheme=' + encodeURIComponent(schemeUrl)
// 示例:
https://render.alipay.com/p/s/i/?scheme=alipays%3A%2F%2Fplatformapi%2Fstartapp%3FappId%3D20000067%26url%3Dhttps%253A%252F%252Frender.alipay.com%252Fp%252Fyuyan%252F180020010000706007%252Findex.html%253FsignStr%253Dbizmock_trace_id%25253D5fcca2b0c6254b01b3df99be03e61af2189008%252526charset%25253DGBK%252526biz_content%25253D%2525257B%25252522zm_service_id%25252522%2525253A%252525222021020500000000000004336900%25252522%2525252C%25252522category_id%25252522%2525253A%25252522credit_payment_000001%25252522%2525252C%25252522cancel_back_link%25252522%2525253A%25252522https%2525253A%2525252F%2525252Fwww.taobao.com%25252522%2525252C%25252522external_logon_id%25252522%2525253A%25252522138552852877%25252522%2525252C%25252522return_back_link%25252522%2525253A%25252522https%2525253A%2525252F%2525252Fwww.taobao.com%25252522%2525252C%25252522out_request_no%25252522%2525253A%25252522120139139882423%25252522%2525252C%25252522extra_param%25252522%2525253A%25252522%2525257B%2525255C%25252522merchantExt%2525255C%25252522%2525253A%2525255C%25252522key%2525253Dvalue%2525255C%25252522%2525257D%25252522%2525252C%25252522out_agreement_no%25252522%2525253A%252525222014070ddd70550166653%25252522%2525257D%252526method%25253Dzhima.credit.payafteruse.creditagreement.sign%252526format%25253Djson%252526sign%25253DRGKmqiVk3DfkGJT4ZetTKcieqVXRXr64kO9SudS4j4VA6vlsHp5mAUKgB9JqbHMUpdcXm8YY%2525252BgiqZqZn%2525252BkQj%2525252BEkiIr%2525252BRDhivv0m8%2525252FHSxO2nYWCdT86OZ%2525252BrmVbVZP3H3vDA5whLLBG7sS6E1jnBvNN1ppPJhCCfvxSwQRHbg8qSaf8Ue7kovf%2525252Ftfs5dJ9%2525252FXRXVYmMJSKibDHoD%2525252BDSMsSBNOfr6uDdXNtIHMK%2525252FjXijhb7WUFntyxlJl6eJN3BDHSgB9RIdaiFgnfj5Xh1QyD%2525252B2W%2525252BH%2525252B178MJ6%2525252FF6r6BHyZIKqAQeaVs2vIlsHtQtTILQ0u01ugBfoTxvCfkXGHcm8hDIg%2525253D%2525253D%252526app_id%25253D2017090501336036%252526version%25253D1.0%252526sign_type%25253DRSA2%252526timestamp%25253D2021-07-12%25252B19%2525253A59%2525253A49
直接跳转这个 **landingUrl,**这个时候会先到一个中间landing页面引导用户下载支付宝。
- 用户完成服务开通后,通过参入中的 return_back_link 值,跳转回商户APP或者小程序页面。
- 支付宝会通过 zhima.credit.payafteruse.creditagreement.changed(服务开通/授权状态变更通知)发送商户异步通知。在没有收到异步通知,或者需要主动查询开通情况时,可以使用 zhima.credit.payafteruse.creditagreement.query(查询服务开通/授权信息接口)。
支付宝小程序接入
第一步:创建小程序
要在小程序内使用小程序芝麻后付插件,首先请完成 开发者入驻 并 创建小程序。
第二步:订购插件
完成创建小程序应用后,使用小程序所属的主体支付宝账号,在 PC 端 芝麻先享服务插件 详情页点击 立即获取,完成插件订购。
第三步:修改小程序参数
插件 APPID:2021002151672975(固定不变)
app.json 插件配置
{
"pages": [
"pages/index/index"
],
"plugins": {
"myPlugin": {
"version": "*",
"provider": "2021002151672975"
}
}
}
小程序页面 .axml 示例代码
<button class="operation-btn" size="default" type="primary" onTap="onClick">open service</button>
.js 示例代码
const plugin = requirePlugin('myPlugin');
Page({
data: {
},
onClick() {
plugin.startService({
type: 'pay_after',
sign_str: '',
zm_service_id: '',
success: () => {},
fail: () => {},
complete: () => {},
});
},
});
入参
属性 | 类型 | 必填 | 描述 |
---|---|---|---|
type | String | 是 | 服务类型。芝麻先享为 pay_after。 |
sign_str | String | 是 | App 接入步骤中的 signStr。 |
zm_service_id | String | 是 | 申请接入芝麻先享服务时,芝麻分配给商户的服务 ID。 |
success | () => void | 否 | 调用成功回调。指的是成功拉起页面。 |
fail | (error) => void | 否 | 调用失败回调。 |
complete | () => void | 否 | 调用完毕。 |
错误结构
属性 | 类型 | 描述 |
---|---|---|
error | string | 错误码 |
errorMessage | string | 错误描述信息 |
错误码
错误码 | 描述 | 解决方案 |
---|---|---|
2000 | 参数错误 | 阅读产品接入文档,校对参数。 |
3000 | 服务不存在 | 传入的type,服务类型不存在。阅读产品接入文档,校对 type 参数。 |
API 列表
服务开通重要入参说明:
关键字段 | 描述 | 备注 |
---|---|---|
zm_service_id | 芝麻信用服务ID | 申请接入芝麻先享服务时,芝麻分配给商户的服务ID |
category_id | 芝麻外部类目 | 申请接入芝麻先享服务时,芝麻分配给商户的外部类目 |
接口列表:
接口描述 | API 接口 | 备注 |
---|---|---|
信用服务开通/授权 | zhima.credit.payafteruse.creditagreement.sign | 通过页面开通建立商户与用户关系拿到开通协议号(credit_agreement_id),用于下单流程 |
查询服务开通/授权信息 | zhima.credit.payafteruse.creditagreement.query | 根据开通协议号(credit_agreement_id)查询确定当前用户开通状态及相关信息 |
服务开通/授权状态变更通知 | zhima.credit.payafteruse.creditagreement.changed | 消息通知类接口,订阅方式可查看 From 蚂蚁消息。开通状态变更时发送该通知:例如:开通成功,用户主动关闭服务 |
信用下单并开通
未开通芝麻先享服务的用户,在商户平台购买商品或消费时,可引导用户同时开通芝麻先享服务,届时既开通芝麻先享服务又同时完成本笔交易的信用下单。在下单流程中引导用户开通,用户体验更加顺畅。
业务规则
- 下单并开通时,服务开通及信用下单同步成功或失败。
- 若因用户信用评估不通过导致无法完成下单并开通,支付宝会自动转入普通支付流程,用户可按订单金额直接完成付款。
*下单并开通示意图
*
开通并下单失败,转为普通支付示意图
流程说明
- 商家通过 alipay.trade.app.pay(app支付接口2.0),唤起支付宝客户端进行信用下单并开通。
-
- 商户 App 可查看 App 支付产品介绍。
- 小程序:
-
-
- 使用 sdkExecute 方法,通过 response.getBody(),获取到签名参数,用于支付接口的 orderStr。
- 然后使用小程序唤起支付接口 my.tradePay 完成小程序信用下单:
-
/*名称:my.tradePay
类型:小程序接口
功能:支付订单字符串通过小程序方式唤起支付
注意:该场景下,请参考如下编写:*/
my.tradePay({
orderStr: 'myOrderStr', //完整的支付参数拼接成的字符串,从服务端获取
success: (res) => {
my.alert({
content: JSON.stringify(res),
});
},
fail: (res) => {
my.alert({
content: JSON.stringify(res),
});
}
});
-
下单并开通成功后:
-
- 通过 zhima.credit.payafteruse.creditbizorder.changed(芝麻先享信用服务订单状态变更通知)发送信用下单结果的异步通知。
- 通过 zhima.credit.payafteruse.creditagreement.changed(服务开通/授权状态变更通知)发送用户开通结果的异步通知。
API 列表
下单并开通接口重要入参:
名称 | 是否必传 | 示例 | 描述 |
---|---|---|---|
product_code | 是 | QUICK_MSECURITY_PAY | 先用后付开通并下单必须传:QUICK_MSECURITY_PAY |
extend_params | 是 | - | 业务扩展参数 |
--creditTradeScene | 是 | 信用交易场景 | 必须上送:CREDIT_PAY |
--categoryId | 是 | 芝麻外部类目 | 申请接入芝麻先用后付服务时,芝麻分配给商户的外部类目 |
--serviceId | 是 | 芝麻服务ID | 申请接入芝麻先用后付服务时,芝麻分配给商户的服务ID |
--creditTradeExtInfo | 是 | 芝麻扩展参数 | 芝麻扩展参数。商品或服务类目标识:merchantCategoryCode收货地址:shippingAddress示例:"creditTradeExtInfo":"{"merchantCategoryCode":"food","shippingAddress":"浙江省西湖区西溪路556号"}" |
接口列表:
接口描述 | API接口 | 备注 |
---|---|---|
下单并开通 | alipay.trade.app.pay | 适用场景:下单并开通、信用下单(用户确认场景),调用该接口下单,由用户确认支付 |
信用服务订单查询 | zhima.credit.payafteruse.creditbizorder.query | 信用下单后,通过此接口查询信用订单详情 |
信用服务订单状态变更通知 | zhima.credit.payafteruse.creditbizorder.changed | 消息通知类接口,订阅方式订阅方式可查看 From 蚂蚁消息。通过此接口获取信用订单的状态变动通知。 |
服务开通/授权状态变更通知 | zhima.credit.payafteruse.creditagreement.changed | 消息通知类接口,订阅方式订阅方式可查看 From 蚂蚁消息。通过此接口获取用户先享服务开通状态变更通知。例如:新开通,用户主动解除等。 |
信用下单
用户开通服务后在商户平台购买商品或消费,使用芝麻先享下单,商家可以直接调用信用下单服务进行免密支付。
业务规则
- 根据订单金额是否超过免密信用下单额度(前期与支付宝签约时事先约定),流程不同:
-
- 普通信用下单:下单金额 <= 免密信用下单金额,用户提交订单后无需跳转支付宝,在商户端内直接完成信用下单。
- 信用下单(超额确认场景):下单金额 > 免密信用下单金额,仍可使用信用下单模式,但需要用户跳转到支付宝侧进行确认金额是否准确,确认后完成信用下单。
- 当用户本次信用下单,命中芝麻校验规则,例如需用户通过兑换权益进行单次下单、用户服务协议变更等需要用户确认的场景时,服务会返回特定错误码 ACQ.ZM_AUTH_RULE_LIMIT,此时用户仍可使用信用下单模式,但需要更换调用 alipay.trade.app.pay(app支付接口2.0),用户跳转到支付宝侧进行确认后继续下单。
- 芝麻先享服务开通后,若用户存在未履约等行为会导致用户信用风险提升,风险用户不支持继续使用芝麻先享下单,信用恢复后可正常使用。
信用下单示意图
信用下单(用户确认场景)示意图
流程说明
信用下单(已开通下单)
- 已开通芝麻先享用户在商户客户端商品页面进行商品购买。
- 商家客户端请求商户服务端下单服务,商家服务端调用支付宝信用下单接口 alipay.trade.pay(统一收单交易支付接口)进行信用下单。
- 下单完成后,支付宝侧会同步返回信用下单的结果。同时也会通过接口 zhima.credit.payafteruse.creditbizorder.changed(芝麻先享信用服务订单状态变更通知)发送异步通知。支付宝同步返回结果里,credit_pay_mode='creditAdvanceV2' 表明信用下单成功。
- 商家还可以主动查询,调用 alipay.trade.query(统一收单线下交易查询接口),查询结果里credit_pay_mode='creditAdvanceV2' 表明信用下单成功。
- 特殊需要注意流程说明:调用 alipay.trade.pay(统一收单交易支付接口)下单时,若由于用户关闭了芝麻先享服务或者下单金额超过免密额度而导致信用下单失败。商户可以通过识别该接口返回的错误码(ACQ.ZM_AUTH_AMOUNT_EXCEED 、ACQ.ZM_CREDIT_AUTH_FAIL、ACQ.ZM_AUTH_RULE_LIMIT),改为调用 alipay.trade.app.pay(app支付接口2.0)通过用户确认模式尝试重新信用下单。
http://openapi.alipay.com/gateway.do?charset=UTF-8&biz_content={"out_trade_no":"ch06280001","product_code":"GENERAL_WITHHOLDING","subject":"商品名称","total_amount":20,"timeout_express":"1d","is_async_pay":false,"auth_code":"ZMOP99202103100100990000506689","scene":"ZHIMA_AUTH_CODE","extend_params":{"zmCategoryId":"credit_payment_000001","creditTradeScene":"CREDIT_PAY"}}&method=alipay.trade.pay&sign_type=RSA×tamp=2021-06-28 19:27:23&sign=WgYY//7Y2jf//R5jekdicYXG/GlIfvTN0jXhFoNw8+LBB8bOZtcA48QEGVsgDGlN/on2SqWBAtnUo9bNdHIp7mB7H2juE2IM4TSW1bVBO5Ni358RcKVFmq506fRpiMbS0XAqC6zb+gE0mqsXkugJGND/+yAbrgYDMK16xkqI1HA=&app_id=2019032360876122
信用下单(用户确认场景)
- 商家通过 alipay.trade.app.pay(app支付接口2.0),唤起支付宝 App 进行信用下单并开通。
-
- 商户App 可查看 App 支付产品介绍。
- 小程序:
-
-
- 使用 sdkExecute 方法,通过 response.getBody(),获取到签名参数,用于支付接口的 orderStr。
- 然后使用小程序唤起支付接口 my.tradePay 完成小程序信用下单:
-
/*名称:my.tradePay
类型:小程序接口
功能:支付订单字符串通过小程序方式唤起支付
注意:该场景下,请参考如下编写:*/
my.tradePay({
orderStr: 'myOrderStr', //完整的支付参数拼接成的字符串,从服务端获取
success: (res) => {
my.alert({
content: JSON.stringify(res),
});
},
fail: (res) => {
my.alert({
content: JSON.stringify(res),
});
}
});
- 完成信用下后,支付宝会通过 zhima.credit.payafteruse.creditbizorder.changed(芝麻先享信用服务订单状态变更通知)发送信用下单后的异步通知。
API列表
alipay.trade.pay 接口重要入参:
名称 | 是否必传 | 本次传参说明 | 描述 |
---|---|---|---|
scene | 是 | ZHIMA_AUTH_CODE | 芝麻先享场景必须上送:ZHIMA_AUTH_CODE |
product_code | 是 | GENERAL_WITHHOLDING | 信用下单使用代扣产产品码:GENERAL_WITHHOLDING, |
auth_code | 是 | 芝麻先享协议号 | 开通接口中返回的credit_agreement_id |
extend_params | 是 | 业务扩展参数 | |
--creditTradeScene | 是 | 信用交易场景 | 必须上送:CREDIT_PAY |
--zmCategoryId | 是 | 芝麻外部类目 | 申请接入芝麻先享服务时,芝麻分配给商户的外部类目 |
--creditTradeExtInfo | 是 | 芝麻扩展参数 | 芝麻扩展参数。商品或服务类目标识:merchantCategoryCode收货地址:shippingAddress示例:"creditTradeExtInfo":"{"merchantCategoryCode":"food","shippingAddress":"浙江省西湖区西溪路556号"}" |
接口列表:
接口说明 | API 接口 | 备注 |
---|---|---|
信用服务下单 | alipay.trade.pay | 已开通且订单金额超免密金额限制、芝麻校验不通过等场景,该接口下单返回如下错误码时,需要切换至信用下单(用户确认场景)下单:ACQ.ZM_AUTH_AMOUNT_EXCEEDACQ.ZM_CREDIT_AUTH_FAIL ACQ.ZM_AUTH_RULE_LIMIT |
信用服务下单(用户确认场景) | alipay.trade.app.pay | 用户确认下单流程,适用于下单并开通、超过免密金额等场景。 |
信用服务订单查询 | zhima.credit.payafteruse.creditbizorder.query | 查询信用服务订单当前状态订单信息 |
结束信用服务订单接口 | zhima.credit.payafteruse.creditbizorder.finish | 确认该服务订单无需继续扣款或用户已履约完成,则调用完结接口,结束对应信用服务订单,用户芝麻信用守约记录状态同步更新。 |
信用服务订单状态变更通知 | zhima.credit.payafteruse.creditbizorder.changed | 消息通知类接口,订阅方式订阅方式可查看 From 蚂蚁消息。信用服务订单状态变更时会发送该通知:下单时信用服务订单创建成功,结束时信用服务订单完成或取消等。 |
扣款
用户在商户平台选择芝麻先享下单后,在体验到期时,商户平台基于下单金额向用户发起扣款。
业务规则
-
若在固定扣款周期内,商户平台扣款成功,用户信用服务订单状态变更为结束,并积累用户信用记录。
-
若在固定扣款周期内,商户平台扣款失败
-
- 若商户合作模式为担保模式时,由芝麻合作担保机构垫付至商户平台后,即为扣款成功,后续由担保机构自行向用户账户发起追缴扣款;
- 若商户合作模式为非担保模式时,支付宝向从用户账户扣款。
-
信用服务订单在扣款时的扣款金额不能超过代扣限额,一个信用服务订单仅支持一次扣款,且退款后不支持再次扣款。
-
若用户账户持续未扣款/追缴扣款成功,用户信用服务订单将进入逾期状态,直到扣款成功后进入守约状态。
-
扣款成功的订单才会生成业务账单用于商户对账、以及下一步的结算、分账等操作。
-
商户扣款阶段,芝麻先享具备智能代扣服务,商户发起一次扣款,支付宝将自动智能对用户扣款,协助商家提高回款效率。在集成流程上,商家发起扣款调用 alipay.trade.order.pay(统一收单交易订单支付接口)时,需要传递参数 is_async_pay = true。不会同步返回支付结果,商家需监听 扣款异步通知。
流程说明
1、用户在商户客户端操作确认收货,商户客户端请求商户服务端确认收货。
2、商户服务端调用支付宝订单扣款接口,支付宝接口名 alipay.trade.order.pay(统一收单交易订单支付接口)。
3、支付宝收到扣款请求,处理扣款。如果是非担保模式,则支付宝会同步返回本次扣款结果。如果是担保模式,则支付宝同步返回受理成功,然后异步扣款,后面扣款成功后会给商户发送扣款成功异步通知。通知说明见 扣款异步通知。
4、如果是担保模式,对于扣款结果,商户还可以主动查询,调用支付宝查询接口 alipay.trade.query,交易状态 trade_status = 'TRADE_SUCCESS' 就说明扣款成功,'WAIT_BUYER_PAY' 说明扣款还没成功。
https://openapi.alipay.com/gateway.do?charset=UTF-8&biz_content={"trade_no":"2021042122001480821459702880","fulfillment_amount":"2.0","out_request_no":"pre-test-0004","order_pay_mode":"CREDIT_FULFILLMENT_ZM","is_async_pay":"true","advance_payment_type":"CREDIT_FULFILLMENT_ZM"}&method=alipay.trade.order.pay&sign_type=RSA×tamp=2021-04-21 16:12:23&sign=cptKYiUDz/1FEFAq0GNbyzlM1XoU0kt3aKN3sSLqGYTIi7g5g0tzNfQWt121wEeQnFpVTaViujF6nb72rr+92dcMguHveJHWvzBAmkvsEoBAyT3NioIuQ81703H+7Ij04hlyPEGM+2wCE36BL7xqhCsenn6zhSn40mgB4gbEi58=&app_id=2016122604628016
API列表
alipay.trade.order.pay 重要入参说明:
名称 | 示例值 | 描述 |
---|---|---|
fulfillment_amount | 88.88 | 信用服务订单本次扣款金额,目前只支持全额扣款,即必须与信用服务订单金额一致。单位为元,精确到小数点后两位。 |
order_pay_mode | CREDIT_FULFILLMENT_ZM | 芝麻先享场景必须上送:CREDIT_FULFILLMENT_ZM |
advance_payment_type | CREDIT_FULFILLMENT_ZM | 商户签约为担保模式时:上送CREDIT_FULFILLMENT_ZM,从用户账户扣款失败时,会自动进行垫资处理。不上送则不会进行垫资;商户签约为非担保模式时,此字段不用上送,上送无效。 |
is_async_pay | true | 传 true 时,支付宝会在后台定时轮询扣款,无需商户重复发起,且芝麻先享产品支持智能扣款能力,显著提高商户回款效率。传入 true 时,不会同步返回支付结果,商家需监听扣款异步通知,详见下方异步通知参数。 |
接口列表:
接口说明 | API接口 | 备注 |
---|---|---|
扣款 | alipay.trade.order.pay | 信用服务订单到达扣款周期时,调用此接口扣款 |
退款 | alipay.trade.refund | 信用服务订单扣款成功后,若需要退款,复用通用退款接口进行退款 |
交易查询 | alipay.trade.query | 查询信用服务订单扣款结果 |
扣款异步通知
商户异步发送地址:支付宝会根据 alipay.trade.app.pay(app支付接口2.0)或 alipay.trade.pay(统一收单交易支付接口)中传入的异步通知地址 notify_url,通过 POST 请求的形式将支付结果作为参数通知到商家系统,具体参数如下:
参数 | 参数名称 | 类型 | 描述 |
---|---|---|---|
notify_time | 通知时间 | Date | 通知的发送时间。格式为 yyyy-MM-dd HH:mm:ss。 |
notify_type | 通知类型 | String(64) | 通知的类型。 |
notify_id | 通知校验ID | String(128) | 通知校验 ID。 |
sign_type | 签名类型 | String(10) | 商户生成签名字符串所使用的签名算法类型,目前支持 RSA2 和 RSA,推荐使用 RSA2(如果开发者手动验签,不使用 SDK 验签,可以不传此参数)。 |
sign | 签名 | String(256) | 请参考异步返回结果的验签(如果开发者手动验签,不使用 SDK 验签,可以不传此参数)。 |
trade_no | 支付宝交易号 | String(64) | 支付宝交易凭证号。 |
app_id | 开发者的app_id | String(32) | 支付宝分配给开发者的应用 Id。 |
out_trade_no | 商户订单号 | String(64) | 原支付请求的商户订单号。 |
out_biz_no | 商户业务号 | String(64) | 商户业务 ID,主要是退款通知中返回退款申请的流水号 |
buyer_id | 买家支付宝用户号 | String(16) | 买家支付宝账号对应的支付宝唯一用户号。以 2088 开头的纯 16 位数字。 |
buyer_logon_id | 买家支付宝账号 | String(100) | 买家支付宝账号。 |
seller_id | 卖家支付宝用户号 | String(30) | 卖家支付宝用户号。 |
seller_email | 卖家支付宝账号 | String(100) | 卖家支付宝账号。 |
trade_status | 交易状态 | String(32) | 交易目前所处的状态。 |
total_amount | 订单金额 | Number(9,2) | 本次交易支付的订单金额,单位为人民币(元)。 |
receipt_amount | 实收金额 | Number(9,2) | 商家在交易中实际收到的款项,单位为元。 |
invoice_amount | 开票金额 | Number(9,2) | 用户在交易中支付的可开发票的金额。 |
buyer_pay_amount | 付款金额 | Number(9,2) | 用户在交易中支付的金额。 |
refund_fee | 总退款金额 | Number(9,2) | 退款通知中,返回总退款金额,单位为元,支持两位小数。 |
send_back_fee | 实际退款金额 | Number(9,2) | 商户实际退款给用户的金额,单位为元,支持两位小数。 |
subject | 订单标题 | String(256) | 商品的标题/交易标题/订单标题/订单关键字等,是请求时对应的参数,原样通知回来。 |
body | 商品描述 | String(400) | 该订单的备注、描述、明细等。对应请求时的body参数,原样通知回来。 |
gmt_create | 交易创建时间 | Date | 该笔交易创建的时间。格式为 yyyy-MM-dd HH:mm:ss。 |
gmt_payment | 交易付款时间 | Date | 该笔交易的买家付款时间。格式为 yyyy-MM-dd HH:mm:ss。 |
gmt_refund | 交易退款时间 | Date | 该笔交易的退款时间。格式为 yyyy-MM-dd HH:mm:ss.S。 |
gmt_close | 交易结束时间 | Date | 该笔交易结束时间。格式为 yyyy-MM-dd HH:mm:ss。 |
fund_bill_list | 支付金额信息 | String(512) | 支付成功的各个渠道金额信息,详见资金明细信息说明。 |
交易状态说明
枚举名称 | 枚举说明 |
---|---|
WAIT_BUYER_PAY | 交易创建,等待买家付款 |
TRADE_CLOSED | 未付款交易超时关闭,或支付完成后全额退款 |
TRADE_SUCCESS | 交易支付成功 |
TRADE_FINISHED | 交易结束,不可退款 |
触发条件
触发条件名 | 触发条件描述 | 触发条件默认值 |
---|---|---|
TRADE_FINISHED | 交易完成 | false(不触发通知) |
TRADE_SUCCESS | 支付成功 | true(触发通知) |
WAIT_BUYER_PAY | 交易创建 | false(不触发通知) |
TRADE_CLOSED | 交易关闭 | false(不触发通知) |
异步返回结果验签
某商户设置的通知地址为 https://api.xx.com/receive_notify.htm
,对应接收到通知的示例如下:
https://api.xx.com/receive_notify.htm?gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34&seller_email=testyufabu07@alipay.com¬ify_type=trade_status_sync&sign=kPbQIjX+xQc8F0/A6/AocELIjhhZnGbcBN6G4MM/HmfWL4ZiHM6fWl5NQhzXJusaklZ1LFuMo+lHQUELAYeugH8LYFvxnNajOvZhuxNFbN2LhF0l/KL8ANtj8oyPM4NN7Qft2kWJTDJUpQOzCzNnV9hDxh5AaT9FPqRS6ZKxnzM=&trade_no=2015061121001004400068549373&out_trade_no=21repl2ac2eOutTradeNo322&gmt_create=2015-06-11 22:33:46&seller_id=2088211521646673¬ify_time=2015-06-11 22:34:03&subject=xxx中文&trade_status=TRADE_SUCCESS&sign_type=RSA2
- 在通知返回参数列表中,除去 sign、sign_type 两个参数外,凡是通知返回回来的参数皆是待验签的参数。
- 将剩下参数进行 url_decode, 然后进行字典排序,组成字符串,得到待签名字符串:
gmt_create=2015-06-11 22:33:46&gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34¬ify_time=2015-06-11 22:34:03¬ify_type=trade_status_sync&out_trade_no=21repl2ac2eOutTradeNo322&seller_email=testyufabu07@alipay.com&seller_id=2088211521646673&subject=xxx中文&trade_no=2015061121001004400068549373&trade_status=TRADE_SUCCESS
- 将签名参数(sign)使用 base64 解码为字节码串。
- 使用 RSA/RSA2 的验签方法,通过签名字符串、签名参数(经过 base64 解码)及支付宝公钥验证签名。
- 需要严格按照如下描述校验通知数据的正确性。
-
- 商户需要验证该通知数据中的 out_trade_no 是否为商户系统中创建的订单号。
- 判断 total_amount 是否确实为该订单的实际金额(即商户订单创建时的金额)。
- 校验通知中的 seller_id(或者seller_email) 是否为 out_trade_no 这笔单据的对应的操作方。
上述有任何一个验证不通过,则表明本次通知是异常通知,务必忽略。在上述验证通过后商户必须根据支付宝不同类型的业务通知,正确的进行不同的业务处理,并且过滤重复的通知结果数据。在支付宝的业务通知中,只有交易通知状态为 TRADE_SUCCESS 或 TRADE_FINISHED 时,支付宝才会认定为买家付款成功。
注意
- 状态 TRADE_SUCCESS 的通知触发条件是商家开通的产品支持退款功能的前提下,买家付款成功。
- 状态 TRADE_FINISHED 的通知触发条件是商家开通的产品不支持退款功能的前提下,买家付款成功;或者,商家开通的产品支持退款功能的前提下,交易已经成功并且已经超过可退款期限。
结束信用服务订单
信用下单后,用户即生成一个服务中的信用服务订单,若用户使用先享服务后完成扣款,系统扣款成功则自动将信用服务订单完结,为用户积累芝麻分。若用户发起退款,则该信用服务订单不需要进行扣款,则需要商户主动结束信用服务订单,将信用服务订单取消。
业务规则
- 若信用下单后,正常通过扣款接口完成扣款,会自动结束信用服务订单,不需要单独调用结束服务。
- 若买家发起退款,必须调用结束接口将信用服务订单完结,否则用户在芝麻的信用服务订单会一直处于服务使用中的状态。
- 结束后的信用服务订单,无法再发起扣款。
流程说明
- 商家侧通过 zhima.credit.payafteruse.creditbizorder.finish(结束信用服务订单接口)结束信用服务订单。结束订单后,将不能继续发起扣款。
- 支付宝侧会通过 zhima.credit.payafteruse.creditbizorder.changed(芝麻先享信用服务订单状态变更通知)异步通知结束订单的结果。
API列表
关键参数说明:
关键字段 | 描述 | 备注 |
---|---|---|
is_fulfilled | 是否履约标识 | 用户此订单是否守约。传 true 时,用户在芝麻信用-守约记录中,该笔订单是已守约状态。传 false 时,用户在芝麻信用-守约记录中,该笔订单是已取消状态。is_fulfilled 不传值默认 false。 |
接口列表:
接口描述 | API接口 | 备注 |
---|---|---|
结束信用服务订单接口 | zhima.credit.payafteruse.creditbizorder.finish | 当该订单无需扣款或用户已守约,调用该接口完结或取消信用服务订单。核心入参 is_fulfilled 将影响用户信用状态,请参照接口具体描述。 |