订阅激活
在订阅支付流程中,买家选择一个套餐和支付方式,经过授权确认信息,然后被重定向到授权结果页面。在集成时,您需要创建展示支付方式的订阅激活页面。该页面通过授权 URL将用户重定向到结账页面,然后基于订阅状态处理支付回调将用户重定向到相应界面。
用户体验
订阅支付的用户体验如下:
图1. 订阅支付的用户体验
各部分的功能如下:
- 订阅激活页面:买家选择订阅计划和支付方式,并确认激活。此时生成一个订阅订单,并进入订阅授权流程。
- 授权流程:将用户重定向到支付方法授权页面,买家在此确认信息,验证身份并完成授权。随后买家会被重定向到 Antom 中间页面。
- 授权结果页面:授权完成后,买家会自动重定向到授权结果页面。
在集成过程中,您需要聚焦于创建订阅激活页面。此页面用于以下目的:
- 展示可用支付方式:支付方式根据支付金额和买家所在地区等支付信息进行排序。
- 重定向用户授权:使用 Antom 提供的授权 URL将买家重定向到授权页面。
- 接收支付回调(可选):通过监控页面调用或使用生命周期函数接收支付回调,随后可以根据订阅状态将买家重定向到订阅结果页面。
集成步骤
通过以下步骤开始集成:
- 获取并显示可用支付方式。
- 调用授权流程。
步骤1:获取并展示可用支付方式
获取支付方式的名称和标识,并在页面上显示可用的支付方式。
获取支付方式的名称和支付方式logo
请联系 Antom 技术支持以获取对应于每种支付方式的名称和logo。
过滤支付方式
在展示所有支付方式之前,建议取消展示或禁用正在维护的支付方式,以避免订阅失败。您可以联系 Antom 技术支持查询支付方式的维护状态。
展示支付方式
对于 Alipay+ 支付方式,您必须展示 Alipay+ 合作伙伴的logo。您可以选择以下样式之一,确保每个支付方式的名称和标识使用正确:
步骤2:发起授权流程
您需要先获取授权 URL,然后发起授权流程。
拦截无效订单
为了避免重复订阅或订阅过期,建议您在买家点击或触摸 立即订阅 后,验证订单的状态和有效期。
为了拦截过期的订阅授权,您可以通过指定 paymentExpiryTime 参数来设定订阅的过期时间。如果买方在订阅过期时间后进行授权,将会报告错误。设置订阅的过期时间还可以避免买方在被重定向到支付方式页面后,长时间延迟授权所导致的重复订阅情况。
服务器的时间偏差也可能导致重复的订阅授权。建议在接收有关订阅和支付状态的异步通知时,检查状态。如果出现重复授权情况,请使用取消订阅 接口取消订单。
获取授权URL
当买家点击或轻触 立即订阅 后,您的客户端会向服务器请求授权URL,随后您的服务器调用 订阅创建 获取授权 URL 并将其返回给客户端。在请求完成并获得授权 URL 之前,请禁用 立即订阅 按钮,以防用户触发重复操作。
在请求授权 URL 的过程中,由于网络问题,客户端和服务器端的请求都可能失败。建议在客户端的 HTTP 请求中设置超时,以防止买家等待时间过长。如果无法获取授权 URL,需要允许买家重新发起订阅授权。
订阅授权请求中的关键字段如下。
字段名称 | 描述 |
subscriptionRequestId | 商户为识别订阅请求分配的专属 ID。 |
env | 根据客户端类型指定 terminalType:
|
subscriptionRedirectUrl | 用户授权订阅后重定向到的商户页面链接。
|
subscriptionNotifyUrl | 用于接收订阅结果通知的链接。 请指定为 HTTPS 链接。 |
paymentNotifyUrl | 用于接收每个订阅周期支付结果通知的链接。请指定为 HTTPS 链接。 |
进行授权流程
授权流程的用户体验如下:
重定向到结果页面
在 订阅创建 接口中,可以通过 subscriptionRedirectUrl 参数设置授权 URL。 根据以下 terminalType 的值,建议传递 H5 URL或deep link:
terminalType | subscriptionRedirectUrl |
WEB | 传递一个 H5 URL。 |
WAP | 传递一个 H5 URL。 |
APP | 传递一个deep link。 |
当买家完成授权后,他们首先会被重定向到 Antom 的中间页面,然后再被重定向到商户的页面。
授权完成后,Antom 会发送一个异步通知到 subscriptionNotifyUrl ,通知您授权是否成功。
当您收到来自 Antom 的通知时,您必须按照 订阅结果通知 中的代码示例进行响应。如果您没有向 Antom 返回响应,或者由于网络问题 Antom 未收到响应,Antom 将在 24 小时内自动重试发送异步通知,最多八次,直到收到正确的响应。发送间隔如下:0 秒,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时和 15 小时。
订阅场景示例
请特别关注与订阅周期和订阅开始时间相关的参数。这些参数定义了为买家提供的订阅套餐。
关键参数
您可以通过在 订阅创建 接口中配置以下参数来管理订阅周期和定期支付逻辑:
字段名称 | 描述 |
subscriptionStartTime | 订阅开始的时间。您可以设置为过去的时间,但不能早于订阅请求发起前的一个周期。 |
subscriptionEndTime | 订阅结束的时间。 |
paymentAmount | 每个订阅周期向用户收取的支付金额。 |
periodRule.periodType | 订阅周期类型。有效值为: |
periodRule.periodCount | 订阅周期内的周期类型数量。例如,如果 periodType 的值为 |
trials.trialStartPeriod | 试用期的开始订阅周期。 |
trials.trialAmount | 每个订阅试用期的折扣金额。 |
trials.trialEndPeriod | 试用期的结束订阅周期。如果此参数留空,默认值将与 trials.trialStartPeriod 相同。 |
参数 subscriptionStartTime 设置了订阅支付的起始时间,而 periodRule 参数定义了订阅的计费间隔,从而划定了计费周期。
假设 subscriptionStartTime 为 2023-08-01T08:00:00+8:00
, periodRule.periodType 是 MONTH
,并且 periodRule 的 periodCount 为1
,计费周期为一个月,重复支付的详细情况如下:
期数 | 订阅开始时间 | 扣款时间 | 若扣款失败 |
1 | 2023-08-01T08:00:00+8:00 | 授权完成时间 | 授权失败 |
2 | 2023-09-01T08:00:00+8:00 | 2023-08-31T08:00:00+8:00 至 2023-09-01T08:00:00+8:00 | 无影响 |
3 | 2023-10-01T08:00:00+8:00 | 从2023-09-30T08:00:00+8:00到 2023-10-01T08:00:00+8:00 | 无影响 |
4 | 2023-11-01T08:00:00+8:00 | 从2023-10-31T08:00:00+8:00到 2023-11-01T08:00:00+8:00 | 无影响 |
... | ... | ... |
如果首个订阅周期的扣款成功,Antom 会在每个后续周期开始前 24 小时开始尝试扣款,直到扣款成功或 24 小时后结束。
如果您收到第二个订阅周期的扣款失败通知,您不能自行发起该周期的扣款请求。您需要调用取消接口来取消买家的后续订阅服务。
无论 subscriptionStartTime 是在订阅授权完成之前还是之后,首次支付会在买家完成订阅授权时执行。后续支付遵循计费周期时间表, Antom 会在每个周期开始前 24 小时发起扣款。如果扣款失败,Antom 会连续尝试 24 小时,直到支付成功或 24 小时期限结束。
在扣款成功或失败后,您将通过异步通知了解支付状态。接收通知的地址在 Antom Dashboard 或 订阅创建 中的请求参数 paymentNotificationUrl 指定。
注意:关于扣款失败的情况:
- 如果首次扣款失败:订阅授权将失败,订阅不会生效。
- 如果在后续支付周期中扣款失败:
- 订阅状态不会改变,订阅保持有效。
- 对于特定期间的失败扣款,您不能重试扣款。但是,当前期间的扣款失败不会影响后续期间的扣款。
示例
通过指定相应的参数,您可以使用订阅支付服务处理多种场景。以下示例展示了如何在 订阅创建 接口中为几个典型的订阅场景指定参数。
常见订阅
成功订阅授权后,立即进行扣款。随后,每隔一个周期进行扣款。
{
"...": "...",
"paymentAmount": {
"currency": "PHP",
"value": "1100"
},
"period": {
"periodCount": 1,
"periodType": "MONTH"
},
"subscriptionStartTime": "2023-08-01T08:00:00+8:00"
}
期数 | 订阅开始时间 | 支付金额 |
1
| 2023-08-01T08:00:00+8:00 | 1100PHP |
1个月 | ||
2 | 2023-09-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
3 | 2023-10-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
4 | 2023-11-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
.... |
预售
订阅授权成功后,款项会立即扣除。然而,服务将在未来某个时间生效,随后的支付会每隔一定周期扣除。
{
"...": "...",
"paymentAmount": {
"currency": "PHP",
"value": "1100"
},
"period": {
"periodCount": 1,
"periodType": "MONTH"
},
"subscriptionStartTime": "2023-08-08T08:00:00+8:00"
}
期数 | 订阅开始时间 | 支付金额 |
1 | 2023-08-01T08:00:00+8:00 | 1100PHP |
1 周 | ||
| 2023-08-08T08:00:00+8:00 | \ |
1 个月 | ||
2 | 2023-09-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
3 | 2023-10-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
4 | 2023-11-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
.... |
订阅优惠
订阅授权成功后,立即扣款,随后每月自动扣款。前两个周期的订阅费用减半,从第三个周期起订阅费用恢复正常。
{
"...": "...",
"paymentAmount": {
"currency": "PHP",
"value": "1100"
},
"period": {
"periodCount": 1,
"periodType": "MONTH"
},
"subscriptionStartTime": "2023-08-01T08:00:00+8:00",
"trials": [
{
"trialStartPeriod": 1,
"trialAmount": {
"currency": "PHP",
"value": "550"
},
"trialEndPeriod": 2
}
]
}
期数 | 订阅开始时间 | 支付金额 |
1
| 2023-08-01T08:00:00+8:00 | 550PHP |
1个月 | ||
2 | 2023-09-08T08:00:00+8:00 | 550PHP |
1个月 | ||
3 | 2023-10-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
4 | 2023-11-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
.... |
七天试用期
订阅启动后服务立即生效。然而,首次扣款将在一周后进行,之后每月扣款一次。
{
"...": "...",
"paymentAmount": {
"currency": "PHP",
"value": "1100"
},
"period": {
"periodCount": 1,
"periodType": "MONTH"
},
"subscriptionStartTime": "2023-07-08T08:00:00+8:00",
"trials": [
{
"trialStartPeriod": 1,
"trialAmount": {
"currency": "PHP",
"value": "0"
},
"trialEndPeriod": 1
}
]
}
期数 | 订阅开始时间 | 支付金额 |
| 2023-08-08T08:00:00+8:00 | \ |
1个月(不包括第一周) | ||
1 | 2023-08-08T08:00:00+8:00 | 0PHP |
1周 | ||
2 | 2023-09-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
3 | 2023-10-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
4 | 2023-11-08T08:00:00+8:00 | 1100PHP |
1个月 | ||
... |