资金授权

产品介绍

产品概述

用户在租车、充电桩、酒店预订等场景消费时，用户在开启服务时需要做一笔资金授权，当服务完结算时，再从授权资金中扣除消费金额，剩余返还给用户。支付宝资金授权支持余额，余额宝，信用卡，借记卡，花呗以及芝麻信用等渠道，其中：

  • 余额，余额宝做资金冻结；

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

  • 花呗锁定额度（推荐），不产生账期，用户不需要马上还款；

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

备注：

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

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

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

资金授权 - 图1

页面流程

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

资金授权 - 图2

使用说明

业务流程

资金授权 - 图3

使用步骤

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

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

应用案例

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

资金授权 - 图5

案例2：自助办公场景

资金授权 - 图6

准入条件

  • 企业可申请（具体以在线签约为准）；

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

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

签约方式

开发者在小程序管理后台“开发管理”页面中“功能列表”中添加“支付宝资金授权”功能包，添加后可点击签约进入签约流程，如不符合签约门槛，则在签约页面有相关文案提示。

计费模式

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

接入介绍

接入流程

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

资金授权 - 图7

关键流程说明

资金处理说明

  • 预授权冻结授权金额根据场景需求，设置合理值；

  • 如果用户享受信用授权，不会冻结用户资金；如果用户享受资金授权，则冻结授权金额数；

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

  • 若未发起授权转支付，用户资金授权超过 36 个月（默认，具体根据协议确定），支付宝将驱动自动解除；

  • 若授权转支付成功后，须商户发起解冻剩余金额（授权金额-支付金额）或者由支付宝解除，详情参考授权转支付接口部分；

  • 若存在0租金订单，可调用解冻接口实现0租金订单，具体查看解冻接口说明；

  • 若授权转支付失败，商户可在15天内发起重试扣款，扣款时请保持交易订单号不变；

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

接口详解

线上资金预授权冻结

名称：alipay.fund.auth.order.app.freeze类型：服务端接口功能：创建支付宝授权订单并完成资金冻结。适用于线上场景完成资金授权, 例如从支付宝小程序端拉起支付宝收银台完成冻结。

该接口为通用接口，该场景下，请参考如下编写：

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

入参建议:1、创建 alipayClient 的 charset 请使用 utf-8；2、product_code=PRE_AUTH_ONLINE，产品码为固定值，不要更改;3、Payee_user_id（商户 PID），Payee_logon_id（商户登录 ID）不能同时为空；4、extraParam={"category":"CHARGE_PILE_CAR","outStoreCode":"charge0011","outStoreAlias":"充电桩北京路点"} 扩展参数，category=CHARGE_PILE_CAR 固定值，表示充电桩行业（category为业务分类，请查看具体类目信息），outStoreCode 传入充电桩编号，outStoreAlias 传入充电桩名称，outStoreAlias 将在用户端信用守护、支付信息、账单详情页展示；5、enablePayChannels 为选填字段，可以指定支付渠道，如果不传，默认为签约协议的支付渠道；若需要指定渠道，目前仅支持余额宝（MONEY_FUND）、花呗（PCREDIT_PAY）以及芝麻信用（CREDITZHIMA）；6、notifyUrl 为必传参数，通过该参数进行异步通知接收；7、请使用 sdkExecute 方法，通过 response.getBody()，获取到签名参数，用于支付接口的 orderStr。

返回结果样例

  1. {
  2.     "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"
  3. }

通过 response.getBody() 获取 orderStr。

成功样例

  1. {
  2. "alipay_fund_auth_order_app_freeze_response":{
  3.     "code":"10000",
  4.     "msg":"Success",
  5.     "auth_no":"2014070800002001550000014417",
  6.     "out_order_no":"4977164666634053",
  7.     "operation_id":"2014070800032850551",
  8.     "out_request_no":"2014070700166653",
  9.     "amount":0.02,
  10.     "status":"SUCCESS",
  11.     "payer_user_id":"2088102000275885",
  12.     "gmt_trans":"2014-09-15 11:23:04",
  13.     "pre_auth_type":"CREDIT_AUTH",
  14.     "credit_amount":0.01,
  15.     "fund_amount":0.01
  16.   }
  17. ,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
  18. }

失败样例

  1. {
  2.     "alipay_fund_auth_order_app_freeze_response": {
  3.         "code": "20000",
  4.         "msg": "Service Currently Unavailable",
  5.         "sub_code": "isp.unknow-error",
  6.         "sub_msg": "系统繁忙"
  7.     },
  8.     "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
  9. }

