接口详解

资金授权冻结接口 alipay.fund.auth.order.freeze


商户使用扫码枪等条码识别设备扫描用户支付宝钱包上的条码,完成用户资金授权,根据是否需要输入密码可分为:免密模式和验密模式。


服务调用流程:
免密模式:

验密模式:

  • 商户系统将用户付款码与订单信息一起通过资金授权冻结接alipay.fund.auth.order.freeze请求到支付宝,并从接口同步返回中获取支付结果。

  • 根据公共返回参数中的code做相应后续业务处理。这笔授权操作可能有四种状态:授权成功(10000),授权失败(40004),等待用户授权(10003)和未知异常(20000)。


关键入参:

参数名称

参数说明

out_order_no

商户授权资金订单号,需要保证不重复

out_request_no

商户授权资金操作流水号,需要保证不重复

auth_code

用户付款码

auth_code_type

固定值传入bar_code

order_title

订单标题

amount

冻结金额

pay_timeout

授权超时时间

payee_logon_id

收款方支付宝账号(Email或手机号),如果收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)同时传递,则以用户号(payee_user_id)为准,如果商户有勾选花呗渠道,收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)不能同时为空。

payee_user_id

收款方的支付宝唯一用户号,以2088开头的16位纯数字组成,如果非空则会在支付时校验交易的的收款方与此是否一致,如果商户有勾选花呗渠道,收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)不能同时为空。

product_code

销售产品码,后续新接入当面资金授权业务,本字段取值固定为PRE_AUTH。

enable_pay_channels

商户可用该参数指定用户可使用的支付渠道,本期支持三种支付渠道,余额宝(MONEY_FUND)、花呗(PCREDIT_PAY)以及芝麻信用(CREDITZHIMA)。商户可设置一种支付渠道,也可设置多种支付渠道。参数值格式为:[{"payChannelType":"PCREDIT_PAY"},{"payChannelType":"MONEY_FUND"},{"payChannelType":"CREDITZHIMA"}]

extra_param

业务扩展参数,用于商户的特定业务信息的传递,json格式。

1.间联模式必须传入二级商户ID,key为secondaryMerchantId; 2. 当面资金授权业务对应的类目,key为category,value由支付宝分配,酒店业务传 "HOTEL",充电桩业务传"CHARGE_PILE_CAR",传统租车传"TRAD_RENT_CAR",信用预授权必传; 3. 外部商户的门店编号,key为outStoreCode,当需要支持信用授权时必传; 4. 外部商户的门店简称,key为outStoreAlias,当需要支持信用授权时必传。


关键出参:

参数名称

参数说明

auth_no

支付宝28位授权资金订单号

operation_id

支付宝标识本次资金操作的流水号

status

本次资金授权操作的状态

pre_auth_type

授权类型,目前支持CREDIT_AUTH(信用授权);商户可根据该标识来判断该笔类型,当返回值为“CREDIT_AUTH”表明该笔为信用授权,没有真实冻结资金;当返回值为空或者不为“CREDIT_AUTH”则表明该笔为普通资金授权,有冻结用户资金


TIPS:商户授权订单号out_order_no和资金操作流水号out_request_no在任何情况下不可重复,即使对于失败或撤销的授权冻结操作,商户授权订单号和资金操作流水号也可能已经被使用了,如需再次发起授权,必须使用新的商户授权订单号和资金操作流水号调用接口,否则会报错。


资金授权发码接口 alipay.fund.auth.order.voucher.create


收银员通过收银台或商户后台调用支付宝接口,生成二维码后,展示给用户,由用户扫描二维码完成资金冻结。


业务规则:
1)授权冻结支持的支付渠道以及默认冻结顺序:花呗>余额宝>余额>信用卡>借记卡。如果用户在支付宝客户端有设置默认扣款顺序,则以用户设置为准。
2)授权验证密码规则:用户通过钱包app进行密码授权冻结。


调用流程:

关键入参:

参数名称

参数说明

out_order_no

商户授权资金订单号,需要保证不重复

out_request_no

商户授权资金操作流水号,需要保证不重复

order_title

订单标题

amount

冻结金额

pay_timeout

授权超时时间

payee_logon_id

收款方支付宝账号(Email或手机号),如果收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)同时传递,则以用户号(payee_user_id)为准,如果商户有勾选花呗渠道,收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)不能同时为空。

payee_user_id

