接口说明
该接口是 签名数据准备接口,用于生成可信签名字符串(orderstr)。可信签名串中包含业务参数及商户身份信息,可防止数据被篡改,一般用于打开支付宝客户端。请在服务端执行支付宝sdk中sdkexecute方法,读取响应中的body()结果。具体使用方法请参考
预授权支付
创建支付宝授权订单并完成资金冻结。适用于线上场景完成资金授权, 例如从商户app端拉起支付宝收银台完成冻结。
公共请求参数
业务请求参数
out_order_no必选string(64)
【描述】商户授权资金订单号。
商家自定义需保证在商户端不重复。仅支持字母、数字、下划线。
商家自定义需保证在商户端不重复。仅支持字母、数字、下划线。
【示例值】8077735255938023
out_request_no必选string(64)
【描述】商户本次资金操作的请求流水号,用于标示请求流水的唯一性。
可与out_order_no相同,仅支持字母、数字、下划线。
可与out_order_no相同,仅支持字母、数字、下划线。
【示例值】8077735255938032
order_title必选string(100)
【描述】订单标题。
业务订单的简单描述,如商品名称等
业务订单的简单描述,如商品名称等
【示例值】xx租车押金
amount必选price(11)
【描述】需要冻结的金额,单位为:元(人民币),精确到小数点后两位。
取值范围:[0.01,100000000.00]
取值范围:[0.01,100000000.00]
【示例值】0.01
product_code必选string(32)
【描述】销售产品码。
预授权支付产品固定为 preauth_pay
预授权支付产品固定为 preauth_pay
【示例值】preauth_pay
deposit_product_mode特殊可选string(32)
【描述】免押受理台模式,使用免押产品必传该字段。根据免押不同业务模式将开通受理台区分三种模式,商家可根据调用预授权冻结接口传入的参数决定该笔免押订单选择哪种受理台模式。不同受理台模式需要传入不同参数,其中:postpay 表示后付金额已知,postpay_uncertain 表示后付金额未知,deposit_only 表示纯免押。 具体规则参考文档:
【枚举值】
后付金额已知: postpay
后付金额未知: postpay_uncertain
纯免押: deposit_only
【必选条件】使用免押产品必传该字段
【示例值】postpay
post_payments特殊可选postpayment[]
【描述】后付费项目,有付费项目时需要传入该字段。不同受理台模式需要传入不同参数,后付费项目名称和计费说明需要通过校验规则,同时计费说明将展示在开通受理台上。当受理台模式(deposit_product_mode)传入postpay 时,后付费项目名称(name)、金额(amount)必传,计费说明(description)选传;当传入 postpay_uncertain 时,后付费项目名称(name)、计费说明(description)必传,金额(amount)不传。 具体规则参考文档:
【必选条件】有付费项目时需要传入该字段
name特殊可选string(32)
【描述】后付费项目名称
【示例值】租金
amount特殊可选string(11)
【描述】后付费金额,单位为:元(人民币),精确到小数点后两位。
【示例值】0.01
description可选string(64)
【描述】计费说明
【示例值】2元/小时,99元封顶
payee_user_id可选string(32)
【描述】收款账户的支付宝用户号。
以2088开头的16位纯数字,如果传入则会校验该账号是否具备当前商户收款权限,如果商户希望用户能够使用花呗,则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
以2088开头的16位纯数字,如果传入则会校验该账号是否具备当前商户收款权限,如果商户希望用户能够使用花呗,则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
【示例值】2088102000275795
payee_logon_id可选string(100)
【描述】收款账户的支付宝登录号(email或手机号)。
如果传入则会校验该登录号对应的账号是否具备当前商户收款权限,如果商户希望用户能够使用花呗,则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
如果传入则会校验该登录号对应的账号是否具备当前商户收款权限,如果商户希望用户能够使用花呗,则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
【示例值】159****5620
timeout_express可选string(5)
【描述】预授权订单相对超时时间。从商户客户端请求时间开始计算。
预授权订单允许的最晚授权时间,逾期将关闭该笔订单。取值范围:1m~15d。m-分钟,h-小时,d-天。 该参数数值不接受小数点, 如 1.5h,可转换为90m。
默认为15m。
预授权订单允许的最晚授权时间,逾期将关闭该笔订单。取值范围:1m~15d。m-分钟,h-小时,d-天。 该参数数值不接受小数点, 如 1.5h,可转换为90m。
默认为15m。
【示例值】2d
enable_pay_channels可选string(128)
【描述】无特殊需要请勿传入;商户可用该参数指定支付渠道。
传入后用户仅能使用列表中的渠道进行支付,目前支持三种渠道,余额宝(money_fund)、花呗(pcredit_pay)以及芝麻信用(creditzhima)。与禁用支付渠道不可同时传入
传入后用户仅能使用列表中的渠道进行支付,目前支持三种渠道,余额宝(money_fund)、花呗(pcredit_pay)以及芝麻信用(creditzhima)。与禁用支付渠道不可同时传入
【示例值】[{"paychanneltype":"pcredit_pay"},{"paychanneltype":"money_fund"}]
disable_pay_channels可选string(128)
【描述】无特殊需要请勿传入;商户可用该参数禁用支付渠道。
传入后用户不可使用列表中的渠道进行支付,目前支持两种禁用渠道:信用卡快捷(optimized_moto)、信用卡卡通(bigamount_credit_cartoon)。与可用支付渠道不能同时传入
传入后用户不可使用列表中的渠道进行支付,目前支持两种禁用渠道:信用卡快捷(optimized_moto)、信用卡卡通(bigamount_credit_cartoon)。与可用支付渠道不能同时传入
【示例值】[{"paychanneltype":"optimized_moto"},{"paychanneltype":"bigamount_credit_cartoon"}]
identity_params可选string(300)
【描述】无特殊需要请勿传入;买家实名信息。
传入后支付宝会比对买家在支付宝端的实名信息。包含两个可选key:
1.identity_hash,买家姓名拼接身份证号后,使用sha256摘要方式与utf8编码后的hash值,返回的十六进制字符串,例如 “张三4566498798498498498498”对应的identity_hash应为“acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6”
2.alipay_user_id,买家uid
传入后支付宝会比对买家在支付宝端的实名信息。包含两个可选key:
1.identity_hash,买家姓名拼接身份证号后,使用sha256摘要方式与utf8编码后的hash值,返回的十六进制字符串,例如 “张三4566498798498498498498”对应的identity_hash应为“acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6”
2.alipay_user_id,买家uid
【示例值】{"identity_hash":"acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6"}
extra_param可选string(300)
【描述】业务扩展参数,用于特定业务信息的传递,json格式。
1、category,信用类目,信用预授权场景必传,具体类目信息见;
2、serviceid,信用服务id:信用预授权场景必传。需要商家在 创建信用服务获取,详情可查看 。在创建过程中如果有其它疑问,可以咨询芝麻客服小二(0571-88158055 转 2);
3、creditextinfo,信用参数,可选,如有需要请与芝麻约定后传入,信用服务说明见
1、category,信用类目,信用预授权场景必传,具体类目信息见;
2、serviceid,信用服务id:信用预授权场景必传。需要商家在 创建信用服务获取,详情可查看 。在创建过程中如果有其它疑问,可以咨询芝麻客服小二(0571-88158055 转 2);
3、creditextinfo,信用参数,可选,如有需要请与芝麻约定后传入,信用服务说明见
【示例值】{"category":"charge_pile_car","serviceid":"2020042800000000000001450466"}
business_params可选string(1024)
【描述】业务参数,如风控参数outriskinfo等。
【示例值】{"outriskinfo":"{\"mccreatetradetime\":\"2022-03-11 12:46:09\",\"extraaccountcertnolastsix\":\"000011\",\"mobileoperatingplatform\":\"ios\",\"sysversion\":\"15.4.2\",\"mccreatetradeip\":\"11.110.111.43\"}"}
常见请求示例
默认示例
package com.java.sdk.demo;
import com.alipay.api.alipayapiexception;
import com.alipay.api.alipayclient;
import com.alipay.api.defaultalipayclient;
import com.alipay.api.alipayconfig;
import com.alipay.api.response.alipayfundauthorderappfreezeresponse;
import com.alipay.api.request.alipayfundauthorderappfreezerequest;
import com.alipay.api.domain.postpayment;
import com.alipay.api.domain.alipayfundauthorderappfreezemodel;
import com.alipay.api.fileitem;
import java.util.base64;
import java.util.arraylist;
import java.util.list;
public class alipayfundauthorderappfreeze {
public static void main(string[] args) throws alipayapiexception {
// 初始化sdk
alipayclient alipayclient = new defaultalipayclient(getalipayconfig());
// 构造请求参数以调用接口
alipayfundauthorderappfreezerequest request = new alipayfundauthorderappfreezerequest();
alipayfundauthorderappfreezemodel model = new alipayfundauthorderappfreezemodel();
// 设置后付费项目
list<postpayment> postpayments = new arraylist<postpayment>();
postpayment postpayments0 = new postpayment();
postpayments0.setamount("0.01");
postpayments0.setname("租金");
postpayments0.setdescription("2元/小时,99元封顶");
postpayments.add(postpayments0);
model.setpostpayments(postpayments);
// 设置订单标题
model.setordertitle("xx租车押金");
// 设置需要冻结的金额
model.setamount("0.01");
// 设置收款账户的支付宝用户号
model.setpayeeuserid("2088102000275795");
// 设置商户授权资金订单号
model.setoutorderno("8077735255938023");
// 设置销售产品码
model.setproductcode("preauth_pay");
// 设置收款账户的支付宝登录号(email或手机号)
model.setpayeelogonid("159****5620");
// 设置无特殊需要请勿传入
model.setenablepaychannels("[{\"paychanneltype\":\"pcredit_pay\"},{\"paychanneltype\":\"money_fund\"}]");
// 设置免押受理台模式
model.setdepositproductmode("postpay");
// 设置无特殊需要请勿传入
model.setidentityparams("{\"identity_hash\":\"acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6\"}");
// 设置业务参数
model.setbusinessparams("{\"outriskinfo\":\"{\"mccreatetradetime\":\"2022-03-11 12:46:09\",\"extraaccountcertnolastsix\":\"000011\",\"mobileoperatingplatform\":\"ios\",\"sysversion\":\"15.4.2\",\"mccreatetradeip\":\"11.110.111.43\"}\"}");
// 设置预授权订单相对超时时间
model.settimeoutexpress("2d");
// 设置无特殊需要请勿传入
model.setdisablepaychannels("[{\"paychanneltype\":\"optimized_moto\"},{\"paychanneltype\":\"bigamount_credit_cartoon\"}]");
// 设置商户本次资金操作的请求流水号
model.setoutrequestno("8077735255938032");
// 设置业务扩展参数
model.setextraparam("{\"category\":\"charge_pile_car\",\"serviceid\":\"2020042800000000000001450466\"}");
request.setbizmodel(model);
// 第三方代调用模式下请设置app_auth_token
// request.putothertextparam("app_auth_token", "<-- 请填写应用授权令牌 -->");
alipayfundauthorderappfreezeresponse response = alipayclient.sdkexecute(request);
string orderstr = response.getbody();
system.out.println(orderstr);
if (response.issuccess()) {
system.out.println("调用成功");
} else {
system.out.println("调用失败");
// sdk版本是"4.38.0.all"及以上,可以参考下面的示例获取诊断链接
// string diagnosisurl = diagnosisutils.getdiagnosis;
// system.out.println(diagnosisurl);
}
}
private static alipayconfig getalipayconfig() {
string privatekey = "<-- 请填写您的应用私钥,例如:miievqibadanb ... ... -->";
string alipaypublickey = "<-- 请填写您的支付宝公钥,例如:miibijanbg... -->";
alipayconfig alipayconfig = new alipayconfig();
alipayconfig.setserverurl("https://openapi.alipay.com/gateway.do");
alipayconfig.setappid("<-- 请填写您的appid,例如:2019091767145019 -->");
alipayconfig.setprivatekey(privatekey);
alipayconfig.setformat("json");
alipayconfig.setalipaypublickey(alipaypublickey);
alipayconfig.setcharset("utf-8");
alipayconfig.setsigntype("rsa2");
return alipayconfig;
}
}
说明:本示例仅供参考。
公共响应参数
无公共响应参数
业务响应参数
orderstr|签名字符串必选string(16384)
【描述】获取签名后的业务数据,在my.tradepay接口中传入此签名串即可发起支付具体使用方法请参考
【示例值】请参考响应示例
响应示例
正常示例
app_id=2017060101317939&biz_content={"post_payments%22:%22%22,"order_title%22:"xx租车押�%87%91%22,"amount%22:%220.01%22,"payee_user_id%22:%222088102000275795%22,"out_order_no%22:%228077735255938023%22,"product_code%22:"preauth_pay%22,"payee_logon_id%22:%22159****5620%22,"enable_pay_channels%22:%22[{\"paychanneltype\%22:\"pcredit_pay\%22},{\"paychanneltype\%22:\"money_fund\%22}]%22,"deposit_product_mode%22:"postpay%22,"identity_params%22:%22{\"identity_hash\%22:\"acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6\%22}%22,"business_params%22:%22{\"outriskinfo\%22:\%22{\\\"mccreatetradetime\\\%22:\\\%222022-03-11 12:46:09\\\%22,\\\"extraaccountcertnolastsix\\\%22:\\\%22000011\\\%22,\\\"mobileoperatingplatform\\\%22:\\\"ios\\\%22,\\\"sysversion\\\%22:\\\%2215.4.2\\\%22,\\\"mccreatetradeip\\\%22:\\\%2211.110.111.43\\\%22}\%22}%22,"timeout_express%22:"2d%22,"disable_pay_channels%22:%22[{\"paychanneltype\%22:\"optimized_moto\%22},{\"paychanneltype\%22:\"bigamount_credit_cartoon\%22}]%22,"out_request_no%22:%228077735255938032%22,"extra_param%22:%22{\"category\%22:\"charge_pile_car\%22,\"serviceid\%22:\%222020042800000000000001450466\%22}%22}&charset=utf-8&format=json&method=alipay.fund.auth.order.app.freeze&sign=eritjkeijkjhkkkkkkkhjereeeeeeeeeee&sign_type=rsa2×tamp=2014-07-24 03:07:50&version=1.0
说明:本示例仅供参考。
公共错误码
业务错误码
错误码 | 错误描述 | 凯发app官方网站的解决方案 |
---|---|---|
system_error | 系统繁忙 | 请立即调用查询订单api,查询当前订单的状态,并根据订单状态决定下一步的操作 |
access_forbidden | 授权失败,本商户没有权限使用该产品,建议顾客使用其他方式付款 | 未签约合同或者合同已到期 |
currency_verification_fail | 币种校验失败 | 确认标价币种、结算币种正确后重新发起请求 |
exist_forbidden_word | 授权失败,订单信息中包含违禁词 | 修改订单信息后,重新发起请求 |
forex_id_verification_fail | 用户身份校验失败 | 请确认用户为大陆身份证认证用户 |
freeze_already_success | 授权失败,授权订单已经冻结成功,请勿重复授权 | 确认该笔预授权信息是否为当前付款方的,如果是则认为授权成功,如果不是则更换商家授权资金订单号后,重新发起请求 |
illegal_argument | 授权失败,预授权冻结参数异常或参数缺失,请顾客刷新付款码后重新收款 | 检查请求参数,修改后重新发起请求 |
merchant_status_error | 商户状态错误 | 商户状态异常,请联系支付宝核实 |
order_already_closed | 授权失败,本笔授权订单已关闭 | 更换商户授权资金订单号后,重新发起请求 |
order_already_finish | 授权失败,本笔授权订单已经完结,无法再进行资金操作 | 更换商家授权资金订单号后,重新发起请求 |
payee_not_exist | 授权失败,收款方账号不存在 | 确认该收款方账号是注册过的支付宝账号 |
payee_user_status_limit | 授权失败,收款方账号异常 | 卖家支付宝账户受限,请登录支付宝认证升级,详情咨询 4007585858 |
payer_not_exist | 授权失败,获取顾客账户信息失败 | 顾客重新登录支付宝后,再发起请求 |
payer_user_status_limit | 授权失败,顾客账户暂时无法支付,建议顾客使用其他方式付款 | 买家支付宝账户受限,请登录支付宝认证升级,详情咨询 4007585858 |
product_amount_limit_error | 购汇额度校验失败 | 请与客服确认用户购汇额度信息 |
restricted_merchant_industry | 商户所属行业mcc单笔订单金额限制 | 请商户与支付宝客服确认行业mcc订单金额限制信息 |
secondary_merchant_status_error | 商户状态异常 | 请商户与支付宝客服联系确认 |
sub_merchant_level_error | 间联商户等级校验错误 | 间联商户等级校验错误,请提高间联商户的等级 |
sub_merchant_no_permission | 间联商户无权使用该产品 | 商户暂时不符合产品的使用场景 |
sub_merchant_org_id_error | 间联模式下,传入的二级商户的机构id为空或错误 | 间联模式下,传入正确的机构id |
user_account_validate_fail | 用户账号校验失败 | 用户账号信息校验失败,请确认当前用户与支付宝用户是否匹配。 |
user_identity_info_validate_fail | 用户实名信息校验失败 | 用户实名信息校验失败,请确认当前用户与支付宝用户是否匹配。 |
触发通知类型
通知类型 | 描述 | 默认开启 |
---|---|---|
fund_auth_freeze | 资金预授权冻结成功 | 1 |
fund_auth_freeze.closed | 资金预授权订单关闭 | 0 |
fund_auth_freeze.init | 资金预授权订单创建 | 0 |
触发通知示例
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&payer_open_id=03914imefxss9k-tsvhy-iisrllofthfgdvo-hu30xtkpg9&merchant_app_id=2016092901250233&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&credit_merchant_ext={"1003190":"true"}&enterprise_pay_info={"biz_info":"{\"enterprisepayamount\":\"0.01\"}"}