1  产品介绍

    用户在宾馆、酒店等场所消费时，消费与资金结算往往不在同一时间完成，用户在消费时缴纳一定的押金，消费结束结算时，再根据实际消费情况从押金中扣除消费金额，剩余未消费部分返还给用户。支付宝根据此类业务线下消费场景的习惯，推出当面资金授权产品，用户在消费时，先针对可用资金渠道做资金授权（冻结），结算时从冻结资金扣划给商户，剩余资金解冻返还给用户。

    具体案例：

    山东奢品酒店已上线使用当面资金授权功能。使用流程如图：

1.1适用场景

    用户打开钱包付款码，店员用扫码设备扫描钱包付款条码预缴押金办理入住，退房时收银员根据用户消费情况进行支付结算，结算过程由收银员发起无需用户干预，如有多冻结押金部分直接由收银员通过系统操作解冻。

1.2业务流程

使用步骤：

• 用户登陆支付宝APP，点击首页“付款”，进入付款码界面；
• 收银员在商家收银系统操作生成订单，用户确认授权金额；
• 用户出示APP的“付款码”，收银员用扫码设备来扫描用户手机上的条码后，商家收银系统提交授权冻结；
• 授权成功后商家收银系统会拿到授权成功或者失败的结果；
• 消费完成后实际结算时，商家根据实际消费情况直接从原冻结资金发起扣款，用户无需参与，仅在实际扣款成功后收到推送通知。

1.3签约流程

1）ISV签约：走第三方应用授权模式ISV无需签约，直接找对应运营申请挂载接口包。

2）一般商户签约：直接签约“当面资金授权”。

签约方式：

• 目前只能BD后台签约。

ISV代商户签约（目前暂未开放，预计 2月初上线）。

2  技术集成

2.1接口概述

签约销售方案共包含7个接口，各接口描述和使用场景详见下表接口使用说明（接口文档尚未在线上开放，需要请联系雨菲获取）。

接口英文名	接口名称	描述	使用场景
alipay.fund.auth.order.freeze	资金授权冻结接口	通过调用该接口创建支付宝授权订单并完成资金冻结	收银员使用扫码设备读取用户支付宝钱包“付款码”后，将二维码或条码信息和订单信息通过本接口上送至支付宝发起资金授权冻结。
alipay.fund.auth.operation.cancel	资金授权撤销接口	通过调用该接口撤销授权冻结操作	只有发生授权系统超时或者授权结果未知时可调用撤销，其他正常授权冻结的操作如需实现相同功能请调用资金授权解冻服务。提交资金授权后调用【资金授权操作查询】，没有明确的授权结果再调用【资金授权撤销】
alipay.fund.auth.order.unfreeze	资金授权解冻接口	支持部分和全部解冻	当资金授权发生之后一段时间内，由于买家或者商家等其他原因需要要解冻资金，商家可通过资金授权解冻接口将授权资金进行解冻，支付宝将在收到解冻请求并验证成功后，按解冻规则将冻结资金进行解冻，原路退回支付宝账号
alipay.fund.auth.operation.detail.query	资金授权操作查询接口	通过调用该接口查询授权操作明细信息	商家后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；调用资金授权冻结接口后，返回系统错误或未知交易状态情况；调用资金授权冻结请求后，返回处理中的状态（返回结果中的code等于10003）；注意：调用撤销接口之前，需通过操作查询接口确认该笔授权操作目前的状态（返回结果status=”SUCCESS”表明授权操作成功）。 当商家调用“资金授权解冻接口”时出现系统错误，商户可使用该接口查询提交的解冻请求是否执行成功。
alipay.trade.pay	交易创建并支付接口	通过调用该接口创建支付宝交易订单 并使用预授权资金完成支付	当商家需要对用户授权资金进行解冻支付时，商家可通过交易创建并支付接口将用户授权资金支付给卖家，支付宝将在收到请求后创建相应交易单并将授权资金支付给卖家
alipay.trade.refund	交易同步退款接口	支持部分和全部退款	当交易发生之后一段时间内，由于买家或者卖家的原因需退款，卖家可通过退款接口将支付款退还给买家，支付宝将在收到退款请求并验证成功后，按退款规则将支付款按原路退到买家帐号上
alipay.trade.query	交易订单查询接口	通过调用该接口查询订单的状态	商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；

2.2接口调用流程

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

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

服务调用流程：

免密模式：

验密模式：

1. 商户系统将用户付款码与订单信息一起通过资金授权冻结接fund.auth.order.freeze请求到支付宝，并从接口同步返回中获取支付结果。
2. 根据公共返回参数中的code做相应后续业务处理。这笔授权操作可能有四种状态：授权成功（10000），授权失败（40004），等待用户授权（10003）和未知异常（20000）。结果码描述和处理方式见下表。

关键入参：