收款方的支付宝唯一用户号,以2088开头的16位纯数字组成,如果非空则会在支付时校验交易的的收款方与此是否一致,如果商户有勾选花呗渠道,收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)不能同时为空。

enable_pay_channels

商户可用该参数指定用户可使用的支付渠道,本期支持三种支付渠道,余额宝(MONEY_FUND)、花呗(PCREDIT_PAY)以及芝麻信用(CREDITZHIMA)。商户可设置一种支付渠道,也可设置多种支付渠道。参数值格式为:[{"payChannelType":"PCREDIT_PAY"},{"payChannelType":"MONEY_FUND"},{"payChannelType":"CREDITZHIMA"}]

product_code

销售产品码,后续新接入当面资金授权业务,本字段取值固定为PRE_AUTH。

extra_param

业务扩展参数,用于商户的特定业务信息的传递,json格式。
1.间联模式必须传入二级商户ID,key为secondaryMerchantId; 2. 当面资金授权业务对应的类目,key为category,value由支付宝分配,酒店业务传 "HOTEL",充电桩业务传"CHARGE_PILE_CAR",传统租车传"TRAD_RENT_CAR",信用预授权必传; 3. 外部商户的门店编号,key为outStoreCode,当需要支持信用授权时必传; 4. 外部商户的门店简称,key为outStoreAlias,当需要支持信用授权时必传。


关键出参:

参数名称

参数说明

out_order_no

商户的授权资金订单号

out_request_no

商户本次资金操作的请求流水号

code_type

码类型,分为 barCode:条形码 (一维码) 和 qrCode:二维码(qrCode) ; 目前发码只支持 qrCode

code_value

当前发码请求生成的二维码码串,商户端可以利用二维码生成工具根据该码串值生成对应的二维码

code_url

生成的带有支付宝logo的二维码地址


资金授权解冻接口 alipay.fund.auth.order.unfreeze


商户因业务原因需要解冻用户授权资金时,可进行资金解冻,支持部分解冻。


业务规则:

  1. 冻结订单的资金解冻都需要由商户端发起,支付宝对冻结资金不会发起自动解冻;

  1. 解冻服务中的附言remark字段会展示在用户的支付宝账单上。


调用流程:

商户系统调用资金授权解冻接口alipay.fund.auth.order.unfreeze,传入支付宝订单号、解冻操作请求号、解冻金额等参数请求退款,并同步获得退款结果。


关键入参:

参数名称

参数说明

auth_no

支付宝28位授权资金订单号

out_request_no

商户授权资金操作流水号,需要保证不重复

amount

解冻金额

remark

操作描述,展示在用户支付宝账单上

extra_param

解冻扩展信息,json格式;

具体示例值:

{"unfreezeBizInfo": "{\"bizComplete\":\"true\"}"}

unfreezeBizInfo 目前为芝麻消费字段,支持Key值如下:
"bizComplete":"true" -- 选填:标识本次解冻用户是否履约,如果true信用单会完结为COMPLETE


关键出参:

参数名称

参数说明

auth_no

支付宝28位授权资金订单号

operation_id

支付宝标识本次资金操作的流水号

status

本次资金授权操作的状态


TIPS:解冻接口会根据商户的资金操作流水号out_request_no幂等返回,因此必须保证每次资金操作时需要使用不同的out_request_no。


资金授权撤销接口 alipay.fund.auth.operation.cancel


只有商户由于业务系统处理超时需要终止后续业务处理或者授权结果未知时可调用撤销,其他正常授权冻结的操作如需实现相同功能请调用资金授权解冻服务。


业务规则:
提交资金授权后调用【资金授权操作查询】,没有明确的授权结果再调用【资金授权撤销】。


关键入参:

参数名称

参数说明

auth_no

支付宝28位授权资金订单号

operation_id

支付宝资金授权冻结操作流水号

out_order_no

商户资金授权订单号

out_request_no

商户资金授权冻结操作流水号

remark

操作描述


关键出参:

参数名称

参数说明

action

本次撤销触发的动作 close:关闭订单,无资金解冻 unfreeze:产生了资金解冻


资金授权操作查询接口 alipay.fund.auth.operation.detail.query


通过该接口可以查询单笔资金授权操作明细的详细信息。


关键入参:

参数名称

参数说明

auth_no

支付宝28位授权资金订单号

operation_id

支付宝资金授权冻结操作流水号

