• 下载
  • 社区

资金授权

产品介绍

产品概述


用户在租车、充电桩、酒店预订等场景消费时,用户在开启服务时需要做一笔资金授权,当服务完结算时,再从授权资金中扣除消费金额,剩余返还给用户。

支付宝资金授权支持余额,余额宝,信用卡,借记卡,花呗以及芝麻信用等渠道,其中:

  • 余额,余额宝做资金冻结;

  • 信用卡,借记卡扣款至支付宝内部账户做资金锁定;

  • 花呗锁定额度(推荐),不产生账期,用户不需要马上还款;

  • 芝麻信用以用户信用为担保并授权。


备注

  • 转支付扣款时,以信用担保授权的订单将轮询用户资金渠道(余额,余额宝,花呗、银行卡等)扣除相应资金(扣款顺序以用户在支付宝钱包内设置为准);

  • 商户发起授权转支付成功后,可通过参数控制是否解冻剩余冻结金额。


用户线上提交订单,触发商户的预授权功能,并打开授权确认界面,用户仅需在支付宝收银台中输入支付密码,确认授权后,即可完成授权。



页面流程


用户在使用资金授权时的页面流程如下图所示:



使用说明

业务流程



使用步骤


  1. 用户搜索访问小程序或扫码访问小程序以后,点击充电桩首页“立即充电”;
  2. 商户后台生成订单,并且在小程序里自动跳转至支付宝资金授权界面;
  3. 用户在支付宝收银台中输入支付密码,确认授权
  4. 支付宝将信用授权结果同步返回给商户;
  5. 消费完成后实际结算时,商家根据实际消费情况直接从授权资金中发起授权转支付,用户无需参与,仅在实际扣款成功后收到推送通知。


资金授权调用说明


资金授权商户端的操作流程和调用接口情况如下图所示:


应用案例


案例 1:

租赁商家可使用花呗预授权产品能力,冻结用户花呗额度当押金,缓解用户租赁商品(尤其是贵价商品)需支付押金的资金压力,降低租赁业务门槛。以租手机为例:



案例 2:

自助办公场景



准入条件


  • 企业可申请(具体以在线签约为准);

  • 需提供真实有效的营业执照,且支付宝账户名称需与营业执照主体一致;

  • 提供小程序名称或产品说明文档,开发者与支付宝账户名称不一致需提供开发合作协议。


计费模式  


支付宝资金授权阶段不收费;预授权转支付阶段计收费,按收款方收款金额的 0.6% 实时收费。


接入指引

第一步:创建小程序


要在您的小程序内使用 订单中心功能,您需要首先完成开发者入驻创建小程序


第二步:添加功能


小程序创建完成后,开发者在 功能列表 部分可以点击 添加功能 来添加 支付宝资金授权 功能。勾选相应功能后,点击 确定 即可添加功能。


第三步:签约功能


支付宝资金授权 需要签约才能生效,在小程序上线后,请点击功能列表右侧对应功能的 签约 链接;签约成功后,需要 1 个工作日左右的审批时间(审批结果会以短信和邮件形式告知),审批成功后,功能状态会变为“已生效”,即可调用 支付宝资金授权 功能。


第四步:集成并配置 SDK


服务端 SDK 需要商户集成在自己的服务端系统中,用于后续的服务端接口调用。

下载服务端 SDK

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

接口调用配置

在 SDK 调用前需要进行初始化,以 JAVA 代码为例:

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


关键参数说明:

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


接下来,就可以用 alipayClient 来调用具体的 API 了。alipayClient 只需要初始化一次,后续调用不同的 API 都可以使用同一个 alipayClient 对象。


注意:

ISV /开发者可以通过第三方应用授权得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力。




签约流程(主流程)

开发者签约并接入资金授权的具体流程如下图所示:




