支付
在获得买家授权后,您可以直接启动代扣服务,无需为每次支付再次进行授权流程。
要完成代扣支付,需执行以下两个步骤:
- 发起支付
- 获取支付结果
步骤1:发起支付
如果目标支付方式的余额足以支付买家的订单,您可以调用 支付(代扣) 接口来发起扣款。在请求中请正确传入以下参数:
- productCode:传入值为
AGREEME
NT_PAYMENT
。 - paymentMethod.paymentMethodId:您通过调用 申请支付令牌 接口获取到的支付令牌(accessToken)的值。
- paymentExpiryTime:如果您不指定此字段的值,则扫码签约请求过期时间为支付请求发送后的一分钟。如果您想限制支付请求的过期时间比一分钟更短,可以通过此字段传入对应的时长。值得注意的是,过期时间不支持比一分钟更长,另外,此字段的值需遵循 ISO 8601 标准。详情参考 支付(代扣)接口字段说明。
- paymentNotifyUrl:用于接收异步通知的地址,建议传入此参数。
在 支付(代扣) 接口的响应中,您需要根据 result.resultStatus 的值来判断扣款是否成功:
- 如果值为
S
,则扣款成功。 - 如果值为
U
,则交易仍在进行中。您需要通过轮询 支付结果查询 接口查询支付状态或等待异步通知来获取交易结果。 - 如果值为
F
,则扣款失败。您需要根据 resultCode 进行处理。
如果您无法收到响应,我们建议您使用相同的参数再次调用 支付(代扣)接口。
步骤2:获取支付结果
由于网络问题,异步通知有无法触达或延迟的可能性。为了获得准确的支付结果,您必须同时集成异步通知和支付结果查询服务。
1. 接收异步通知
除去从重定向到支付结果页面获取支付结果外,您还可以通过 支付(代扣)接口中的 paymentNotifyUrl 参数来设置异步通知地址。当支付完成或支付超时后,Antom 会通过 支付通知 接口向该地址发送异步通知。
当您收到 Antom 的通知时,您必须按照处理通知的示例代码格式返回响应。如果您未向 Antom 返回响应,或由于网络问题响应未被 Antom 接收到,Antom 则会在 24 小时内自动重试发送异步通知,最多重试八次或直至收到正确的响应终止发送。发送间隔为:0 秒,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时和 15 小时。
注意:支付成功后, Antom 会立即向您发送支付成功的异步通知。支付失败时,Antom 会在支付订单关闭后向您发送支付失败的异步通知。默认关单时间通常为支付发起后的 14 分钟。
2. 查询支付状态
我们建议您通过调用 支付结果查询 接口来查询支付状态。您可以在发起支付请求后且订单未关闭前使用此接口。
在 支付结果查询 接口返回的响应中,务必依赖 paymentStatus 作为支付状态,建议您按照一下表格做后续引导:
paymentStatus | 类型 | 描述 | 采取的行动 |
SUCCESS | 支付终态 | 支付成功。 | 显示支付成功。 |
PROCESSING | 支付中间态 | 支付正在处理中。 | 允许买家继续支付。 |
FAIL | 支付终态 | 买家未支付或支付失败。 | 允许买家继续支付或关闭支付订单。 |
CANCELLED | 支付终态 | 支付已被您取消。 | 允许买家继续支付或关闭支付订单。 |
表1. paymentStatus 详情
有关支付状态的详细信息,请参阅支付状态描述。
3. 最佳实践
为了获取准确的支付结果,建议您在数据库中维护一个订单表,至少包括两个字段:订单号和订单状态。并按照以下方式使用异步通知和支付结果查询服务:
- 异步通知:监听 Antom 的异步通知,并在接收到异步通知后返回响应。然后检查数据库中的订单状态:
- 如果订单状态为
INIT
,根据异步通知更新订单状态。 - 如果订单状态不是
INIT
,说明已经通过查询服务获取了最终支付结果,并更新了订单状态。不需要进一步操作。
- 支付查询:通过轮询的形式发起对支付结果的主动查询。在每次查询之前,您需要检查数据库中的订单状态:
- 如果订单状态为
INIT
,发起查询。如果获取到最终支付结果,更新数据库中的订单状态,否则继续轮询过程。 - 如果订单状态不是
INIT
,则表示已经进行了查询过程并获得了最终支付结果并用于更新订单状态,无需采取进一步操作。
图1. 使用异步通知和支付结果查询的最佳实践