out_order_no

商户资金授权订单号

out_request_no

商户资金授权冻结操作流水号


关键出参:

参数名称

参数说明

auth_no

支付宝28位授权资金订单号

operation_id

支付宝资金授权冻结操作流水号

out_order_no

商户资金授权订单号

out_request_no

商户资金授权冻结操作流水号

status

本次资金授权操作的状态


交易创建并支付接口 alipay.trade.pay


商户因业务原因需要解冻用户授权资金并支付给卖家时,通过该接口创建交易订单并将授权资金解冻转支付给卖家,同时解冻剩余资金。


业务规则:

  1. 商家通过系统调用支付宝的交易创建并支付服务将用户授权资金解冻转支付给卖家,该过程无需再次扫描用户钱包付款码;

  1. 交易创建并支付的金额应小于等于用户授权资金金额,当支付金额小于授权冻结金额时,剩余授权冻结金额需要商户再发起授权资金解冻请求将剩余冻结资金进行解冻。
    调用流程:

    商户系统调用交易创建并支付接口alipay.trade.pay,传入商户订单号,支付宝资金授权单号、商品信息、卖家信息,交易金额等参数请求交易支付,并同步获得交易支付结果。


关键入参:

参数名称

参数说明

out_trade_no

商户订单号,需要保证不重复

total_amount

订单金额

product_code

产品码,当面授权场景传固定值PRE_AUTH

auth_no

支付宝资金授权单号

subject

订单标题

buyer_id

买家支付宝uid,即资金授权用户uid,必传

seller_id

卖家支付宝uid,即资金授权收款方uid,必传

auth_confirm_mode

预授权转交易时结束预授权(并解冻剩余资金)时需要传入COMPLETE 或NOT_COMPLETE;其中当传入COMPLETE时,执行转支付给收款方并剩余授权资金解除;当传入NOT_COMPLETE或不传时,仅执行转支付给收款方

business_params

商户传入业务信息,具体值要和支付宝约定;非必传;

信用预授权场景可传入具体订单信息,具体示例值:

{"orderBizInfo":"{\"ChargeType\":\"rent\",\"PenaltyPoints\":\\"3分"}"}


业务参数样例:

"biz_content":{
    "out_trade_no":"20161122000000001",
    "auth_no":"2016111710002001390222200964",
    "product_code":"PRE_AUTH",
    "subject":"冻结转支付",
    "buyer_id":"2088202415071394:,
    "seller_id":"2088211521646673",
    "total_amount":0.01
    "auth_confirm_mode":"COMPLETE",
}


TIPS:商户订单号out_trade_no在任何情况下不可重复,即时对于失败或撤销的交易,商户订单号也可能已经被使用了,如需再次发起支付,必须使用新的商户订单号调用接口,否则会报错。


交易同步退款接口alipay.trade.refund


商户因业务原因需要退款时,可通过成功交易的商户订单号或支付宝交易号进行退款 ,支持部分退款。


调用流程:

商户系统调用交易退款接口alipay.trade.refund,传入商户订单号或支付宝交易号、退款请求号、退款金额等参数请求退款,并同步获得退款结果。


关键入参:

参数名称

参数说明

out_trade_no

支付时传入的商户订单号,与trade_no必填一个

trade_no

支付时返回的支付宝交易号,与out_trade_no必填一个

out_request_no

本次退款请求流水号,部分退款时必传

refund_amount

本次退款金额


关键出参:

参数名称

参数说明

refund_fee

该笔交易已退款的总金额


TIPS:退款接口会根据外部请求号out_request_no幂等返回,因此同一笔需要多次部分退款时,必须使用不同的out_request_no。


交易查询接口 alipay.trade.query


商户因后台、网络、服务器等出现异常,而未接收到支付通知时,可以通过本接口主动查询订单状态,来决策完成下一步的业务逻辑。


调用流程:

商户系统调用交易查询接口alipay.trade.query,传入商户订单号或支付宝交易号、同步返回交易订单信息。


关键入参:

参数名称

参数说明

out_trade_no

支付时传入的商户订单号,与trade_no必填一个

trade_no

支付时返回的支付宝交易号,与out_trade_no必填一个


关键出参:

参数名称

参数说明

trade_no

支付宝28位交易号

out_trade_no

支付时传入的商户订单号

trade_status

交易当前状态

请求参数示例

