接口调用规范

针对唤起收银台的交易需确保能及时获得用户支付结果

原因：对于等待支付的交易，商家如果无法及时确认用户付款是否成功，容易引起资损和纠纷。

建议方案：对所有唤起收银台的交易（支付宝返回状态10003）发起轮询，并且建议轮询总时间设为 30 秒，轮询平均间隔设为 3 秒。让用户再次支付前，必须通过查询确认当前订单的状态。

同一订单的部分退款需确保退款请求号不重复

原因：同一笔交易如果不改变退款请求号 out_request_no，会因为请求号冲突，导致部分退款失败。

建议方案：同一笔交易若发起多次部分退款，每一次都需要改变 out_request_no。

入参规范

参数	规范	说明
storeid	storeid 不能含有中文字符	原因：中文有可能引起乱码，在有营销活动的情况下，会导致营销活动无法生效。建议方案：建议 storeid 全部用字母和数字的组合。
支付请求需要传入 storeid	原因：如果不传，会导致在商家自营销活动发放的券无法核销。建议方案：建议所有支付订单都加入 storeid 参数。
terminalid	机具接入请传入 terminalid	原因：在机具支付异常的情况下无法跟踪，无法得到后续保障，也会导致营销活动无法生效。建议方案：所有机具接入的支付请求需要带入 terminal_id 参数。
sys_service_provider_id	需要返佣的服务商（独立软件开发商）请确保传入正确的sys_service_provider_id	原因：服务商接入如果不传入正确的 sys_service_provider_id，会导致无法获得返佣。建议方案：建议服务商接入的所有订单都加入 sys_service_provider_id 参数，并检查参数是否正确。
discountable_amount	确保带有折扣参数的订单可以正常享受优惠	原因：订单里的可打折金额（discountable_amount）如果设置成 0，该笔订单将无法享受折扣。建议方案：在传入打折参数的情况下，请确认 discountable_amount 不为 0。
goods_detail	参与单品活动的交易需要传入正确的 goodsdetail 信息	原因：如果交易参数中的 goodsdetail 为空或者有误，将无法参与单品活动。建议方案：参与单品活动的商家请检查请求是否包含 goodsdetail，并确保 goodsID 和口碑后台所配置的相一致。

异常处理

不合法传参

原因：传参错误会导致支付异常。

建议方案：对所有返回 INVALID_PARAMETER 的响应进行监控，一旦发现请停止调用并检查请求参数，修改后重新发起请求。

接口调用发生异常

现象：接口的大量调用错误，商家带宽被无效调用占用，会导致访问支付宝速度变慢，并且容易引发商家端处理错误，造成系统无法正常使用，严重影响系统稳定性及用户体验。

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

查询接口 alipay.trade.query 和撤销接口 alipay.trade.cancel 调用异常：立即重试一分钟，如果仍然返回超时或未知异常，需要记录该异常交易并走人工处理流程

下单接口 alipay.trade.precreate 调用异常：使用新的商家订单号 out_trade_no 重新调用预下单接口。

退款接口 alipay.trade.refund 调用异常：使用相同的参数重试一分钟，如果仍然返回超时或未知异常，需要记录该异常交易并走人工处理流程，不能简单的推断为退款成功或失败。

支付接口 alipay.trade.pay 调用异常，立即调用查询接口，如果：

查询的交易不存在（错误码 ACQ.TRADE_NOT_EXIST），使用相同的参数重新调用支付接口。

网络超时或未知异常，继续查询一分钟，如仍然超时或未知异常，需要记录该异常交易并走人工处理流程，不能简单的推断为付款失败。

资金安全

未支付订单请及时撤销

原因：未支付订单如果不及时关闭，用户可能会误支付，从而导致用户资损，引起单边账。

建议方案：

对于未支付的订单，请及时通过调用撤销接口关闭订单（注意：超过 24 小时的订单无法撤销）。

为每笔订单设置超时时间，超过时间未支付的订单会自动关闭。

不要将撤销接口用于退款业务

原因：退款接口用于正常退款业务，撤销接口用于在订单出现问题时候将其撤销并关闭。两者的业务场景完全不同，错用会导致订单状态与业务状态不匹配，在监控下无法准确地发现系统异常。

建议方案：所有退款业务都必须调用退款接口。

单品总金额与订单总金额要一致

原因：单品总金额与订单金额不一致会导致实收金额与应收金额不匹配，从而引起资损。

建议方案：在传入单品的情况下，订单总金额需要基于单品的单价和数量计算出来。

不要在没有获得交易结果的时候要求用户再次付款

原因：商家端没有获得交易结果，很有可能是用户已经付款成功只是商家端单方面原因（网络问题）导致没有获得支付结果，再次支付会导致用户资损。

建议方案：对于商家端没有获得交易结果的订单，请和用户确认支付结果，如果用户已经支付成功，请先退款然后让用户再次支付。

支付体验

合理的轮询间隔以及轮询总时间

原因：如果轮询总时间太短，而用户输入密码时间较长，商家可能无法获得支付结果，导致资损和纠纷。如果轮询时间太长，会产生不必要的资源消耗，降低服务器性能。同样，轮询间隔如果过短，会给服务器带来压力，降低性能，反之，会无法及时得到支付结果，增加不必要的排队等待时间。

建议方案：建议轮询总时间设置在 30 秒，轮询间隔设为 3 秒。

提高订单支付成功率

原因：支付失败现象增多会引起商家收银问题，增加用户等待时间，引起单边账，降低用户满意度。

建议方案：对支付接口的返回进行监控，如果有较高比例的支付失败，需要及时排查原因。付款码支付成功率建议保持在 95% 以上。