关键流程说明


  1. 整体流程包含预授权、授权转支付、对账三个阶段;

  1. 用户通过支付宝小程序扫一扫,请求商户订单,在订单中选择选择信用充,信用授权/资金授权后开启充电;

  1. 充电完毕后,调用预授权转支付接口直接扣款;

  1. 主流程接口包含线上资金授权冻结接口(alipay.fund.auth.order.app.freeze)、客户端支付/小程序支付接口(用于唤起支付宝收银台)、统一收单交易支付接口( alipay.trade.pay );

  1. 提供资金授权操作查询(alipay.fund.auth.operation.detail.query、资金授权解冻(alipay.fund.auth.order.unfreeze、资金授权撤销(alipay.fund.auth.operation.cancel、交易查询(alipay.trade.query)、交易退款(alipay.trade.refund)、支付宝订单信息同步接口(alipay.trade.orderinfo.sync、对账单地址查询(alipay.data.dataservice.bill.downloadurl.query接口辅助业务流程。

  1. 异步通知:为保证一致性,包含异步通知接口会异步通知到商户,异步通知地址通过请求入参传进来。


资金处理说明


  1. 预授权冻结授权金额根据场景需求,设置合理值;

  1. 如果用户享受信用授权,不会冻结用户资金;如果用户享受资金授权,则冻结授权金额数;

  1. 预授权转支付时,传入实际支付金额,支付金额不大于授权金额;用户无需参与,扣款成功后会收到通知;

  1. 若未发起授权转支付,用户资金授权超过 36 个月(默认,具体根据协议确定),支付宝将驱动自动解除;

  1. 若授权转支付成功后,须商户发起解冻剩余金额(授权金额-支付金额)或者由支付宝解除,详情参考授权转支付接口部分;

  1. 若存在0租金订单,可调用解冻接口实现0租金订单,具体查看解冻接口说明;

  1. 授权转支付失败,商户可在15天内发起重试扣款,扣款时请保持交易订单号不变;

  1. 若15天内尝试扣款失败,请调用支付宝订单信息同步接口,反馈用户违约状态,芝麻届时会记录用户负面记录。


第五步:调用接口

线上资金预授权冻结

名称:alipay.fund.auth.order.app.freeze

类型:服务端接口

功能:创建支付宝授权订单并完成资金冻结。适用于线上场景完成资金授权, 例如从支付宝小程序端拉起支付宝收银台完成冻结。


该接口为通用接口,该场景下,请参考如下编写:


/**
 * 测试
 */
@Test
public void fundAuthOrderAppFreeze() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","utf-8","alipay_public_key","RSA2");
    AlipayFundAuthOrderAppFreezeRequest request = new AlipayFundAuthOrderAppFreezeRequest();
    AlipayFundAuthOrderAppFreezeModel model = new AlipayFundAuthOrderAppFreezeModel();
    model.setOrderTitle("支付宝资金授权");
    model.setOutOrderNo("2018077735255938023");//替换为实际订单号
    model.setOutRequestNo("2018077735255938232");//替换为实际请求单号,保证每次请求都是唯一的
    model.setPayeeUserId("payee_user_id");//payee_user_id,Payee_logon_id不能同时为空
    model.setPayeeLogonId("Payee_logon_id");
    model.setProductCode("PRE_AUTH_ONLINE");//PRE_AUTH_ONLINE为固定值,不要替换
    model.setAmount("0.02");
    //需要支持信用授权,该字段必传
    model.setExtraParam("{\"category\":\"CHARGE_PILE_CAR\",\"outStoreCode\":\"charge001\",\"outStoreAlias\":\"充电桩北京路点\"}"); //outStoreAlias将在用户端信用守护、支付信息、账单详情页展示
    request.setBizModel(model);
    request.setNotifyUrl(notify_url);//异步通知地址,必填,该接口只通过该参数进行异步通知
    AlipayFundAuthOrderAppFreezeResponse response = alipayClient.sdkExecute(request);//注意这里是sdkExecute,可以获取签名参数
    if(response.isSuccess()){
        System.out.println("调用成功");
        logger.info("response: {}"+response.getBody());//签名后的参数,直接入参到
    } else {
        System.out.println("调用失败");
    }
}


入参建议:

1. 创建 alipayClient 的 charset 请使用 utf-8。

2. product_code=PRE_AUTH_ONLINE,产品码为固定值,不要更改; 3Payee_user_id(商户 PID),Payee_logon_id(商户登录 ID)不能同时为空。

3. extraParam={"category":"CHARGE_PILE_CAR","outStoreCode":"charge0011","outStoreAlias":"充电桩北京路点"} 扩展参数,category=CHARGE_PILE_CAR 固定值,表示充电桩行业(category为业务分类,请查看具体类目信息),outStoreCode 传入充电桩编号,outStoreAlias 传入充电桩名称,outStoreAlias 将在用户端信用守护、支付信息、账单详情页展示。

4. enablePayChannels 为选填字段,可以指定支付渠道,如果不传,默认为签约协议的支付渠道;若需要指定渠道,目前仅支持余额宝(MONEY_FUND)、花呗(PCREDIT_PAY)以及芝麻信用(CREDITZHIMA)。

5. 建议开发者不要只以同步通知为准,也需接入异步通知。因为有些情况下同步通知超时,但资金冻结成功,此时需要异步通知。 

6. 如需异步通知,则必须传入 notify_url 参数,通过该参数接收异步通知,否则会导致无法接收异步回调参数返回值。

7. 请使用 sdkExecute 方法,通过 response.getBody(),获取到签名参数,用于支付接口的 orderStr。


返回结果样例


{
    "body": "alipay_sdk=alipay-sdk-java-3.0.118.DEV&app_id=2018112803019836&biz_content=%7B%22amount%22%3A%220.02%22%2C%22extra_param%22%3A%22%7B%5C%22category%5C%22%3A%5C%22CHARGE_PILE_CAR%5C%22%7D%22%2C%22order_title%22%3A%22%D6%A7%B8%B6%B1%A6%D4%A4%CA%DA%C8%A8%22%2C%22out_order_no%22%3A%22ZMOutOrderNoAppFreeze2018052915543415090975%22%2C%22out_request_no%22%3A%22ZMOutReqNoAppFreeze20180529155434581875858%22%2C%22pay_timeout%22%3A%222d%22%2C%22payee_user_id%22%3A%222088202224929664%22%2C%22product_code%22%3A%22PRE_AUTH_ONLINE%22%7D&charset=GBK&format=json&method=alipay.fund.auth.order.app.freeze&sign=L4wk%2FNKcbJOo3n6Q5qbPzn0jUsvZlK4jr7iXnghudR0zeWJMmeNC71qIBSQfIz45n%2B5iTd0NQ5IK581xI2xCShTCiKAywnQcDmA%2Bjf%2BrRdKCDQCMLfCz%2BZ37C%2B6zxAX3e81%2F8Hr29lw4VPFfHkp9FmMwKw%2FGkNfV5ZlWoh7UtN8%3D&sign_type=RSA&timestamp=2018-05-29+15%3A54%3A35&version=1.0"
}

通过 response.getBody() 获取 orderStr。


成功样例


{
"alipay_fund_auth_order_app_freeze_response":{
    "code":"10000",
    "msg":"Success",
    "auth_no":"2014070800002001550000014417",
    "out_order_no":"4977164666634053",
    "operation_id":"2014070800032850551",
    "out_request_no":"2014070700166653",
    "amount":0.02,
    "status":"SUCCESS",
    "payer_user_id":"2088102000275885",
    "gmt_trans":"2014-09-15 11:23:04",
    "pre_auth_type":"CREDIT_AUTH",
    "credit_amount":0.01,
    "fund_amount":0.01
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


失败样例


{
    "alipay_fund_auth_order_app_freeze_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


出参处理:  

1、response 中的 status=SUCCESS 表示预授权成功;INIT:初始状态,表示已创建授权单,等待用户密码确认;CLOSED:关闭状态,超时未授权,支付宝将授权单关闭后的状态;

2、pre_auth_type=CREDIT_AUTH 时,表示信用预授权,不会真实冻结资金;如果 pre_auth_type 返回值为空或不为“CREDIT_AUTH”,则表示普通资金预授权,会冻结用户资金;

3、对于授权金额单笔不超过200元,累积未结清限额200元,且芝麻信用达标的用户可以免冻结账户资金;授权金额单笔大于200元、累积未结清额度大于200或风控系统需要验证用户身份的情况下,支付宝APP会唤起收银台让用户输入密码确认授权冻结,此时 status=INIT,表示用户授权中,可调用资金授权操作查询接口(alipay.fund.auth.operation.detail.query)每隔5秒钟查询一次授权冻结的状态,如依然是用户授权中,则再等待5秒钟继续使用查询接口查询,直至1分钟后超时(推荐每隔5秒查询一次,共进行12次查询,具体根据商户业务情况决定),如超时前最后一次查询依然返回用户授权中,则马上调用资金授权撤销接口(alipay.fund.auth.operation.cancel)将该笔预授权冻结交易撤销;

4、如接口返回系统异常,先通过查询接口查询授权冻结的状态,并根据查询结果进行后续操作;

5、返回错误码为 SYSTEM_ERROR 时,请调用查询接口确定授权状态,并根据状态确定下一步操作;

6、对于未消费的预授权订单(预授权成功,但未进行授权转支付),请使用定时任务做好解冻或撤销,避免影响用户信用额度,造成不必要的客诉。


通知样例


https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&auth_no=2014070800002001550000014417&out_order_no=4977164666634053&operation_id=2014070800032850551&out_request_no=8077735255938032&operation_type=FREEZE&amount=0.01&status=SUCCESS&gmt_create=2014-09-15 11:23:04&gmt_trans=2014-09-15 11:23:04&payer_logon_id=test***@alitest.com&payer_user_id=2088102000275885&payee_logon_id=159****5620&payee_user_id=2088102000275795&total_freeze_amount=0.01&total_unfreeze_amount=0.01&total_pay_amount=0.01&rest_amount=0.01&pre_auth_type=CREDIT_AUTH


小程序唤起冻结

名称:my.tradePay

类型:小程序接口

功能:商户在支付宝钱包内,可通过该小程序接口唤起预授权冻结流程(入参即接入流程中获取的 orderStr)


Tips: 开发者需通过真机调试的方式调试该接口的功能,若用IDE调试该接口则会报无效的api入参。

接口为通用接口,该场景下,请参考如下编写:


my.tradePay({
  orderStr: 'myOrderStr', //完整的支付参数拼接成的字符串,从服务端获取
  success: (res) => {
    my.alert({
    content: JSON.stringify(res),
  });
  },
  fail: (res) => {
    my.alert({
    content: JSON.stringify(res),
  });
  }
});


资金授权解冻

名称:alipay.fund.auth.order.unfreeze

类型:服务端接口

功能:当资金授权发生之后一段时间内,由于买家或者商家等其他原因需要要解冻资金,商家可通过资金授权解冻接口将授权资金进行解冻,支付宝将在收到解冻请求并验证成功后,按解冻规则将冻结资金按原路进行解冻。


接口为通用接口,该场景下,请参考如下编写:


/**
 * 测试预授权解冻
 */
@Test
public void fundAuthOrderUnFreeze() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipayFundAuthOrderUnfreezeRequest request = new AlipayFundAuthOrderUnfreezeRequest();
    AlipayFundAuthOrderUnfreezeModel model = new AlipayFundAuthOrderUnfreezeModel();
    model.setAuthNo("2017120410002001390208978986"); // 支付宝资金授权订单号,在授权冻结成功时返回需要入库保存
    model.setOutRequestNo("UnfreezeRequestNo000003");//同一商户每次不同的资金操作请求,商户请求流水号不能重复,且与冻结流水号不同
    model.setAmount("0.01"); // 本次操作解冻的金额,单位为:元(人民币),精确到小数点后两位
    model.setRemark("预授权解冻"); // 商户对本次解冻操作的附言描述,长度不超过100个字母或50个汉字 
    request.setBizModel(model);
    AlipayFundAuthOrderUnfreezeResponse response = alipayClient.execute(request);
    logger.info("response: {}"+response.getBody());
}


注意

1、支持全额解冻和部分解冻;

2、解冻转支付时,若 auth_confirm_mode=complete,无需调用解冻接口,支付宝端在扣款成功后会自动解冻剩余金额;若auth_confirm_mode=not_complete,在收到支付成功通知后,商户自行调用解冻接口将余额进行解冻; 3、对于信用授权订单,扣款处理中或扣款失败(如:trade_ status=WAIT_BUYER_PAY 或 ORDER SUCCESS PAY INPROGRESS),若调用解冻接口,会中断支付宝扣款流程,请慎用;

4、extraParam 为选填字段,只对信用授权订单生效,若订单为0元订单,extraParam 传入 {"unfreezeBizInfo":"{\"bizComplete\":\"true\"}"},将为用户生成芝麻履约订单。


资金预授权撤销

名称:alipay.fund.auth.operation.cancel 类型:服务端接口 功能:只有商户由于业务系统处理超时需要终止后续业务处理或者授权结果未知时可调用撤销,其他正常授权冻结的操作如需实现相同功能请调用资金授权解冻服务。提交资金授权后调用资金授权操作查询,没有明确的授权结果再调用资金预授权撤销


接口为通用接口,该场景下,请参考如下编写:


/**
 * 测试预授权撤销
 */
@Test
public void fundAuthCancel() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipayFundAuthOperationCancelRequest request = new AlipayFundAuthOperationCancelRequest();
    AlipayFundAuthOperationCancelModel model = new AlipayFundAuthOperationCancelModel();
    //model.setAuthNo("2017120110002001390206804295"); // 支付宝资金授权订单号,在授权冻结成功时返回参数中获得
    model.setOutOrderNo("orderFreeze000005"); //商户的授权资金订单号,与支付宝的授权资金订单号不能同时为空
    //model.setOperationId("20171201317348823902"); //支付宝的授权资金操作流水号
    model.setOutRequestNo("requestNo000005");//与支付宝的授权资金操作流水号不能同时为空,与冻结流水号相同
    model.setRemark("预授权撤销"); // 商户对本次撤销操作的附言描述,长度不超过100个字母或50个汉字       
    request.setBizModel(model);
    AlipayFundAuthOperationCancelResponse response = alipayClient.execute(request);
    logger.info("response: {}"+response.getBody());
}


资金授权转支付

名称:alipay.trade.pay

类型:服务端接口

功能:在商户发起扣款时,可调用该接口进行预授权解冻转支付


接口为通用接口,该场景下,请参考如下编写:

/**
 * 测试
 */
@Test
public void tradePay() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","utf-8","alipay_public_key","RSA2");
    
    AlipayTradePayRequest request = new AlipayTradePayRequest();
    
    AlipayTradePayModel model = new AlipayTradePayModel();
    model.setOutTradeNo("20180412100020088982"); // 预授权转支付商户订单号,为新的商户交易流水号
    model.setProductCode("PRE_AUTH_ONLINE"); // 固定值PRE_AUTH_ONLINE
    model.setAuthNo("2018041210002001660228733635"); // 填写预授权冻结交易号
    model.setSubject("预授权转支付测试"); // 解冻转支付标题,用于展示在支付宝账单中
    model.setTotalAmount("0.01"); // 结算支付金额
    model.setSellerId(pid); // 填写卖家支付宝账户pid
    model.setBuyerId(pay_user_id); // 填写预授权用户uid,通过预授权冻结接口返回的payer_user_id字段获取
    model.setStoreId("test_store_id"); // 填写实际交易发生的终端编号,与预授权的outStoreCode保持一致即可   
    model.setBody("预授权解冻转支付测试"); // 可填写备注信息
    model.setAuthConfirmMode("COMPLETE");//传入COMPLETE时,用户剩余金额会自动解冻
    request.setBizModel(model);
    
    AlipayTradePayResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        System.out.println("调用成功");
        logger.info("response: {}"+response.getBody());
    } else {
        System.out.println("调用失败");
    }
}


入参说明:

1、product_code=PRE_AUTH_ONLINE,产品码,是固定值,不要更改;

2、需要传入 store_id(建议与资金授权冻结接口中 extra_param 参数的 outStoreCode 取值一致)参数。如果需返佣接入时还需要传入"extend_params":{"sys_service_provider_id":"ISV签约账户的PID"} 参数用于计算返佣。

3、auth_confirm_mode 传入 COMPLETE,无需调用解冻接口,支付宝端在扣款成功后会自动解冻剩余金额,同时该笔授权订单完成;若 auth_confirm_mode=NOT_COMPLETE,在收到支付成功通知后,商户自行调用解冻接口将余额进行解冻;

4、如果需要从一笔授权中完成多笔订单支付,保持 auth_no 不变,不同订单根据 outTradeNo 进行标识,此时auth_confirm_mode不传或者传入NOT_COMPLETE;进行到最后一笔转支付时,auth_confirm_mode 传入 COMPLETE 由支付宝完成剩余金额自动解冻,或者商户自行调用解冻接口将剩余金额解冻。


出参处理:

1、response 中的 code=10000,表示接口调用成功,支付状态以异步通知为准;

2、auth_trade_pay_mode,预授权支付模式,该参数仅在信用预授权支付场景下返回。信用预授权支付: CREDIT_PREAUTH_PAY;

3、如果未收到异步通知,可以通过交易查询接口查询最新支付状态,如果返回处理中(如:trade_ status=WAIT_BUYER_PAY 或ORDER SUCCESS PAY INPROGRESS)场景,商户可以调用预授权转支付(首次扣款15天内都可重试),重新发起扣款(注意:商户订单号out_trade_no保持不变)。


成功样例


{
    "alipay_trade_pay_response": {
        "code": "10000",
        "msg": "Success",
        "auth_trade_pay_mode": "CREDIT_PREAUTH_PAY",
        "buyer_logon_id": "x***@163.com",
        "buyer_pay_amount": "0.00",
        "buyer_user_id": "208822323293534",
        "gmt_payment": "2018-07-04 14:53:06",
        "invoice_amount": "0.00",
        "out_trade_no": "ZMOutTradeNoTradePay20180704145304679018382",
        "point_amount": "0.00",
        "receipt_amount": "0.00",
        "total_amount": "0.01",
        "trade_no": "2018070421001004660568415769"
    },
    "sign": "cHoNGyETgo2+L5ngyKhjRewR1KH1ZhtlaQ9+nq247/jlVm08/+o1ynIOX5ZRjCsPrDyJbwlwgpaqtN6Hdv8QY/53+UWM5NtR4EIQThvg52NRV2iWZhVNMm3jVrbNgnsmOemTYLfXAO0682K4R0QvS5cn45TGRFEq5o5cjlzFAIWx6mDVC7dYn/UF7HiF3xycqSTUbBZgjZ4EzWRSJWbnn36zRu8IKU4GNr9ArGBz3tEDXaCxSSxm9H3ErwarHdHZOfz0bA+4aJMWaxY/kV7BPRB30/ECwuOI7cFO8pwgjWbEoD6ZqwBO2YkvAKCMW4foNJ5L764Bn1QNJvkz9+2gLQ=="
}


失败样例


{
    "alipay_trade_pay_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


资金授权操作查询

名称:alipay.fund.auth.operation.detail.query

类型:服务端接口

功能:通过该接口可以查询单笔明细的详细信息,细分到每一次操作,如冻结、解冻。


接口为通用接口,该场景下,请参考如下编写:


/**
 * 测试资金授权操作查询
 */
@Test
public void fundAuthQuery() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipayFundAuthOperationDetailQueryRequest request = new AlipayFundAuthOperationDetailQueryRequest();
    AlipayFundAuthOperationDetailQueryModel model = new AlipayFundAuthOperationDetailQueryModel();
    //model.setAuthNo("2017120110002001390206804295"); // 支付宝资金授权订单号,在授权冻结成功时返回参数中获得
    model.setOutOrderNo("orderFreeze000003"); //商户的授权资金订单号,与支付宝的授权资金订单号不能同时为空
    //model.setOperationId("20171201317348823902"); //支付宝的授权资金操作流水号,冻结成功同步返回
    model.setOutRequestNo("requestNo000003");//商户的授权资金操作流水号,与支付宝的授权资金操作流水号不能同时为空,该值为冻结或解冻是的outRequestNo
    request.setBizModel(model);
    AlipayFundAuthOperationDetailQueryResponse response = alipayClient.execute(request);
    logger.info("response: {}"+response.getBody());
}



统一收单线下交易查询

名称:alipay.trade.query

类型:服务端接口

功能:通过该接口可以查询单笔明细的详细信息。


接口为通用接口,该场景下,请参考如下编写:


/**
 * 
 *测试预授权交易查询
 */
@Test
public void testTradeQuery() throws Exception {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipayTradeQueryModel model = new AlipayTradeQueryModel();
    model.setOutTradeNo("tradePay000002");
    AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
    request.setBizModel(model);
    AlipayTradeQueryResponse response = alipayClient.execute(request);
    logger.info("response: {}"+ response.getBody());
}


入参说明:

outTradeNo 为授权转支付时传入的 outTradeNo。


出参处理:

如果查询返回处理中(如:trade_ status=WAIT_BUYER_PAY 或 ORDER SUCCESS PAY INPROGRESS),商户可以调用预授权转支付,重新发起扣款(注意:商户订单号 out_trade_no 保持不变)


统一收单交易退款

名称:alipay.trade.refund

类型:服务端接口

功能:当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,支付宝将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。 交易超过约定时间(签约时设置的可退款时间)的订单无法进行退款 支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。一笔退款失败后重新提交,要采用原来的退款单号。总退款金额不能超过用户实际支付金额。


接口为通用接口,该场景下,请参考如下编写:


/**
 * 测试预授权交易退款
 */
@Test
public void testTradeRefund() throws Exception {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipayTradeRefundModel model = new AlipayTradeRefundModel();
    model.setOutTradeNo("tradePay000002"); //与预授权转支付商户订单号相同,代表对该笔交易退款
    model.setRefundAmount("0.01");
    model.setRefundReason("预授权退款测试");    
    model.setOutRequestNo("refund0000001");//标识一次退款请求,同一笔交易多次退款需要保证唯一,如部分退款则此参数必传。
    AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();
    request.setBizModel(model);
    AlipayTradeRefundResponse response = alipayClient.execute(request);
    logger.info("response: {}"+response.getBody());
}



支付宝订单信息同步接口

名称:alipay.trade.orderinfo.sync

类型:服务端接口

功能:该接口用于商户向支付宝同步该笔订单相关业务信息。


接口为通用接口,该场景下,请参考如下编写:


public void testTradeInfoSync() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","utf-8","alipay_public_key","RSA2");
    AlipayTradeOrderinfoSyncRequest request = new AlipayTradeOrderinfoSyncRequest();
    AlipayTradeOrderinfoSyncModel model = new AlipayTradeOrderinfoSyncModel();
    model.setBizType("CREDIT_AUTH");
    model.setTradeNo("2018061021001004680073956707");
    model.setOutRequestNo(genBizNo("OutRequestNo", "OrderInfoSync"));
    model.setOrderBizInfo("{\"orderInfo\":\"{\\\"status\\\":\\\"COMPLETE\\\"}\"}");

    request.setBizModel(model);
    AlipayTradeOrderinfoSyncResponse response = alipayClient.execute(request);
    logger.info("response: {}" + response.getBody());
    Assert.assertTrue(response.isSuccess());
}


接口使用场景

1、预授权订单为全信用或者部分信用授权订单;

2、针对授权转支付扣款失败的订单,请在首次授权转支付失败T+N之后调用该接口;

3、orderInfo 中的 status 包含:COMPLETE(用户已履约)、VIOLATED(用户已违约);

4、COMPLETE(用户已履约):如果用户通过其他方式完成订单支付,请反馈该状态,芝麻将对用户形成一条良好履约记录;

5、VIOLATED(用户已违约):如果用户在约定时间(具体根据行业约定,可联系 BD )内未完成订单支付,反馈该状态,芝麻将对用户记录一条负面记录;


入参说明:

1、bizType 为 CREDIT_AUTH 为固定值;

2、tradeNo 为授权转支付返回的 tradeNo。


出参处理:

1、当返回 ACQ.NOTIFY_STATUS_INVALID,表示当前无法反馈该状态,请稍后再试。



查询对账单下载地址

名称:alipay.data.dataservice.bill.downloadurl.query

类型:服务端接口

功能:为方便商户快速查账,支持商户通过本接口获取商户离线账单下载地址。


注意

该接口默认不输出账单,调用前提供商户ID和名称,联系BD进行申请。


接口为通用接口,该场景下,请参考如下编写:


/**
 * 测试
 */
@Test
public void billQuery() throws AlipayApiException {
    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipayDataDataserviceBillDownloadurlQueryRequest request = new AlipayDataDataserviceBillDownloadurlQueryRequest();
    request.setBizContent("{" +
                        "\"bill_type\":\"trade\"," +
                        "\"bill_date\":\"2018-04-05\"" +
                        "}");
    AlipayDataDataserviceBillDownloadurlQueryResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        System.out.println("调用成功");
        System.out.println("下载地址:" + response.getBillDownloadUrl());
    } else {
        System.out.println("调用失败");
    }
}


返回结果:


{
    "billDownloadUrl": "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=trade&userId=20880315752097830156&fileType=csv.zip&bizDates=20180612&downloadFileName=20880315752097830156_20180612.csv.zip&fileId=%2Ftrade%2F20880315752097830156%2F20180612.csv.zip&timestamp=1529063362&token=6d390c70765bb110ce303d9680e8871a",
    "code": "10000",
    "msg": "Success",
    "body": "{\"alipay_data_dataservice_bill_downloadurl_query_response\":{\"code\":\"10000\",\"msg\":\"Success\",\"bill_download_url\":\"http:\\/\\/dwbillcenter.alipay.com\\/downloadBillFile.resource?bizType=trade&userId=20880315752097830156&fileType=csv.zip&bizDates=20180612&downloadFileName=20880315752097830156_20180612.csv.zip&fileId=%2Ftrade%2F20880315752097830156%2F20180612.csv.zip&timestamp=1529063362&token=6d390c70765bb110ce303d9680e8871a\"},\"sign\":\"bilfAOig2ujJeu7LszKRFPSktd1U1ujAmxFMT9BzATQY0a53CzP8JXqXCLbwR1HocYZd8/Q6sS8As+HeA6BloOdKd7zw0H1RF7KNKYt0BPI45Exc3avKNmJ5RPK0Lnp5LNBFjtE0bCQoMkT04N6uXbmbm686PX/I4Nw26PcIWd6Mj4cm6kght+H1d//T3SeWUnZlC/Fnmyvidvr0BwVe0CWI52tDMzQ5fgaFdAucrVVjy1YxYMSWr1RK/8hSaLQOYtQ7WuGA2WIxrM3++6d9jBPPU9vVBGVKkaXBPDAgNZnADrBEX4EvYIc++s9GZAoPwaZvsqXEBPuJiDg/yyLbpQ==\"}",
    "params": {
        "biz_content": "{\"bill_type\":\"trade\",\"bill_date\":\"2018-06-12\"}"
    }
}


注意

下载地址有效时间为30秒,请尽快下载。


异步通知


为保证数据的一致性,芝麻系统会给商户发送订单操作成功通知。只有订单操作成功才会给商户发送通知。


异步通知接收地址设置

通过 线上资金授权冻结接口 alipay.fund.auth.order.app.freeze 接收冻结异步通知,通知地址即接口中传入的 notify_url,具体通知参数查看上文的接口详解。


异步通知样例


{
    "body": "alipay_sdk=alipay-sdk-java-3.0.118.DEV&app_id=2018112803019836&biz_content=%7B%22amount%22%3A%220.02%22%2C%22extra_param%22%3A%22%7B%5C%22category%5C%22%3A%5C%22CHARGE_PILE_CAR%5C%22%7D%22%2C%22order_title%22%3A%22%D6%A7%B8%B6%B1%A6%D4%A4%CA%DA%C8%A8%22%2C%22out_order_no%22%3A%22ZMOutOrderNoAppFreeze2018052915543415090975%22%2C%22out_request_no%22%3A%22ZMOutReqNoAppFreeze20180529155434581875858%22%2C%22pay_timeout%22%3A%222d%22%2C%22payee_user_id%22%3A%222088202224929664%22%2C%22product_code%22%3A%22PRE_AUTH_ONLINE%22%7D&charset=GBK&format=json&method=alipay.fund.auth.order.app.freeze&sign=L4wk%2FNKcbJOo3n6Q5qbPzn0jUsvZlK4jr7iXnghudR0zeWJMmeNC71qIBSQfIz45n%2B5iTd0NQ5IK581xI2xCShTCiKAywnQcDmA%2Bjf%2BrRdKCDQCMLfCz%2BZ37C%2B6zxAX3e81%2F8Hr29lw4VPFfHkp9FmMwKw%2FGkNfV5ZlWoh7UtN8%3D&sign_type=RSA&timestamp=2018-05-29+15%3A54%3A35&version=1.0"
}

通过 response.getBody() 获取 orderStr。


验签方法

同步接口和异步通知验签,请参考验签流程。


异步通知接收代码规范

接收程序执行完后必须打印输出“success”(不包含引号)。如果商户反馈给支付宝的字符不是“success”这7个字符,服务器会不断重发通知,直到超过24小时22分钟。一般情况下,25小时以内完成8次通知(通知的间隔频率一般是 4m,10m,10m,1h,2h,6h,15h); 接收程序执行完成后,该页面不能执行页面跳转。如果执行页面跳转,支付宝会接收不到success字符,会被支付宝服务器判定为该页面程序运行出现异常,而重发处理结果通知;

代码示例:


/**
 * 异步通知代码示例
 */
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException,
                                                                                   IOException {
    // 获取请求参数
    Map<String, String> params = RequestUtil.getRequestParams(request);
    String notifyType = params.get("notify_type");

    // 不同消息类型,执行不同业务逻辑
    if("xxxx".equals(notifyType)) {
        processBizMsg(request,response);
        return;
    } 

}

/**
 * 业务信息处理
 */
public void processBizMsg(final HttpServletRequest request, HttpServletResponse response) throws IOException {

        //1、验签
        ……

        //2、通知参数解析
        Map<String, String[]> notifyParams = request.getParameterMap();
        String notifyParamStr=JSONObject.toJSONString(notifyParams);
        System.out.println("异步通知:" + notifyParamStr);
        
        //3、执行业务逻辑
        ……

        //4、向芝麻反馈处理是否成功
        PrintWriter writer = null;
        try {
            writer = response.getWriter();
            writer.write("success"); //一定要打印success
            writer.flush();
        } finally {
            if (writer != null) {
                writer.close();
            }
        }
    }
}