出参处理： 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、对于未消费的预授权订单（预授权成功，但未进行授权转支付），请使用定时任务做好解冻或撤销，避免影响用户信用额度，造成不必要的客诉。

通知样例

  1. 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）。

接口为通用接口，该场景下，请参考如下编写：

  1. my.tradePay({
  2.   orderStr: 'myOrderStr', //完整的支付参数拼接成的字符串，从服务端获取
  3.   success: (res) => {
  4.     my.alert({
  5.       content: JSON.stringify(res),
  6.     });
  7.   },
  8.   fail: (res) => {
  9.     my.alert({
  10.       content: JSON.stringify(res),
  11.     });
  12.   }
  13. });

资金授权解冻

名称：alipay.fund.auth.order.unfreeze类型：服务端接口功能：当资金授权发生之后一段时间内，由于买家或者商家等其他原因需要要解冻资金，商家可通过资金授权解冻接口将授权资金进行解冻，支付宝将在收到解冻请求并验证成功后，按解冻规则将冻结资金按原路进行解冻。

接口为通用接口，该场景下，请参考如下编写：

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

注意：1、支持全额解冻和部分解冻；2、解冻转支付时，若 authconfirm_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类型：服务端接口功能：只有商户由于业务系统处理超时需要终止后续业务处理或者授权结果未知时可调用撤销，其他正常授权冻结的操作如需实现相同功能请调用资金授权解冻服务。提交资金授权后调用资金授权操作查询，没有明确的授权结果再调用资金预授权撤销。

接口为通用接口，该场景下，请参考如下编写：

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

资金授权转支付

名称：alipay.trade.pay类型：服务端接口功能：在商户发起扣款时，可调用该接口进行预授权解冻转支付。

接口为通用接口，该场景下，请参考如下编写：

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

入参说明: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、authtrade_pay_mode，预授权支付模式，该参数仅在信用预授权支付场景下返回。信用预授权支付： CREDIT_PREAUTH_PAY；3、如果未收到异步通知，可以通过交易查询接口查询最新支付状态，如果返回处理中（如：trade status=WAIT_BUYER_PAY 或ORDER SUCCESS PAY INPROGRESS）场景，商户可以调用预授权转支付（首次扣款15天内都可重试），重新发起扣款（注意：商户订单号out_trade_no保持不变）。

成功样例

  1. {
  2.     "alipay_trade_pay_response": {
  3.         "code": "10000",
  4.         "msg": "Success",
  5.         "auth_trade_pay_mode": "CREDIT_PREAUTH_PAY",
  6.         "buyer_logon_id": "x***@163.com",
  7.         "buyer_pay_amount": "0.00",
  8.         "buyer_user_id": "208822323293534",
  9.         "gmt_payment": "2018-07-04 14:53:06",
  10.         "invoice_amount": "0.00",
  11.         "out_trade_no": "ZMOutTradeNoTradePay20180704145304679018382",
  12.         "point_amount": "0.00",
  13.         "receipt_amount": "0.00",
  14.         "total_amount": "0.01",
  15.         "trade_no": "2018070421001004660568415769"
  16.     },
  17.     "sign": "cHoNGyETgo2+L5ngyKhjRewR1KH1ZhtlaQ9+nq247/jlVm08/+o1ynIOX5ZRjCsPrDyJbwlwgpaqtN6Hdv8QY/53+UWM5NtR4EIQThvg52NRV2iWZhVNMm3jVrbNgnsmOemTYLfXAO0682K4R0QvS5cn45TGRFEq5o5cjlzFAIWx6mDVC7dYn/UF7HiF3xycqSTUbBZgjZ4EzWRSJWbnn36zRu8IKU4GNr9ArGBz3tEDXaCxSSxm9H3ErwarHdHZOfz0bA+4aJMWaxY/kV7BPRB30/ECwuOI7cFO8pwgjWbEoD6ZqwBO2YkvAKCMW4foNJ5L764Bn1QNJvkz9+2gLQ=="
  18. }

失败样例

  1. {
  2.     "alipay_trade_pay_response": {
  3.         "code": "20000",
  4.         "msg": "Service Currently Unavailable",
  5.         "sub_code": "isp.unknow-error",
  6.         "sub_msg": "系统繁忙"
  7.     },
  8.     "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
  9. }

资金授权操作查询

名称：alipay.fund.auth.operation.detail.query类型：服务端接口功能：通过该接口可以查询单笔明细的详细信息，细分到每一次操作，如冻结、解冻。

接口为通用接口，该场景下，请参考如下编写：

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

统一收单线下交易查询