新建的订单都需要改变订单号

原因：外部订单号重复会导致交易失败，不予以控制将增大服务器开销，增加用户等待时间。

建议方案：对新建的订单进行跳号处理。

支付结果异步通知

异步通知验签

商家接受到异步通知后需要先验签，以确保该通知来自支付宝发出的。验签的详细规则可查看异步通知验签，同时建议参考以下代码使用支付宝提供的开发平台服务端SDK 来辅助验签。

Map < String ,  String >   paramsMap   =  ...  //将异步通知中收到的所有参数都存放到map中 
 boolean   signVerified   =   AlipaySignature . rsaCheckV1 ( paramsMap ,  ALIPAY_PUBLIC_KEY ,  CHARSET , SIGN_TYPE )  //调用SDK验证签名 
 if ( signVerfied ){
     // TODO 验签成功则继续业务操作，最后在response中返回success 
} else {
     // TODO 验签失败则记录异常日志，并在response中返回failure. 
}

**注意：**出于安全考虑，验签完成后，请开商家务必检查通知中的 appid、外部订单号和订单金额与预下单时传入的是否一致。

最佳实践

最佳架构

商家和服务商在对接支付宝时，通常有以下两种形式：

门店直连，即门店收银终端直接通过公网请求支付宝。

商家和服务商后台转发，即商家和服务商开发并部署独立的服务端（支付中台），门店收银终端先请求到商家服务端，再由服务端请求支付宝。

建议是用第二种转发模式，这样可以方便日志记录、问题排查，同时将支付逻辑和原有业务逻辑尽量解耦。

商家订单号生成

当同一业务订单需要进行多次支付（前几次失败或被撤销）时，需要保证每次调用接口传入的商家订单号 out_trade_no 不重复，因此不能直接将业务订单号作为商家订单号使用，而是应该为每个支付请求生成独立的流水号，并在商家服务端维护业务订单号与流水号（商家订单号）的关系。

建议商家订单号规则为业务订单号+请求序号，例如对于业务订单号 A10001，第一次请求支付的商家订单号为 A10001_0，如果失败或未支付被撤销，再次发起的支付的商家订单号为 A10001_1，以此类推。

轮询设计

当请求支付返回 WAIT_BUYER_PAY 时，收银系统需要做轮询处理，建议：

收银终端界面阻塞并提示等待用户确认支付。

轮询间隔设为 3-6 秒，轮询总时长 60 秒左右。

轮询时，收银终端界面提供手动停止功能，停止时必须调用撤销 API 撤销支付宝交易。

单边账

单边账是指对于一笔交易，商家端和用户端的结果不一致，分为两种情况：

商家资损单边账：用户实际未付款成功，但商家系统判定支付成功；或用户支付成功后，商家系统由于逻辑问题发起了撤销。

用户资损单边账：用户付款成功，但商家系统未得到支付成功的结果，误认为付款失败，再次扫用户付款码发起支付，导致用户多支付了一笔。在用户手机网络不好的情况下，支付成功后用户手机不一定会显示支付成功页面，用户自己也不知道已经付成功了。这种情况在小额场景下尤其容易出现，且难以发现，需要商家和服务商特别注意。

避免出现单边账的措施

为了避免单边账，建议商家和服务商采取以下措施。

每一笔交易一定要闭环：即支付成功或撤销交易，不能有交易一直停留在等待用户付款的状态。

轮询 + 撤销的流程中，如轮询的结果一直为未付款，撤销一定要紧接着最后一次查询，不能有时间间隔。

门店收银系统应该具备独立的手动查询功能作为兜底，输入商户订单号（可从用户手机账单中获得）调用支付宝查询接口获得确切的支付状态。

当遇到网络超时和未知异常时，参考异常处理流程正确处理，对于每一笔交易或退款，一定要得到确切的结果。

撤销接口调用成功后，需要在收银台页面为收银员展示撤销成功的强提示文案，且按实际业务情况引导收银员进行手工订单查询。如果撤销接口没有明确返回处理结果，如遇到网络超时或支付宝未知异常等情况，则需要在收银台提示文案中表明，撤销正在处理中；若该笔订单已经支付则后续会有发生退款的可能，并和用户做好线下沟通。

对于经过轮询和撤销仍然无法确认结果的（例如系统故障或门店断网），应上报总部 IT 或财务，由 IT（从系统内）或财务（从支付宝后台），确认支付结果后，通过后台发起退款。或让用户查询手机支付宝账单，如用户手机没网络，可拨打支付宝客服热线 4007585858 确认支付结果。

在上述基础上，业务流程培训时应强调支付结果必须以商家端为准，用户手机上的支付宝结果或账单只能做参考，不能作为最终识别标准。如果商家未正确处理业务逻辑和业务流程培训，存在潜在的风险，商家自行承担因此而产生的所有损失。

当面付接入注意事项

接口调用规范#

针对唤起收银台的交易需确保能及时获得用户支付结果#

同一订单的部分退款需确保退款请求号不重复#

入参规范#

异常处理#

不合法传参#

接口调用发生异常#

资金安全#

未支付订单请及时撤销#

不要将撤销接口用于退款业务#

单品总金额与订单总金额要一致#

不要在没有获得交易结果的时候要求用户再次付款#

支付体验#

合理的轮询间隔以及轮询总时间#

提高订单支付成功率#

新建的订单都需要改变订单号#

支付结果异步通知#

异步通知验签#

最佳实践#

最佳架构#

商家订单号生成#

轮询设计#

单边账#

避免出现单边账的措施#