API 列表


此列表包含所涉及的所有接口,点击可查看接口的公共请求参数,业务请求参数,返回参数,其他语言请求示例以及错误码等。

接口英文名称

接口中文名称

alipay.fund.auth.order.app.freeze

线上资金授权冻结接口

alipay.fund.auth.order.unfreeze

资金授权解冻接口

alipay.fund.auth.operation.cancel

资金授权撤销接口

alipay.fund.auth.operation.detail.query

资金授权操作查询接口

alipay.trade.pay

统一收单交易支付接口

alipay.trade.query

统一收单线下交易查询

alipay.trade.refund

统一收单交易退款接口

alipay.trade.orderinfo.sync

支付宝订单信息同步接口

alipay.data.dataservice.bill.downloadurl.query

查询对账单下载地址

my.tradePay

小程序支付接口

注意

开发者在调用统一收单交易支付接口(alipay.trade.pay)时,请注意以下参数变化:


  • 授权码的参数为 auth_no 而非当面付中的 auth_code;授权码也没有 25-30 开头的限制。
  • 资金授权过程中不需要 scene 参数。


常见问题

Q:资金授权场景下,在 IDE 上调用 my.tradePay 报错 “error2:无效API入参”,如何处理?

A:资金授权无法在 IDE 模拟器中进行测试,只能在真机上测试,请以真机调试结果为准。