参数名称	参数说明
out_order_no	商户授权资金订单号，需要保证不重复
out_request_no	商户授权资金操作流水号，需要保证不重复
auth_code	用户付款码
auth_code_type	固定值传入bar_code
order_title	订单标题
amount	冻结金额
pay_timeout	授权超时时间

关键出参：

参数名称	参数说明
auth_no	支付宝28位授权资金订单号
operation_id	支付宝标识本次资金操作的流水号
status	本次资金授权操作的状态

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

商户因业务原因需要解冻用户授权资金时，可通过商户订单号和操作流水号，或者支付宝订单号和操作流水号进行资金解冻，支持部分解冻。

业务规则：

1. 冻结订单的资金解冻都需要由商户端发起，支付宝对冻结资金不会发起自动解冻；
2. 解冻服务中的附言remark字段会展示在用户的支付宝账单上。

调用流程：

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

关键入参：

参数名称	参数说明
auth_no	支付宝28位授权资金订单号
out_request_no	商户授权资金操作流水号，需要保证不重复
amount	解冻金额
remark	操作描述，展示在用户支付宝账单上

关键出参：

参数名称	参数说明
auth_no	支付宝28位授权资金订单号
operation_id	支付宝标识本次资金操作的流水号
status	本次资金授权操作的状态

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

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

业务规则：

提交资金授权后调用【资金授权操作查询】，没有明确的授权结果再调用【资金授权撤销】。

关键入参：

参数名称	参数说明
auth_no	支付宝28位授权资金订单号
operation_id	支付宝资金授权冻结操作流水号
out_order_no	商户资金授权订单号
out_request_no	商户资金授权冻结操作流水号
remark	操作描述

关键出参：

参数名称	参数说明
action	本次撤销触发的动作 close：关闭订单，无资金解冻 unfreeze：产生了资金解冻

2.2.4资金授权操作查询接口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	本次资金授权操作的状态

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

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

业务规则：

1. 商家通过系统调用支付宝的交易创建并支付服务将用户授权资金解冻转支付给卖家，该过程无需再次扫描用户钱包付款码；
2. 交易创建并支付的金额应小于等于用户授权资金金额，当支付金额小于授权冻结金额时，剩余授权冻结金额需要商户在发起授权资金解冻请求将剩余冻结资金进行解冻。

调用流程：

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

关键入参：

参数名称	参数说明
out_trade_no	商户订单号，需要保证不重复
total_amount	订单金额
product_code	产品码，当面授权场景传固定值FUND_TRADE_FAST_PAY
auth_no	支付宝资金授权单号
subject	订单标题
buyer_id	买家支付宝uid，即资金授权用户uid，必传
seller_id	卖家支付宝uid，即资金授权收款方uid

业务参数样例：

"biz_content":{

    "out_trade_no":"20161122000000001",

    "sence":"bar_code",

    "auth_no":"2016111710002001390222200964",

"product_code":"FUND_TRADE_FAST_PAY",

    "subject":"冻结转支付",

 "buyer_id":"2088202415071394",

  "seller_id":"2088211521646673",

    "total_amount":0.01

    }

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

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

调用流程：

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

关键入参：

参数名称	参数说明
out_trade_no	支付时传入的商户订单号，与trade_no必填一个
trade_no	支付时返回的支付宝交易号，与out_trade_no必填一个
out_request_no	本次退款请求流水号，部分退款时必传
refund_amount	本次退款金额

关键出参：

参数名称	参数说明
refund_fee	该笔交易已退款的总金额

2.2.7交易查询接口alipay.trade.query

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

调用流程：

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

关键入参：

参数名称	参数说明
out_trade_no	支付时传入的商户订单号，与trade_no必填一个
trade_no	支付时返回的支付宝交易号，与out_trade_no必填一个

关键出参：

参数名称	参数说明
trade_no	支付宝28位交易号
out_trade_no	支付时传入的商户订单号
trade_status	交易当前状态

2.2.8 结果码

结果码	说明	处理方式
10000	授权成功	记录授权结果并在客户端显示授权成功，进入后续的业务处理。
40004	授权失败	记录授权结果并在终端显示错误信息（display_message)。
10003	等待用户授权	发起轮询流程：等待5秒后调用资金授权操作查询接口alipay.fund.auth.operation.detail.query通过授权时传入的商户授权订单号(out_order_no)和资金操作流水号(out_request_no)查询授权结果（返回参数status），如果仍然返回等待用户授权（INIT），则再次等待5秒后继续查询，直到返回确切的授权结果（成功SUCCESS 或 已关闭CLOSED），或是超出轮询时间（建议轮询时间为30s）。在最后一次查询仍然返回等待用户授权的情况下，必须立即调用资金授权撤销接口alipay.fund.auth.operation.cancel将这笔授权操作撤销，避免用户继续操作。
20000	未知异常	调用查询接口确认授权结果，详见异常处理。

2.2.9 异常处理

在调用支付宝接口时，可能会遇到网络超时或支付宝未知异常(接口返回code=20000，sub_code=isp.unknow-error或SYSTEM_ERROR)，此时业务处理结果是未知的，需要根据具体API采取以下措施。

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