名称：alipay.trade.query类型：服务端接口功能：通过该接口可以查询单笔明细的详细信息。

接口为通用接口，该场景下，请参考如下编写：

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

入参说明:1、outTradeNo 为授权转支付时传入的 outTradeNo。

出参处理：1、如果查询返回处理中（如：trade_ status=WAIT_BUYER_PAY 或 ORDER SUCCESS PAY INPROGRESS），商户可以调用预授权转支付，重新发起扣款（注意：商户订单号 out_trade_no 保持不变）。

统一收单交易退款

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

接口为通用接口，该场景下，请参考如下编写：

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

支付宝订单信息同步接口

名称：alipay.trade.orderinfo.sync类型：服务端接口功能：该接口用于商户向支付宝同步该笔订单相关业务信息。

接口为通用接口，该场景下，请参考如下编写：

  1. public void testTradeInfoSync() throws AlipayApiException {
  2.     AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","utf-8","alipay_public_key","RSA2");
  3.     AlipayTradeOrderinfoSyncRequest request = new AlipayTradeOrderinfoSyncRequest();
  4.     AlipayTradeOrderinfoSyncModel model = new AlipayTradeOrderinfoSyncModel();
  5.     model.setBizType("CREDIT_AUTH");
  6.     model.setTradeNo("2018061021001004680073956707");
  7.     model.setOutRequestNo(genBizNo("OutRequestNo", "OrderInfoSync"));
  8.     model.setOrderBizInfo("{\"orderInfo\":\"{\\\"status\\\":\\\"COMPLETE\\\"}\"}");
  10.     request.setBizModel(model);
  11.     AlipayTradeOrderinfoSyncResponse response = alipayClient.execute(request);
  12.     logger.info("response: {}" + response.getBody());
  13.     Assert.assertTrue(response.isSuccess());
  14. }

接口使用场景：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进行申请。

接口为通用接口，该场景下，请参考如下编写：

  1. /**
  2.  * 测试
  3.  */
  4. @Test
  5. public void billQuery() throws AlipayApiException {
  6.     AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
  7.     AlipayDataDataserviceBillDownloadurlQueryRequest request = new AlipayDataDataserviceBillDownloadurlQueryRequest();
  8.     request.setBizContent("{" +
  9.                         "\"bill_type\":\"trade\"," +
  10.                         "\"bill_date\":\"2018-04-05\"" +
  11.                         "}");
  12.     AlipayDataDataserviceBillDownloadurlQueryResponse response = alipayClient.execute(request);
  13.     if(response.isSuccess()){
  14.         System.out.println("调用成功");
  15.         System.out.println("下载地址：" + response.getBillDownloadUrl());
  16.     } else {
  17.         System.out.println("调用失败");
  18.     }
  19. }

返回结果：

  1. {
  2.     "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",
  3.     "code": "10000",
  4.     "msg": "Success",
  5.     "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==\"}",
  6.     "params": {
  7.         "biz_content": "{\"bill_type\":\"trade\",\"bill_date\":\"2018-06-12\"}"
  8.     }
  9. }

注意：下载地址有效时间为30秒，请尽快下载。

异步通知

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

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

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

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

  1. /**
  2.  * 异步通知代码示例
  3.  */
  4. public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException,
  5.                                                                                    IOException {
  6.     // 获取请求参数
  7.     Map<String, String> params = RequestUtil.getRequestParams(request);
  8.     String notifyType = params.get("notify_type");
  10.     // 不同消息类型，执行不同业务逻辑
  11.     if("xxxx".equals(notifyType)) {
  12.         processBizMsg(request,response);
  13.         return;
  14.     } 
  16. }
  18. /**
  19.  * 业务信息处理
  20.  */
  21. public void processBizMsg(final HttpServletRequest request, HttpServletResponse response) throws IOException {
  23.         //1、验签
  24.         ……
  26.         //2、通知参数解析
  27.         Map<String, String[]> notifyParams = request.getParameterMap();
  28.         String notifyParamStr=JSONObject.toJSONString(notifyParams);
  29.         System.out.println("异步通知:" + notifyParamStr);
  31.         //3、执行业务逻辑
  32.         ……
  34.         //4、向芝麻反馈处理是否成功
  35.         PrintWriter writer = null;
  36.         try {
  37.             writer = response.getWriter();
  38.             writer.write("success"); //一定要打印success
  39.             writer.flush();
  40.         } finally {
  41.             if (writer != null) {
  42.                 writer.close();
  43.             }
  44.         }
  45.     }
  46. }

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 参数。