/**
测试预授权冻结
*/
@Test
public  void  fundAuthOrderFreeze()  throws  AlipayApiException  {
AlipayFundAuthOrderFreezeRequest  request  =  new  AlipayFundAuthOrderFreezeRequest();
AlipayFundAuthOrderFreezeModel  model  =  new  AlipayFundAuthOrderFreezeModel();
model.setAuthCode("2839999997473519824");  //  填写用户支付宝钱包中的付款码
model.setAuthCodeType("bar_code");  //  填写固定值bar_code
model.setOutOrderNo("orderFreeze0000011");  //  预授权冻结交易商户订单号,商户系统唯一标识一笔预授权
model.setOutRequestNo("requestNo0000011");
model.setOrderTitle("酒店信用预授权冻结测试");  //  预授权标题,会在支付宝账单中显示
model.setAmount("0.02");  //  预授权金额,注意需要大于等于结算支付金额
model.setPayeeUserId("2088501624737791");  //  收款方的支付宝唯一用户号,以2088开头的16位纯数字组成,收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)不能同时为空。
model.setPayTimeout("5m");  //  预授权冻结超时时间,超时则自动关闭冻结交易
model.setProductCode("PRE_AUTH");  //  填写固定值PRE_AUTH  
request.setBizModel(model);
request.setNotifyUrl("https://www.***.com/notify.htm");
AlipayFundAuthOrderFreezeResponse  response  =  alipayClient.execute(request);  //需要先创建DefaultAlipayClient类型对象alipayclient
logger.info("response:  {}"+response.getBody());
Assert.assertTrue(response.isSuccess());
}
/**
测试扫码预授权生成授权码
*/
@Test
public    void  fundAuthOrderVoucherCreate()  throws  AlipayApiException  {
AlipayFundAuthOrderVoucherCreateRequest  request  =  new  AlipayFundAuthOrderVoucherCreateRequest();
AlipayFundAuthOrderVoucherCreateModel  model  =  new  AlipayFundAuthOrderVoucherCreateModel();
model.setOutOrderNo("orderFreeze000008");  //  预授权冻结交易商户订单号,商户系统唯一标识一笔预授权
model.setOutRequestNo("requestNo000008");  //  商户授权资金操作流水号,不能重复
model.setOrderTitle("酒店预授权冻结测试");  //  预授权标题,会在支付宝账单中显示
model.setAmount("0.01");  //  预授权金额,注意需要大于等于结算支付金额
model.setPayeeUserId("2088501624737791");  //  收款方的支付宝唯一用户号,以2088开头的16位纯数字组成,收款方支付宝登录号(payee_logon_id)和用户号(payee_user_id)不能同时为空。
model.setPayTimeout("5m");  //  预授权冻结超时时间,超时则自动关闭冻结交易
model.setProductCode("PRE_AUTH");  //  填写固定值PRE_AUTH  
request.setBizModel(model);
AlipayFundAuthOrderVoucherCreateResponse  response  =  alipayClient.execute(request);
logger.info("response:  {}"+response.getBody());
Assert.assertTrue(response.isSuccess());
}
/**
测试预授权解冻
*/
@Test
public  void  fundAuthOrderUnFreeze()  throws  AlipayApiException  {
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());
Assert.assertTrue(response.isSuccess());
}
/**
测试预授权撤销
*/
@Test
public  void  fundAuthCancel()  throws  AlipayApiException  {
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());
Assert.assertTrue(response.isSuccess());
}
/**
测试资金授权操作查询
*/
@Test
public void fundAuthQuery() throws AlipayApiException {
AlipayFundAuthOperationDetailQueryRequest request = new AlipayFundAuthOperationDetailQueryRequest();
AlipayFundAuthOperationDetailQueryModel model = new AlipayFundAuthOperationDetailQueryModel();
//model.setAuthNo("2017120110002001390206804295"); // 支付宝资金授权订单号,在授权冻结成功时返回参数中获得
model.setOutOrderNo("orderFreeze000003"); //商户的授权资金订单号,与支付宝的授权资金订单号不能同时为空
//model.setOperationId("20171201317348823902"); //支付宝的授权资金操作流水号,冻结成功同步返回
model.setOutRequestNo("requestNo000003");//商户的授权资金操作流水号,与支付宝的授权资金操作流水号不能同时为空  
request.setBizModel(model);
AlipayFundAuthOperationDetailQueryResponse response = alipayClient.execute(request);
logger.info("response: {}"+response.getBody());
Assert.assertTrue(response.isSuccess());
}
/**
测试预授权解冻转支付,使用当面付接口,但使用PRE_AUTH即预授权的产品码
*/
@Test
public void testTradePay() throws Exception {
AlipayTradePayModel model = new AlipayTradePayModel();
model.setOutTradeNo("tradePay00000009");      //预授权转支付商户订单号,为新的商户交易流水号
model.setScene("bar_code");                // 固定值bar_code
model.setProductCode("PRE_AUTH");          // 固定值PRE_AUTH
model.setAuthNo("2018012410002001670257018719");  // 填写预授权冻结交易号
model.setSubject("预授权转支付测试");     // 解冻转支付标题,用于展示在支付宝账单中
model.setTotalAmount("0.01");             // 结算支付金额
model.setSellerId("2088501624737791");    // 填写卖家支付宝账户pid
model.setBuyerId("2088102852641672");     // 2088202415071394填写预授权用户uid,通过预授权冻结接口返回的payer_user_id字段获取
model.setBody("预授权解冻转支付测试");          // 可填写备注信息
model.setTerminalId("test_terminal_id");      // 填写商户操作员编号
model.setStoreId("test_store_id");    // 填写实际交易发生的终端编号
model.setTimeoutExpress("5m");             // 填写解冻转支付交易的超时时间
//     ExtendParams extendParams = new ExtendParams();
//      extendParams.setSysServiceProviderId("此处填写ISV签约返佣协议账户的PID为2088开头的16位数字");
//      model.setExtendParams(extendParams);  //系统商开发需要传入正确的返佣参数才能拿到返佣,无返佣协议不需要传入该参数。
model.setAuthConfirmMode("COMPLETE"); //自动解冻时取值COMPLETE,不传该参数默认剩余资金不会自动解冻NOT_COMPLETE。
AlipayTradePayRequest request = new AlipayTradePayRequest();
request.setBizModel(model);
request.setNotifyUrl("https://www.***.com/index.htm");
AlipayTradePayResponse response = alipayClient.execute(request);
logger.info("response: {}"+response.getBody());
Assert.assertTrue(response.isSuccess());
}
/**
测试预授权交易退款
*/
@Test
public void testTradeRefund() throws Exception {
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());
Assert.assertTrue(response.isSuccess());
}
/**
*测试预授权交易查询
*/
@Test
public void testTradeQuery() throws Exception {
AlipayTradeQueryModel model = new AlipayTradeQueryModel();
model.setOutTradeNo("tradePay000002");
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
request.setBizModel(model);
AlipayTradeQueryResponse response = alipayClient.execute(request);
logger.info("response: {}"+ response.getBody());                                     
Assert.assertTrue(response.isSuccess());
}


