通用场景
收银员使用扫码设备读取用户支付宝钱包“付款码”后，将条码信息和订单信息通过本接口上送至支付宝发起资金冻结。
公共请求参数
业务请求参数
auth_code必选string(1000)
【描述】用户付款码。
1.条码场景：25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准；
2.刷脸场景：
1）fp开头的35位字符串；
2）300-700字符的随机字符串；
注：刷脸场景考虑到未来可能拓展更多格式，建议外围不必做规则拦截，由支付宝统一做有效性校验
【示例值】付款码场景：28763443825664394，
刷脸场景1)示例：fp1394da8bfc3e299a2128b8bda17456h84
auth_code_type必选string(32)
【描述】付款码类型。
1.条码场景：bar_code
2.刷脸场景：security_code
【枚举值】
条码场景: bar_code
刷脸场景: security_code
【示例值】bar_code
out_order_no必选string(64)
【描述】商户授权资金订单号。
商家自定义需保证在商户端不重复。仅支持字母、数字、下划线。
【示例值】8077735255938023
out_request_no必选string(64)
【描述】商户本次资金操作的请求流水号，用于标示请求流水的唯一性。
可与out_order_no相同，仅支持字母、数字、下划线。
【示例值】8077735255938032
order_title必选string(100)
【描述】订单标题。
业务订单的简单描述，如商品名称等
【示例值】xx租车押金
product_code必选string(32)
【描述】销售产品码。
当面资金预授权固定为 pre_auth
【示例值】pre_auth
amount必选price(11)
【描述】需要冻结的金额，单位为：元（人民币），精确到小数点后两位。
取值范围：[0.01,100000000.00]
【示例值】0.01
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)两者必须传入其一
【示例值】2088102000275795
payee_logon_id可选string(100)
【描述】收款账户的支付宝登录号（email或手机号）。
如果传入则会校验该登录号对应的账号是否具备当前商户收款权限，如果商户希望用户能够使用花呗，则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
【示例值】159****5620
timeout_express可选string(5)
【描述】预授权订单相对超时时间，从商户请求时间开始计算。
预授权订单允许的最晚授权时间，逾期将关闭该笔订单。取值范围：1m～15d。m-分钟，h-小时，d-天。 该参数数值不接受小数点， 如 1.5h，可转换为90m。
默认为15m。
【示例值】2d
scene_code可选string(10)
【描述】场景码。
刷脸场景下传入hotel，其他情况下无需传入
【示例值】hotel
enable_pay_channels可选string(128)
【描述】无特殊需要请勿传入；商户可用该参数指定支付渠道。
传入后用户仅能使用列表中的渠道进行支付，目前支持三种渠道，余额宝（money_fund）、花呗（pcredit_pay）以及芝麻信用（creditzhima）。与禁用支付渠道不可同时传入
【示例值】[{"paychanneltype":"pcredit_pay"},{"paychanneltype":"money_fund"}]
disable_pay_channels可选string(128)
【描述】无特殊需要请勿传入；商户可用该参数禁用支付渠道。
传入后用户不可使用列表中的渠道进行支付，目前支持两种禁用渠道：信用卡快捷（optimized_moto）、信用卡卡通（bigamount_credit_cartoon）。与可用支付渠道不能同时传入
【示例值】[{"paychanneltype":"optimized_moto"},{"paychanneltype":"bigamount_credit_cartoon"}]
extra_param可选string(300)
【描述】业务扩展参数，用于特定业务信息的传递，json格式。
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\"}"}
常见请求示例
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.fund.auth.order.freeze&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'app_auth_token=${app_auth_token}' \
-f 'biz_content={
"post_payments":[
{
"amount":"0.01",
"name":"租金",
"description":"2元/小时，99元封顶"
}
],
"order_title":"xx租车押金",
"amount":"0.01",
"payee_user_id":"2088102000275795",
"out_order_no":"8077735255938023",
"product_code":"pre_auth",
"payee_logon_id":"159****5620",
"auth_code":"付款码场景：28763443825664394，\n刷脸场景1)示例：fp1394da8bfc3e299a2128b8bda17456h84",
"enable_pay_channels":"[{\"paychanneltype\":\"pcredit_pay\"},{\"paychanneltype\":\"money_fund\"}]",
"deposit_product_mode":"postpay",
"auth_code_type":"bar_code",
"business_params":"{\"outriskinfo\":\"{\\\"mccreatetradetime\\\":\\\"2022-03-11 12:46:09\\\",\\\"extraaccountcertnolastsix\\\":\\\"000011\\\",\\\"mobileoperatingplatform\\\":\\\"ios\\\",\\\"sysversion\\\":\\\"15.4.2\\\",\\\"mccreatetradeip\\\":\\\"11.110.111.43\\\"}\"}",
"timeout_express":"2d",
"disable_pay_channels":"[{\"paychanneltype\":\"optimized_moto\"},{\"paychanneltype\":\"bigamount_credit_cartoon\"}]",
"scene_code":"hotel",
"out_request_no":"8077735255938032",
"extra_param":"{\"category\":\"charge_pile_car\",\"serviceid\":\"2020042800000000000001450466\"}"
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
auth_no必选string(64)
【描述】支付宝的资金授权订单号
【示例值】2014070800002001550000014417
out_order_no必选string(64)
【描述】商户的授权资金订单号
【示例值】4977164666634053
operation_id必选string(64)
【描述】支付宝的资金操作流水号
【示例值】2014070800032850551
out_request_no必选string(64)
【描述】商户本次资金操作的请求流水号
【示例值】2014070700166653
amount必选price(11)
【描述】本次操作冻结的金额，单位为：元（人民币），精确到小数点后两位
【示例值】0.01
status必选string(20)
【描述】资金预授权明细的状态
目前支持：
init：初始
success: 成功
closed：关闭
【示例值】success
payer_logon_id必选string(100)
【描述】付款方支付宝账号（email或手机号）
【示例值】test***@alitest.com
以下参数 二选一
payer_user_idstring(32)
【描述】付款方支付宝用户号
新商户建议使用payer_open_id替代该字段。对于新商户，payer_user_id字段未来计划逐步回收，存量商户可继续使用。如使用payer_open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088102000275885
payer_open_idstring(128)
【描述】支付宝openid，用户（userid）在应用（appid）下的唯一用户标识。 详情可查看 openid简介
【示例值】03914imefxss9k-tsvhy-iisrllofthfgdvo-hu30xtkpg9
gmt_trans特殊可选date(20)
【描述】资金授权成功时间
格式：yyyy-mm-dd hh:mm:ss
【示例值】2014-09-15 11:23:04
pre_auth_type特殊可选string(20)
【描述】预授权类型，目前支持 credit_auth(信用预授权);
商户可根据该标识来判断该笔预授权的类型，当返回值为"credit_auth"表明该笔预授权为信用预授权，没有真实冻结资金；当返回值为空或者不为"credit_auth"则表明该笔预授权为普通资金预授权，会冻结用户资金。
【枚举值】
信用预授权，没有真实冻结资金: credit_auth
【示例值】credit_auth
trans_currency特殊可选string(8)
【描述】标价币种, amount 对应的币种单位。支持澳元：aud, 新西兰元：nzd, 台币：twd, 美元：usd, 欧元：eur, 英镑：gbp
【示例值】usd
credit_amount特殊可选price(11)
【描述】本次冻结操作中信用冻结金额，单位为：元（人民币），精确到小数点后两位
【示例值】0.01
fund_amount特殊可选price(11)
【描述】本次冻结操作中自有资金冻结金额，单位为：元（人民币），精确到小数点后两位
【示例值】0.01
响应示例
正常示例
异常示例
{
"alipay_fund_auth_order_freeze_response": {
"code": "10000",
"msg": "success",
"auth_no": "2014070800002001550000014417",
"out_order_no": "4977164666634053",
"operation_id": "2014070800032850551",
"out_request_no": "2014070700166653",
"amount": "0.01",
"payer_user_id": "2088102000275885",
"payer_open_id": "03914imefxss9k-tsvhy-iisrllofthfgdvo-hu30xtkpg9",
"status": "success",
"payer_logon_id": "test***@alitest.com",
"gmt_trans": "2014-09-15 11:23:04",
"pre_auth_type": "credit_auth",
"trans_currency": "usd",
"credit_amount": "0.01",
"fund_amount": "0.01"
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| access_forbidden | 授权失败，本商户没有权限使用该产品，建议顾客使用其他方式付款 | 未签约条码支付或者合同已到期 |
| client_version_not_match | 授权失败，顾客手机支付宝客户端版本过低，请更新到最新版本 | 请用户更新到最新版本的手机支付宝客户端 |
| currency_verification_fail | 币种校验失败 | 确认标价币种、结算币种正确后重新发起请求 |
| error_balance_payment_disable | 授权失败，顾客余额支付功能开关关闭，请用户打开余额支付功能开关 | 用户打开余额支付开关后，再重新进行支付 |
| exist_forbidden_word | 授权失败，订单信息中包含违禁词 | 修改订单信息后，重新发起请求 |
| forbidden_merchant_industry | 订单所属行业mcc被拦截 | 请与支付宝客服联系 |
| forex_id_verification_fail | 用户身份校验失败 | 请确认用户为大陆身份证认证用户 |
| freeze_already_success | 授权失败，授权订单已经冻结成功，请勿重复授权 | 确认该笔预授权信息是否为当前付款方的，如果是则认为授权成功，如果不是则更换商家授权资金订单号后，重新发起请求 |
| illegal_argument | 授权失败，预授权冻结参数异常或参数缺失，请顾客刷新付款码后重新收款 | 检查请求参数，修改后重新发起请求 |
| illegal_payee_user_id | 收款方账号不是卖家可用的账号 | 收款方账号请使用卖家账号或卖家收款账号 |
| merchant_status_error | 商户状态错误 | 商户状态异常，请联系支付宝核实 |
| money_not_enough | 授权失败，顾客余额不足，建议顾客充值完成后再进行付款 | 买家绑定新的银行卡或者支付宝余额有钱后再发起支付 |
| no_payment_instruments_available | 授权失败，用户没用可用的支付工具 | 请用户更换其它付款方式 |
| order_already_closed | 授权失败，本笔授权订单已关闭 | 更换商户授权资金订单号后，重新发起请求 |
| order_already_finish | 授权失败，本笔授权订单已经完结，无法再进行资金操作 | 更换商家授权资金订单号后，重新发起请求 |
| payee_not_exist | 授权失败，收款方账号不存在 | 确认该收款方账号是注册过的支付宝账号 |
| payee_user_status_limit | 授权失败，收款方账号异常 | 卖家支付宝账户受限，请登录支付宝认证升级，详情咨询4007585858 |
| payer_not_exist | 授权失败，获取顾客账户信息失败，请顾客刷新付款码后重新收款 | 用户刷新条码后，重新扫码发起请求 |
| payer_payee_equal | 授权失败，收付款方信息不能相同 | 请商家基于业务诉求更换付款方或收款方信息 |
| payer_user_status_limit | 授权失败，顾客账户暂时无法支付，建议顾客使用其他方式付款 | 买家支付宝账户受限，请登录支付宝认证升级，详情咨询4007585858 |
| payment_auth_code_invalid | 授权失败，获取顾客账户信息失败，请顾客刷新付款码后重新收款，如再次授权失败 | 用户刷新条码后，重新扫码发起请求 |
| product_amount_limit_error | 购汇额度校验失败 | 请与客服确认用户购汇额度信息 |
| pull_mobile_cashier_fail | 授权失败，顾客手机唤起收银台失败，请顾客检查手机网络，刷新付款码后重新预授权，并让顾客在付款码页面等待确认 | 用户检查手机网络，刷新条码后，重新扫码发起请求 |
| restricted_merchant_industry | 商户所属行业mcc单笔订单金额限制 | 请商户与支付宝客服确认行业mcc订单金额限制信息 |
| secondary_merchant_status_error | 商户状态异常 | 请商户与支付宝客服联系确认 |
| smile_pre_auth_zm_consult_fail | 刷脸场景下信用准入咨询异常 | 请求参数不变，适当重试几次，如果仍然是同样的错误，请联系支付宝 |
| sub_merchant_level_error | 间联商户等级校验错误 | 间联商户等级校验错误，请提高间联商户的等级 |
| sub_merchant_no_permission | 此二级商户没有进行预授权产品的进件/入驻，请先完成预授权产品的进件/入驻后再重新发起请求 | 请先完成预授权产品的进件/入驻后再重新发起请求 |
| sub_merchant_organization_id_error | 间联模式下，传入的二级商户的机构id为空或错误 | 间联模式下，传入正确的机构id |
| unique_violation | 授权失败，商户订单号重复，请收银员取消本笔订单并重新授权 | 更换商户的授权资金订单号后，重新发起请求 |
| unsupported_biz_type | 不支持的业务类型 | 一般是接口入参传递错误，请先对照接口文档自行检查修正，仍无法解决的请联系支付宝。 |
| unsupport_order_amount | 不支持的订单金额 | 确认订单金额合法后，更换订单号并重新发起请求 |
| user_account_validate_fail | 用户账号校验失败 | 用户账号信息校验失败，请确认当前用户与支付宝用户是否匹配。 |
| user_bankcard_canceled | 用户银行卡已销户 | 用户银行卡已销户，请检查用户银行卡状态 |
| user_bankcard_express_error | 用户银行卡快捷支付异常 | 用户银行卡快捷支付异常，请检查用户银行卡状态 |
| user_bankcard_frozen | 用户银行卡已冻结 | 用户银行卡已冻结，请检查用户银行卡状态 |
| user_bankcard_pay_error | 用户银行卡支付失败 | 用户银行卡支付失败，请检查用户银行卡状态 |
| user_bankcard_report_loss | 用户银行卡已挂失 | 用户银行卡已挂失，请检查用户银行卡状态 |
| user_bankcard_status_error | 用户银行卡状态异常 | 用户银行卡状态异常，请检查用户银行卡状态 |
| user_face_payment_switch_off | 授权失败，顾客当面付付款开关关闭，请用户在手机上打开当面付付款开关 | 让用户在手机上打开当面付付款开关 |
| 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=null&out_order_no=null&operation_id=null&out_request_no=null&operation_type=null&amount=null&status=null&gmt_create=null&gmt_trans=null&payer_logon_id=null&payer_user_id=null&payee_logon_id=null&payee_user_id=null&total_freeze_amount=null&total_unfreeze_amount=null&total_pay_amount=null&rest_amount=null&payer_open_id=03914imefxss9k-tsvhy-iisrllofthfgdvo-hu30xtkpg9&merchant_app_id=2016092901250233&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"}