支付宝预授权集成流程

2022-03-10 23:15:35

一、文档地址

官方文档地址：[url]https://docs.open.alipay.com/20180417160701241302[/url]

二、开发前准备工作

1、签约：[url]https://openclub.alipay.com/read.php?tid=276&fid=72[/url]

2、创建应用：[url]https://openclub.alipay.com/read.php?tid=1606&fid=72[/url]

3、生成密钥：[url]https://openclub.alipay.com/read.php?tid=1833&fid=69[/url]

4、下载服务端sdk：[url]https://docs.open.alipay.com/54/106370/[/url]

注意事项：1、不支持沙箱测试；2、需签约并添加功能；3、支持第三方调用。

检查调用appid的应用功能列表中是否添加“支付宝预授权”。

三、接口集成流程

1、各接口注意事项

1.线上资金授权冻结(alipay.fund.auth.order.app.freeze)

功能：创建支付宝授权订单并完成资金冻结。适用于线上场景完成资金授权, 例如从商户APP端拉起支付宝收银台完成冻结。

调用该接口会直接将用户金额冻结扣款，扣款完成后可调用授权转支付接口进行支付，或者调用解冻接口进行解冻，将接原路退还给用户；

注意事项：

（1）：请求参数的out_order_no和out_request_no参数每一次请求都必须保证唯一，即使是之前请求报错，也不能使用相同的信息再次请求

（2）：payee_logon_id和payee_user_id两个参数，如果商户有勾选花呗渠道则必须传入其中一个不能都为空，建议在不确定是否签约有勾选花呗渠道的情况下一定要传入这个参数，或是可以联系商户客服咨询自己的签约支付宝预授权是否有勾选花呗渠道后再选择传入，联系商户客服电话：0571-88158090，或在线商户客服：[url]https://cschannel.alipay.com/newPortal.htm?scene=mysjbzzx[/url]

（3）：product_code=PRE_AUTH_ONLINE，产品码，是固定值，不要更改;

（4）：extra_param为业务拓展参数，可以不传。如果传入category为业务分类，需要依据您的签约行业来选择传入。具体的分类请参考：[url]https://docs.open.alipay.com/10719[/url]。

（5）：enablePayChannels为选填字段，可以指定支付渠道，如果不传，默认为签约协议的支付渠道；若需要指定渠道，目前仅支持余额宝（MONEY_FUND）、花呗（PCREDIT_PAY）以及芝麻信用（CREDITZHIMA）；

（6）：该接口必须使用手机上安装支付宝钱包测试，在电脑模拟器上测试会直接报错；

（7）：冻结成功后会有冻结账单

2.授权转支付（alipay.trade.pay ）

功能：建支付宝授权订单并完成资金冻结。适用于线上场景完成资金授权, 例如从商户APP端拉起支付宝收银台完成冻结。

（1）：该接口是当面付条码支付接口，但又不需要传值支付码（auth_code），也无需签约当面付，只需签约支付宝预授权，将产品码（Product_Code）设置为：PRE_AUTH_ONLINE

授权转支付接口调用成功后会自动扣除金额；

（2）：如果auth_confirm_mode = COMPLETE；支付成功后，会自动扣款total_amount传值金额，将剩余金额还给用户；

（3）：如果auth_confirm_mode = NOT_COMPLETE；支付成功后，会自动扣款total_amount传值金额，剩余金额仍会冻结，不会解冻退还，需要调用解冻接口；

（4）：seller_id必须传入，且必须是appid对应的收款id，不传会报错；第三方应传值授权token对应的商户；不传值会报参数无效；

{"code":"40004","msg":"Business Failed","sub_code":"ACQ.INVALID_PARAMETER","sub_msg":"参数无效","buyer_pay_amount":"0.00","invoice_amount":"0.00","point_amount":"0.00","receipt_amount":"0.00"}

（5）：buyer_id必须传入，该参数可以在冻结成功的异步信息中获取

{"code":"40004","msg":"Business Failed","sub_code":"ACQ.INVALID_PARAMETER","sub_msg":"参数无效：买家不能为空","buyer_pay_amount":"0.00","invoice_amount":"0.00","point_amount":"0.00","receipt_amount":"0.00"}

（6）：支付宝预授权支付成功之后是无法调用退款接口退款的，调用我们的退款接口退款会直接报错“交易不存在”

