线上资金授权冻结

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


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

/**
 * 测试
 */
@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\":\"xxx\",\"outStoreCode\":\"charge001\",\"outStoreAlias\":\"充电桩北京路点\"}"); //outStoreAlias将在用户端信用守护、支付信息、账单详情页展示
    //选填字段,指定支付渠道
    //model.setEnablePayChannels("[{\"payChannelType\":\"PCREDIT_PAY\"},{\"payChannelType\":\"MONEY_FUND\"},{\"payChannelType\":\"CREDITZHIMA\"}]");
    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("调用失败");
    }
}


入参TIPS:
1、创建alipayClient的charset请使用utf-8;

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

3、out_order_no和out_request_no不能包含除中文、英文、数字以外的字符;
4、payee_user_id(商户PID),payee_logon_id(商户登录ID)不能同时为空;

5、extra_param={"category":"xxx","outStoreCode":"code0011","outStoreAlias":"codeName"}扩展参数,category为业务分类,请查看具体类目信息,outStoreCode选填参数,outStoreAlias选填参数,outStoreAlias将在用户端信用守护、支付信息、账单详情页展示;如果要使用信用授权,一定要传入该参数;

6、enable_pay_channels为选填字段,可以指定支付渠道,若需要指定渠道,可以传入具体的某个渠道参数,目前仅支持余额宝(MONEY_FUND)、花呗(PCREDIT_PAY)以及芝麻信用(CREDITZHIMA);如果不传,则默认为商家签约时候的渠道,用户做预授权的时候可以选择使用具体的某个渠道,比如余额、余额宝、花呗、银行卡;

7、notifyUrl必传参数,通过该参数进行异步通知接收;

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


注意事项

1、如果商家想使用(信用+资金)授权,则 category必传;在这种场景下,当用户信用条件满足的时候则走信用授权流程,如果不满足则走资金授权的流程 ; (优先使用信用授权流程,信用流程不满足则走资金授权流程)