立即调用查询接口：

查询结果	处理办法
授权成功或等待用户授权	继续业务处理，履行订单或发起轮询
查询的授权操作不存在（错误码AUTH_ORDER_NOT_EXIST）	使用相同的参数重新调用授权接口
网络超时或未知异常	继续查询一分钟，如仍然超时或未知异常，需要记录该异常授权操作并走人工处理流程，不能简单的推断为授权失败。

查询接口alipay.fund.auth.operation.detail.query 和 撤销接口alipay.fund.auth.operation.cancel

立即重试一分钟，如果仍然返回超时或未知异常，需要记录该异常授权操作并走人工处理流程。

资金授权解冻接口aipay.fund.auth.order.open.cancel

使用相同的参数重试一分钟，如果仍然返回超时或未知异常，要记录该异常授权操作并走人工处理流程，不能简单的推断为解冻成功或失败

2.3集成方案

2.3.1集成流程

2.3.2开发前准备

1、密钥配置

特别注意：沙箱和线上的密钥配置地址不同，此处重点介绍线上正式密钥配置方式。沙箱密钥配置方法类似。

获取商户appid、配置商户公钥：

秘钥生成和上传RSA密钥可参考在线视频：https://doc.open.alipay.com/docs/doc.htm?spm=a219a.7629140.0.0.Oskt2a&treeId=291&articleId=106103&docType=1

打开https://open.alipay.com登录商户支付宝账号如下图所示：

点击右上登录账户名下拉框中的“账户中心”，打开如下界面。

点击“设置应用公钥”链接，设置商户应用公钥并保存。（下图是添加完商户公钥后的截图），会多出一个“查看支付宝公钥”的链接。

获取支付宝公钥：

点击查看支付宝公钥，可以查看支付宝的公钥，将此公钥提供给开发人员，配置到商户的系统中。

沙箱密钥配置方法和线上类似，只是配置地址不同，在此不再累述。地址如下：https://openhome.alipay.com/platform/appDaily.htm?tab=info

2、SDK下载

下载对应开发语言版本的SDK并引入到您的开发工程，进行接口开发。https://doc.open.alipay.com/docs/doc.htm?spm=a219a.7629140.0.0.Z4VGW7&treeId=193&articleId=103419&docType=1

2.3.3沙箱测试

沙箱和线上接口功能相同，由于目前沙箱客户端功能尚在测试阶段，所以未发布到沙箱正式环境。在发布之前如需沙箱测试请联系对应技术支持工程师协助开通接口权限。

沙箱测试目前存在问题：能做服务端接口测试，客户端功能未发布。

沙箱环境使用见沙箱环境使用说明

2.3.4验收上线

1、冻结转支付后如果有剩余冻结金额要求系统中立即操作解冻，同时后台要开放人工单独解冻的入口，防止后续商户投诉能方便操作解冻。

2、冻结资金要大于未来消费转支付金额，目前接口不支持追加冻结。

3、alipay.trade.pay接口中需要传入store_id、terminal_id参数。如果是系统商接入还需要传入"extend_params":{"sys_service_provider_id":"ISV签约账户的PID"}参数。

3 系统对账

1、Sftp账单模式：该模式需要联系BD申请sftp账户和账单模板配置。如有业务账单需求只能申请配置sftp账单配置。

2、账单接口方式（查询账单接口(alipay.data.dataservice.bill.downloadurl.query)）：开通当面资金授权产品即开通账单下载地址接口权限。可以获取到业务账单和账务账单（目前离线账单下载接口只能下载账务账单，业务账单需要4月份接口改造完成后上线）。

3、支付宝站内下载账单：签约账户登录www.alipay.com，到对账--账单下载中下载日账单。

三种方式都是T+1提供账单，一般在每天上午10:00之前生成账单。

4 常见问题

1、冻结、解冻、转支付、退款会分别产生一笔账单记录。账单中冻结和解冻金额前不会有“+、-”符号，因为没有真正发生资金变动，资金是在转支付时才划入商家账户。

2、授权冻结支持的支付渠道以及默认冻结顺序：红包>借记卡>余额>余额宝>花呗。如果用户在支付宝客户端有设置默认扣款顺序，则以用户设置为准，其中红包都是优先于其他支付工具冻结。

3、授权验证密码规则：
◆ 授权金额>2000元的交易需要验证用户支付密码

◆ 用户账号每天最多有5W额度可以免密授权，超过后需要验证密码

◆ 因无可用支付工具等原因导致免密授权失败，也会要求验证密码

◆ 支付宝后台判断用户授权行为有异常情况，也会要求验证密码

4、资金授权解冻接口报ILLEGAL_ARGUMENT。

原因可能是资金授权冻结接口和解冻接口中的out_request_no重复导致。需要保证冻结和解冻每笔请求的out_request_no不重复。

 

FAQ

关于此文档暂时还没有FAQ