Q: 资金授权冻结接口无法调起支付,如何处理?

A:问题分析如下:

可能原因 

  • 传入 my.tradePay 的  orderStr 参数错误,导致服务端回传的 orderStr 出错。
  • 资金授权无法在 IDE 模拟器中进行测试。

解决方案 

1. 请参考 资金授权 文档 接入指引 > 第五步:调用接口 > 线上资金预授权冻结,获取用于小程序支付的 orderStr 参数。

2. 将获得的 orderStr 参数传入 my.tradePay 中(设置为固定值),并在真机上进行测试。


Q: 资金授权时, 支付宝预授权报错“订单异常ALIN42683”,如何处理?

A:问题分析如下:

报错原因

OutOrderNo 和 OutRequestNo 重复请求。(OutOrderNo 和 OutRequestNo 参数详情请参见 线上资金授权冻结。)

解决方案

1. 确保 OutOrderNo 和 OutRequestNo 入参在商家系统中唯一 (只传入OutOrderNo 或只传入 OutRequestNo)。

2. 检查参数是否按照文档要求设置,建议只传必传参数测试,避免其他参数干扰。

Q:报错ALI38173/ALI38110

A:检查请求参数,对照我们的线上文档查看,比如:接口中参数少了、多了、乱码、名称不对,还有必传参数是否都请求提交给支付宝了等等。

Q. 资金授权最大金额限制?

A: 取值范围[0.01,100000000.00]。