2、如果商家只想使用信用授权, 则category必传和enable_pay_channels参数中的CREDITZHIMA必传;在这种场景下,当用户信用条件满足的时候则走信用授权流程,如果不满足则无法使用信用授权,也无法使用资金授权流程;(只能使用信用授权流程,无法使用资金授权流程,请根据场景谨慎使用

3、如果商家只想使用资金授权, 则category不传;如果传入enable_pay_channels参数,则可以指定余额宝(MONEY_FUND)或者花呗(PCREDIT_PAY),也可不传入该参数,让用户做授权的时候选择使用具体的某个渠道


返回结果样例


{
    "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,可以使用以下三种支付方式之一完成线上预授权:

小程序唤起支付 | H5唤起支付 | APP支付


APP支付结果参考如如下:

成功样例


{
"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未返回,则表示普通资金预授权,会冻结用户资金;

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

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

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


错误码

错误码

错误描述

解决方案

ORDER_ALREADY_CLOSED

授权失败,本笔授权订单已关闭

更换商户授权资金订单号后,重新发起请求

FREEZE_ALREADY_SUCCESS

授权失败,授权订单已经冻结成功,请勿重复授权

确认该笔预授权信息是否为当前付款方的,如果是则认为授权成功,如果不是则更换商家授权资金订单号后,重新发起请求

SYSTEM_ERROR

系统繁忙

请立即调用查询订单API,查询当前订单的状态,并根据订单状态决定下一步的操作

ORDER_ALREADY_FINISH

授权失败,本笔授权订单已经完结,无法再进行资金操作

更换商家授权资金订单号后,重新发起请求

EXIST_FORBIDDEN_WORD

授权失败,订单信息中包含违禁词

修改订单信息后,重新发起请求

ILLEGAL_ARGUMENT

授权失败,预授权冻结参数异常或参数缺失,请顾客刷新付款码后重新收款

检查请求参数,修改后重新发起请求

ACCESS_FORBIDDEN

授权失败,本商户没有权限使用该产品,建议顾客使用其他方式付款

未签约合同或者合同已到期

PAYEE_NOT_EXIST

授权失败,收款方账号不存在

确认该收款方账号是注册过的支付宝账号

PAYER_NOT_EXIST

授权失败,获取顾客账户信息失败

顾客重新登录支付宝后,再发起请求

PAYER_USER_STATUS_LIMIT

授权失败,顾客账户暂时无法支付,建议顾客使用其他方式付款

买家支付宝账户受限,请登录支付宝认证升级,详情咨询95188

PAYEE_USER_STATUS_LIMIT

授权失败,收款方账号异常

卖家支付宝账户受限,请登录支付宝认证升级,详情咨询95188

异步通知

通知类型

描述

fund_auth_freeze

资金预授权冻结成功

通知字段说明

名称

具体类型

是否必须

最大长度

示例值

描述

auth_no

String

必须

64

2014070800002001550000014417

支付宝资金授权订单号

out_order_no

String

必须

64

4977164666634053

商户的资金授权订单号

operation_id

String

必须

64

2014070800032850551

支付宝的资金操作流水号

out_request_no

String

必须

64

8077735255938032

商户资金操作流水号

operation_type

String

必须

16

FREEZE

资金操作类型,支持【FREEZE,UNFREEZE,PAY】

amount

String

必须

11

0.01

本次操作冻结的金额,单位为:元(人民币),精确到小数点后两位

status

String

必须

20

SUCCESS

资金预授权明细的状态
目前支持:  
INIT:初始
SUCCESS: 成功
CLOSED:关闭

gmt_create

String

必须

20

2014-09-15 11:23:04

操作创建时间

gmt_trans

String

必须

20

2014-09-15 11:23:04

操作处理完成时间

payer_logon_id

String

必须

100

test***@alitest.com

付款方支付宝账号登录号

payer_user_id

String

必须

32

2088102000275885

付款方支付宝账号UID

payee_logon_id

String

必须

100

159****5620

收款方支付宝账号登陆号

payee_user_id

String

必须

32

2088102000275795

收款方支付宝账号UID

total_freeze_amount

String

必须

11

0.01

累计冻结金额

total_unfreeze_amount

String

必须

11

0.01

累计解冻金额

total_pay_amount

String

必须

11

0.01

累计支付金额

rest_amount

String

必须

11

0.01

剩余冻结金额

credit_amount

String

必须

11

0.01

本次操作中信用金额,单位为:元(人民币),精确到小数点后两位(信用授权场景返回)

fund_amount

String

必须

11

0.01

本次操作中自有资金金额,单位为:元(人民币),精确到小数点后两位(信用授权场景返回)

total_freeze_credit_amount

String

必须

11

0.01

累计冻结信用金额,单位为:元(人民币),精确到小数点后两位(信用授权场景返回)

total_freeze_fund_amount

String

必须

11

0.01

累计冻结自有资金金额,单位为:元(人民币),精确到小数点后两位 (信用授权场景返回)

total_unfreeze_credit_amount

String

必须

11

0.01

累计解冻信用金额,单位为:元(人民币),精确到小数点后两位(信用授权场景返回)

total_unfreeze_fund_amount

String

必须

11

0.01

累计解冻自有资金金额,单位为:元(人民币),精确到小数点后两位 (信用授权场景返回)

total_pay_credit_amount

String

必须

11

0.01

累计支付信用金额,单位为:元(人民币),精确到小数点后两位 (信用授权场景返回)

total_pay_fund_amount

String

必须

11

0.01

累计支付自有资金金额,单位为:元(人民币),精确到小数点后两位 (信用授权场景返回)

rest_credit_amount

String

必须

11

0.01

剩余冻结信用金额,单位为:元(人民币),精确到小数点后两位 (信用授权场景返回)

rest_fund_amount

String

必须

11

0.01

剩余冻结自有资金金额,单位为:元(人民币),精确到小数点后两位(信用授权场景返回)

pre_auth_type

String

必须

20

CREDIT_AUTH

预授权类型,目前支持 CREDIT_AUTH(信用预授权);
商户可根据该标识来判断该笔预授权的类型,当返回值为"CREDIT_AUTH"表明该笔预授权为信用预授权,没有真实冻结资金;如果未返回,则表示普通资金预授权,会冻结用户资金。

通知样例

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&credit_amount=0.01&fund_amount=0.01&total_freeze_credit_amount=0.01&total_freeze_fund_amount=0.01&total_unfreeze_credit_amount=0.01&total_unfreeze_fund_amount=0.01&total_pay_credit_amount=0.01&total_pay_fund_amount=0.01&rest_credit_amount=0.01&rest_fund_amount=0.01&pre_auth_type=CREDIT_AUTH


onlineServer