交易关闭接口alipay.trade.close

用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。


调用流程:

商户系统调用交易关闭接口alipay.trade.close,传入商户订单号或支付宝交易号。

关键入参:

参数名称

参数说明

out_trade_no

支付时传入的商户订单号,与trade_no必填一个

trade_no

支付时返回的支付宝交易号,与out_trade_no必填一个


关键出参:

参数名称

参数说明

trade_no

支付宝28位交易号

out_trade_no

支付时传入的商户订单号

支付宝订单信息同步接口alipay.trade.orderinfo.sync

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


调用流程:

商户系统调用订单信息同步接口alipay.trade.orderinfo.sync,传入该笔订单相关同步信息。


关键入参:

参数名称

参数说明

trade_no

支付时返回的支付宝交易号,与out_trade_no必填一个

out_request_no

外部请求号,商户多次同步信息时,需保证唯一

biz_type

交易信息同步对应的业务类型,具体值与支付宝约定;信用授权场景下传CREDIT_AUTH

order_biz_info

商户传入同步信息,具体值要和支付宝约定;用于芝麻信用租车、单次授权等信息同步场景,格式为json格式

示例值:

{\"status\":\"COMPLETE\"}


该状态的具体枚举值包括:
/** 用户已违约 */
VIOLATED
/** 用户已履约 */
COMPLETE
/** 开启用户支付入口 */
OPEN_PAY


关键出参:

参数名称

参数说明

trade_no

支付宝28位交易号

out_trade_no

支付时传入的商户订单号

buyer_user_id

买家在支付宝的用户id


onlineServer