Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

订阅激活

在订阅支付流程中,买家选择一个套餐和支付方式,经过授权确认信息,然后被重定向到授权结果页面。在集成时,您需要创建展示支付方式的订阅激活页面。该页面通过授权 URL将用户重定向到结账页面,然后基于订阅状态处理支付回调将用户重定向到相应界面。

用户体验

订阅支付的用户体验如下:

image.png

图1. 订阅支付的用户体验

各部分的功能如下:

  1. 订阅激活页面:买家选择订阅计划和支付方式,并确认激活。此时生成一个订阅订单,并进入订阅授权流程。
  2. 授权流程:将用户重定向到支付方法授权页面,买家在此确认信息,验证身份并完成授权。随后买家会被重定向到 Antom 中间页面。
  3. 授权结果页面:授权完成后,买家会自动重定向到授权结果页面。

在集成过程中,您需要聚焦于创建订阅激活页面。此页面用于以下目的:

  • 展示可用支付方式:支付方式根据支付金额和买家所在地区等支付信息进行排序。
  • 重定向用户授权:使用 Antom 提供的授权 URL将买家重定向到授权页面。
  • 接收支付回调(可选):通过监控页面调用或使用生命周期函数接收支付回调,随后可以根据订阅状态将买家重定向到订阅结果页面。

集成步骤

通过以下步骤开始集成:

  1. 获取并显示可用支付方式。
  2. 调用授权流程。

步骤1:获取并展示可用支付方式

获取支付方式的名称和标识,并在页面上显示可用的支付方式。

获取支付方式的名称和支付方式logo

请联系 Antom 技术支持以获取对应于每种支付方式的名称和logo。

过滤支付方式

在展示所有支付方式之前,建议取消展示或禁用正在维护的支付方式,以避免订阅失败。您可以联系 Antom 技术支持查询支付方式的维护状态。

展示支付方式

对于 Alipay+ 支付方式,您必须展示 Alipay+ 合作伙伴的logo。您可以选择以下样式之一,确保每个支付方式的名称和标识使用正确:

image

步骤2:发起授权流程

您需要先获取授权 URL,然后发起授权流程。

拦截无效订单

为了避免重复订阅或订阅过期,建议您在买家点击或触摸 立即订阅 后,验证订单的状态和有效期。

image

为了拦截过期的订阅授权,您可以通过指定 paymentExpiryTime 参数来设定订阅的过期时间。如果买方在订阅过期时间后进行授权,将会报告错误。设置订阅的过期时间还可以避免买方在被重定向到支付方式页面后,长时间延迟授权所导致的重复订阅情况。

服务器的时间偏差也可能导致重复的订阅授权。建议在接收有关订阅和支付状态的异步通知时,检查状态。如果出现重复授权情况,请使用取消订阅 接口取消订单。

获取授权URL

当买家点击或轻触 立即订阅 后,您的客户端会向服务器请求授权URL,随后您的服务器调用 订阅创建 获取授权 URL 并将其返回给客户端。在请求完成并获得授权 URL 之前,请禁用 立即订阅 按钮,以防用户触发重复操作。

image

在请求授权 URL 的过程中,由于网络问题,客户端和服务器端的请求都可能失败。建议在客户端的 HTTP 请求中设置超时,以防止买家等待时间过长。如果无法获取授权 URL,需要允许买家重新发起订阅授权。

订阅授权请求中的关键字段如下。

字段名称

描述

subscriptionRequestId

商户为识别订阅请求分配的专属 ID。

env

根据客户端类型指定 terminalType

  • Web:将 terminalType 设置为 WEB
  • WAP:将 terminalType 设置为 WAP,并指定 osType
  • App:将 terminalType 设置为 APP,并指定 osType

subscriptionRedirectUrl

用户授权订阅后重定向到的商户页面链接。

  • Web:传入 H5 链接。
  • WAP:传入 H5 链接。
  • App:传入深度链接链接。

subscriptionNotifyUrl

用于接收订阅结果通知的链接。 请指定为 HTTPS 链接。

paymentNotifyUrl

用于接收每个订阅周期支付结果通知的链接。请指定为 HTTPS 链接。

