快速 接入
支付流程
交互流程图

冻结资金
第一步:商家下资金冻结单
示例代码
bizContent={
"out_order_no":"20221019xxxxxxxx",//商户授权资金订单号,确保唯一
"out_request_no":"20221019xxxxxx",//商户本次资金操作的请求流水号可以和out_order_no相同,确保唯一
"order_title":"资金预授权冻结",
"amount":0.1,//需要冻结的金额,由商户根据自身业务评估金额
"product_code":"PREAUTH_PAY",//产品码固定值
"payee_user_id":"2088xxxxxxxxxxxx",//收款账户的支付宝用户号,如果商户希望用户能够使用花呗,则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
"timeout_express":"30m"//可选,预授权订单相对超时时间
}
request.setBizContent(参考上面bizContent值示例);
request.setNotifyUrl(notify_url);//异步通知地址
AlipayFundAuthOrderAppFreezeResponse response = alipayClient.sdkExecute(request);//注意这里是sdkExecute,可以获取签名参数
if(response.isSuccess()){
System.out.println("调用成功");
string orderStr = response.getBody();
//APP支付唤起冻结,orderStr 入参到 alipay.payV2(orderStr, true )接口
//H5支付唤起冻结,orderStr 入参到 ap.tradePay接口
//小程序唤起冻结 orderStr入参到 my.tradePay接口
} else {
System.out.println("调用失败");
}
重要入参说明
参数名 | 参数说明 |
---|---|
out_order_no | 商家授权资金订单号。 |
out_request_no | 商家本次资金操作的请求流水号。 |
order_title | 订单标题。 |
amount | 需要冻结的金额,由商家根据自身业务评估金额。 |
product_code | 产品码,固定为 PREAUTH_PAY。 |
notify_url | 异步通知地址,异步通知响应详情可查看文中 授权异步通知 章节,当用户授权成功时将触发异步通知返回 auth_no等授权结果信息。若未设置 notify_url 则需调用 alipay.fund.auth.operation.detail.query(资金授权操作查询接口)轮询用户授权结果,当接口返回 order_status = AUTHORIZED 时则用户授权成功。 |
payee_user_id | 可选字段,收款账户的支付宝用户号。 |
payee_logon_id | 可选字段,收款账户的支付宝登录号(email或手机号)。如果商家希望用户能够使用花呗,则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一。 |
enable_pay_channels | 可选字段,可以指定支付渠道,如果不传,默认为签约协议的支付渠道;若需要限制支付渠道,目前仅支持余额宝(MONEY_FUND)、花呗(PCREDIT_PAY)以及芝麻信用(CREDITZHIMA)。冻结用户花呗(PCREDIT_PAY)额度渠道升级中,暂不支持新用户申请接入,请关注后续通知。 |
第二步:调起用户确认页面
APP 调起用户确认页面
Android示例代码
final String orderInfo = orderStr;//orderStr从第一步:生成资金冻结订单,从服务端获取
Runnable payRunnable = new Runnable() {
@Override
public void run () {
PayTask alipay = new PayTask(DemoActivity. this );
Map<String,String> result = alipay.payV2(orderInfo, true );
Message msg = new Message();
msg.what = SDK_PAY_FLAG;
msg.obj = result;
mHandler.sendMessage(msg);
}
};
// 必须异步调用
Thread payThread = new Thread(payRunnable);
payThread.start();
iOS示例代码
重要入参说明
出参获取
private Handler mHandler = new Handler() {
public void handleMessage (Message msg) {
Result result = new Result((String) msg.obj);
Toast.makeText(DemoActivity. this , result.getResult(),
Toast.LENGTH_LONG).show();
};
};
H5 调起用户确认页面
示例代码
<script src= "https://gw.alipayobjects.com/as/g/h5-lib/alipayjsapi/3.1.1/alipayjsapi.inc.min.js"></script>
<button id = "J_btn" class = "btn btn-default">支付</button>
<script>
var btn = document.querySelector('#J_btn');
btn.addEventListener('click', function(){
ap.tradePay({
orderStr : 'timestamp=2016-12-27...'//orderStr从第一步:生成资金冻结订单,从服务端获取
}, function( res ) {
ap.alert(res.resultCode);
});
});
</script>
重要入参说明
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
tradeNO | String | 否 | 交易号,多个交易号请用英文分号 ; 分隔。 |
partnerID | String | 否 | 商户 id。 |
bizType | String | 否 | 交易类型,默认为 trade 。 |
bizSubType | String | 否 | 交易子类型。 |
bizContext | String | 否 | 支付额外的参数,格式为 JSON 字符串。 |
orderStr | String | 否 | 完整的支付参数拼接成的字符串,从服务端获取。 |
参数 | 类型 | 描述 |
---|---|---|
resultCode | String | 支付结果状态码,详情可查看下表。 |
resultCode | 描述 |
---|---|
9000 | 订单支付成功。 |
8000 | 正在处理中。 |
4000 | 订单支付失败。 |
6001 | 用户中途取消。 |
6002 | 网络连接出错。 |
99 | 用户点击忘记密码导致快捷界面退出(only iOS)。 |
小程序调起用户确认页面
示例代码
my.tradePay({
orderStr: 'orderStr', //orderStr从第一步:生成资金冻结订单,从服务端获取
success: (res) => {
my.alert({
content: JSON.stringify(res),
});
},
fail: (res) => {
my.alert({
content: JSON.stringify(res),
});
}
});
注意事项
授权异步通知说明
用户授权成功异步通知样例
https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_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&trans_currency=USD
重要参数说明
参数名 | 参数说明 |
---|---|
auth_no | 支付宝资金授权订单号 |
out_order_no | 商家的资金授权订单号 |
operation_id | 支付宝的资金操作流水号 |
out_request_no | 商家资金操作流水号 |
验签方法
异步通知接收代码规范
示例代码
冻结资金转支付
示例代码
bizContent={
"out_trade_no":"20221019xxxx",//预授权转支付商户订单号,为新的商家交易流水号
"total_amount":"0.09",//结算支付金额
"subject":"冻结转支付",//订单标题
"product_code":"PREAUTH_PAY",//固定值PREAUTH_PAY
"auth_no":"202210201000************3940",//支付宝资金授权订单号,第二步唤起得到可在授权异步通知或查询里面查看
"auth_confirm_mode":"NOT_COMPLETE" //预授权确认模式,非必填
}
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();
request.setBizContent(参考上面bizContent值示例);
request.setNotifyUrl(notify_url);//异步通知地址
AlipayTradePayResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
System.out.println(response.getBody());
} else {
System.out.println("调用失败");
}
重要入参说明
参数名 | 参数说明 |
---|---|
notify_url | 非必填,支付成功异步接收地址 |
auth_confirm_mode | 非必填,预授权确认模式当 auth_confirm_mode = COMPLETE 时无需调用解冻接口,支付宝端在扣款成功后会自动解冻剩余金额,同时该笔授权订单完成。当 auth_confirm_mode = NOT_COMPLETE 时,商家收到支付成功通知后需要自行调用 alipay.fund.auth.order.unfreeze(资金授权解冻接口)将余额进行解冻。如果需要从一笔授权中完成多笔订单支付,保持 auth_no 不变,不同订单根据 outTradeNo 进行标识,此时 auth_confirm_mode 不传或者传入 NOT_COMPLETE;进行到最后一笔转支付时,auth_confirm_mode 传入 COMPLETE 由支付宝完成剩余金额自动解冻,或者商家自行调用解冻接口将剩余金额解冻。 |
**
重要出参说明
支付异步通知说明
资金授权转支付通知样例
gmt_create=2022-10-27 17:41:57&charset=utf-8&seller_email=$$$&subject=资金转支付&sign=$$$&buyer_id=2088********2180&invoice_amount=0.01¬ify_id=202210270122****************555922&fund_bill_list=[{"amount":"0.01","fundChannel":"ALIPAYACCOUNT"}]¬ify_type=trade_status_sync&trade_status=TRADE_SUCCESS&receipt_amount=0.01&app_id=2014********3222&buyer_pay_amount=0.01&sign_type=RSA2&seller_id=2088********0335&gmt_payment=2022-10-27 17:41:57¬ify_time=2022-10-27 17:41:58&version=1.0&out_trade_no=202210278880110111pay&total_amount=0.01&trade_no=20221027****************4504&auth_app_id=2014********3222&buyer_logon_id=156****8305&point_amount=0.00
重要参数说明
参数名 | 参数说明 |
---|---|
out_trade_no | 商家外部交易号 |
trade_no | 支付宝交易号 |
trade_status | 交易状态 |
receipt_amount | 实收金额 |
解冻资金
示例代码
bizContent={
"auth_no":"202210201000************3940",//支付宝资金授权订单号,第二步唤起得到可在授权异步通知或查询里面查看
"out_request_no":"20221020134646013unfree03",//同一商家每次不同的资金操作请求,商家请求流水号不能重复,且与冻结流水号不同
"amount":0.01,// 本次操作解冻的金额,单位为:元(人民币),精确到小数点后两位
"remark":"本次冻结0.01"// 商家对本次解冻操作的附言描述,长度不超过100个字母或50个汉字
}
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();
$request->setBizContent(参考上面bizContent值示例);
AlipayFundAuthOrderUnfreezeResponse response = alipayClient.execute(request);
System.out.println(response.getBody());
资金授权解冻通知示例
notify_url?gmt_create=2022-10-20 11%3A45%3A09&charset=utf-8&rest_amount=0.00&amount=0.01¬ify_time=2022-10-20 11%3A45%3A10&operation_type=UNFREEZE&sign=$$$&out_order_no=20221020v1223102110&version=1.0&auth_no=202210201000************3940¬ify_id=202210200022211***********5729313¬ify_type=fund_auth_unfreeze&total_pay_amount=0.00&total_freeze_amount=0.01&gmt_trans=2022-10-20 11%3A45%3A09&auth_app_id=201410******3222&operation_id=2022102086******1805&total_unfreeze_amount=0.01&out_request_no=20221020134646013unfree03&payer_user_id=2088********2180&app_id=201410******3222&sign_type=RSA2&status=SUCCESS&payer_logon_id=156****8305
重要参数说明
参数 | 参数说明 |
---|---|
operation_type | 资金操作类型。UNFREEZE:解冻。 |
auth_no | 支付宝资金授权订单号。 |
out_request_no | 商家资金操作流水号。 |
查询资金冻结操作
示例代码
bizContent={
"auth_no":"202210201000************3940",// 支付宝预授权订单号,在授权冻结成功时返回参数中获得
"out_request_no":"202210********03",//商家的授权资金订单号,与支付宝的授权资金订单号不能同时为空
"operation_id":"201712********823902", //非必填,支付宝的授权资金操作流水号,冻结成功同步返回
"out_request_no":"request*****00003";//商家的授权资金操作流水号,与auth_no支付宝的授权资金操作流水号不能同时为空,该值为冻结或解冻是的outRequestNo
}
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();
request.setBizContent(参考上面bizContent值示例);
AlipayFundAuthOperationDetailQueryResponse response = alipayClient.execute(request);
System.out.println(response.getBody());
响应示例
{
"alipay_fund_auth_operation_detail_query_response":{
"code":"10000",
"msg":"Success",
"amount":"0.01",
"auth_no":"202210201000************3940",
"extra_param":"{}",
"gmt_create":"2022-10-20 11:45:09",
"gmt_trans":"2022-10-20 11:45:09",
"operation_id":"20221020860169091805",
"operation_type":"UNFREEZE",
"order_status":"CLOSED",
"order_title":"解冻",
"out_order_no":"20221020v1223102110",
"out_request_no":"20221020134646013unfree03",
"payer_logon_id":"156****8305",
"payer_user_id":"2088********2180",
"remark":"\u89e3\u51bb\u8d44\u91d1",
"rest_amount":"0.00",
"status":"SUCCESS",
"total_freeze_amount":"0.01",
"total_pay_amount":"0.00"
},
"sign":"azKv6PByfUQpMD03mdjnFuDYXwipYCvz75fyFOH341mNMzDqIhDx9rgreyPQMaIO1BFkhT6h+H2Sk6\/3R7qSSL3+lKpzHmwCJHTxE1uSkVuBfoR3D8YRmM0Zt1Nn2kujTETMIV6TVT9\/3qQ4ebLFTKJ83F9AUU6eZXLJ9Od6jPrxo3\/pYeKZ2fst2Ld8GrMCIVpiulb2o+LqH2ZyJN39KRm9MPJvN2WgkWA1NPNzwHiadT3LrBB7iWoyvT48ToIgH0YNUFjG00v\/djue3jdac70\/fdfePJ01rH5uGp\/UZbvRZp3Ing27X04rH+79mnxidIXQOORJ\/59ssF+oZSgtEQ=="
}
重要出参说明
撤销资金冻结
示例代码
查询交易
示例代码
重要入参说明
重要出参说明
退款流程
示例代码
对账流程
系统流程

1.
2.
示例代码
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×tamp=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×tamp=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\"}"
}
}
重要出参说明
参数名 | 参数说明 |
---|---|
billDownloadUrl | 对账单下载地址,下载地址有效时间为 30 秒,请尽快下载。 |
接口报错处理
修改于 2023-11-20 07:50:56