{"alipay_trade_refund_response":{"code":"40004","msg":"Business Failed","sub_code":"ACQ.TRADE_NOT_EXIST","sub_msg":"交易不存在","refund_fee":"0.00","send_back_fee":"0.00"}

3.资金授权解冻(alipay.fund.auth.order.unfreeze)

功能：当资金授权发生之后一段时间内，由于买家或者商家等其他原因需要要解冻资金，商家可通过资金授权解冻接口将授权资金进行解冻，支付宝将在收到解冻请求并验证成功后，按解冻规则将冻结资金按原路进行解冻。

（1）：auth_no是调用资金冻结接口成功后返回的，填写错误会报系统繁忙

{"alipay_fund_auth_order_unfreeze_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"aop.SYSTEM_ERROR","sub_msg":"系统错误"},

3.资金授权撤销(alipay.fund.auth.operation.cancel)

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

（1）：调用授权转支付接口支付成功的订单无法调用撤销接口，调用会直接报错

{"alipay_fund_auth_operation_cancel_response":{"code":"40004","msg":"Business Failed","sub_code":"ORDER_ALREADY_FINISH","sub_msg":"授权订单已经完结，无法再进行资金操作"}

4.资金授权操作查询(alipay.fund.auth.operation.detail.query)

功能：通过该接口可以查询单笔明细的详细信息，细分到每一次操作，如冻结、解冻。

详细的返回参数API：[url]https://docs.open.alipay.com/api_28/alipay.fund.auth.operation.detail.query[/url]

2、demo示例

Java示例及demo：[url]https://openclub.alipay.com/read.php?tid=11412&fid=59[/url]

php示例及demo：[url]https://openclub.alipay.com/read.php?tid=11697&fid=60[/url]

.net示例及demo：[url]https://openclub.alipay.com/read.php?tid=11699&fid=60[/url]

四、注意事项

1.确认是否已签约，详细的请参考：[url]https://openclub.alipay.com/read.php?tid=11745&fid=72[/url]

2.如果想要使用芝麻免押功能，在默认的签约中是没有的需要商户主动邮件申请开通，主动申请开通【信用授权】，可主动发送至zmxyservice@zmxy.com.cn申请开通【信用授权】邮件内容包含商户名称，PID，商户的行业产品名。

3.支付宝预授权如何配置授权免押额度：[url]https://openclub.alipay.com/read.php?tid=11419&fid=72[/url]

五、常见接口报错

支付宝预授权接口报错系统异常自查方案：[url]https://openclub.alipay.com/read.php?tid=11411&fid=60[/url]

1.Q：线上资金授权冻结接口报错系统繁忙、系统异常

A:这个报错一般是参数或是秘钥问题，详细的排查方案请参考：[url]https://openclub.alipay.com/read.php?tid=11411&fid=60[/url]

2、Q：为什么无法使用花呗进行付款冻结？

A:使用花呗需要商户签约有花呗支付的渠道且拥有花呗准入的（可联系商户客服确认是否满足这些条件：联系商户客服电话：0571-88158090，或在线商户客服：[url]https://cschannel.alipay.com/newPortal.htm?scene=mysjbzzx[/url]）

3、Q：为什么有的用户无法使用芝麻免押？

A：商家必须要有芝麻免押渠道，首先必须芝麻分不低于配置的限定分值才能免押，其次如果该用户之前有逾期违规行为导致列入芝麻风控，行业黑名单，芝麻分足够也有可能无法免押的，是否准入根据芝麻平台风控判断为准，（如果无法使用免押可以咨询芝麻客服进行确认：客服电话：0571-88158055 转 2 在线咨询：[url]https://b.xin.xin/ant/product/index.htm[/url] ）

4、Q：如何使用银行卡进行付款冻结？

A：如果不限制渠道支付的话不传入enable_pay_channels参数，这样就可以选择使用银行卡进行付款冻结

5、Q：关于冻结接口生成订单的机制

A: 创建支付宝订单的机制是唤起支付宝收银台，比如A用户的支付宝钱包唤起了收银台，这时候B用户在使用A用户的URL去唤起收银台会报系统异常，或者参数无效。在唤起的时候就会根据支付宝客户端进行绑定订单

6、Q：关于冻结接口超时参数的问题pay_timeout

A：这个参数是控制订单超时的时间，不传默认是15M，这个不传指的是整个参数不传，而不是传入空值，超过15M后会再次进行付款冻结会出现两个报错，一个是系统异常，一个是订单参数异常

7、Q：关于调用冻结接口未安装支付宝钱包的问题导致的报错

A：这个是基于在支付宝客户端进行的，如果未安装支付宝钱包H5支付冻结是走不通的（不像日常使用的支付接口在未检测到支付宝客户端会转入到H5页面进行登入），会提示用户去安装支付宝钱包

码农公寓