进行授权流程

授权流程的用户体验如下:

image.png

image.png

重定向到结果页面

订阅创建 接口中,可以通过 subscriptionRedirectUrl 参数设置授权 URL。 根据以下 terminalType 的值,建议传递 H5 URL或deep link

terminalType

subscriptionRedirectUrl

WEB

传递一个 H5 URL。

WAP

传递一个 H5 URL。

APP

传递一个deep link。

当买家完成授权后,他们首先会被重定向到 Antom 的中间页面,然后再被重定向到商户的页面。

image

授权完成后,Antom 会发送一个异步通知到 subscriptionNotifyUrl ,通知您授权是否成功。

当您收到来自 Antom 的通知时,您必须按照 订阅结果通知 中的代码示例进行响应。如果您没有向 Antom 返回响应,或者由于网络问题 Antom 未收到响应,Antom 将在 24 小时内自动重试发送异步通知,最多八次,直到收到正确的响应。发送间隔如下:0 秒,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时和 15 小时。

订阅场景示例

请特别关注与订阅周期和订阅开始时间相关的参数。这些参数定义了为买家提供的订阅套餐。

关键参数

您可以通过在 订阅创建 接口中配置以下参数来管理订阅周期和定期支付逻辑:

字段名称

描述

subscriptionStartTime

订阅开始的时间。您可以设置为过去的时间,但不能早于订阅请求发起前的一个周期。

subscriptionEndTime

订阅结束的时间。

paymentAmount

每个订阅周期向用户收取的支付金额。

periodRule.periodType

订阅周期类型。有效值为:YEAR ,MONTH ,WEEK ,或 DAY

periodRule.periodCount

订阅周期内的周期类型数量。例如,如果 periodType 的值为 MONTH,而 periodCount 的值为 3,这意味着订阅周期为三个月。

trials.trialStartPeriod

试用期的开始订阅周期。

trials.trialAmount

每个订阅试用期的折扣金额。

trials.trialEndPeriod

试用期的结束订阅周期。如果此参数留空,默认值将与 trials.trialStartPeriod 相同。

参数 subscriptionStartTime 设置了订阅支付的起始时间,而 periodRule 参数定义了订阅的计费间隔,从而划定了计费周期。

假设 subscriptionStartTime 2023-08-01T08:00:00+8:00periodRule.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 指定。

注意:关于扣款失败的情况:

  • 如果首次扣款失败:订阅授权将失败,订阅不会生效。
  • 如果在后续支付周期中扣款失败:
    • 订阅状态不会改变,订阅保持有效。
    • 对于特定期间的失败扣款,您不能重试扣款。但是,当前期间的扣款失败不会影响后续期间的扣款。

示例

通过指定相应的参数,您可以使用订阅支付服务处理多种场景。以下示例展示了如何在 订阅创建 接口中为几个典型的订阅场景指定参数。

常见订阅

成功订阅授权后,立即进行扣款。随后,每隔一个周期进行扣款。

copy
{
    "...": "...",
    "paymentAmount": {
        "currency": "PHP",
        "value": "1100"
    },
    "period": {
        "periodCount": 1,
        "periodType": "MONTH"
    },
    "subscriptionStartTime": "2023-08-01T08:00:00+8:00"
}

期数

订阅开始时间

支付金额

1

subscriptionStartTime

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个月

....

预售

订阅授权成功后,款项会立即扣除。然而,服务将在未来某个时间生效,随后的支付会每隔一定周期扣除。

copy
{
    "...": "...",
    "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 周

subscriptionStartTime

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个月

....

订阅优惠

订阅授权成功后,立即扣款,随后每月自动扣款。前两个周期的订阅费用减半,从第三个周期起订阅费用恢复正常。

copy
{
    "...": "...",
    "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

subscriptionStartTime

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个月

....

七天试用期

订阅启动后服务立即生效。然而,首次扣款将在一周后进行,之后每月扣款一次。

copy
{
    "...": "...",
    "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
        }
    ]
}

期数

订阅开始时间

支付金额

subscriptionStartTime

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个月

...