订阅创建
入参
subscriptionRequestId String REQUIRED
商户为识别订阅请求分配的专属 ID。Antom 使用此字段进行幂等性控制。
注意：对于具有相同 subscriptionRequestId 的订阅请求，如果达到最终状态
S或F，请求将返回相同的结果。
更多信息：
- 此为幂等字段。
- 最大长度：64 字符
subscriptionDescription String REQUIRED
订阅的描述，用于显示用户消费记录和其他操作。
更多信息：
- 最大长度：256 字符
subscriptionRedirectUrl URL REQUIRED
用户授权订阅后被重定向到的商户页面链接。
更多信息：
- 最大长度：2048 字符
subscriptionStartTime Datetime REQUIRED
订阅生效的日期和时间。
更多信息：
- 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。
subscriptionEndTime Datetime
订阅结束的日期和时间。
注意：当您需要指定订阅的结束时间时，设置此参数。
更多信息：
- 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。
periodRule PeriodRule REQUIRED
订阅周期规则，用于定义订阅的计费周期。
subscriptionExpiryTime Datetime
创建的订阅过期的具体日期和时间。订阅过期后，订单必须终止。此参数的默认值为订阅创建请求发送后 30 分钟。
注意：如果您希望指定订阅创建的过期时间，设置此参数。指定的支付过期时间必须在订阅请求发送后 48 小时内。
更多信息：
- 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。
paymentMethod PaymentMethod REQUIRED
商户或收单机构用来收款的支付方法。
subscriptionNotificationUrl URL REQUIRED
用于接收订阅结果通知的链接。
您也可以在 Antom Dashboard 中配置订阅通知链接。如果在本接口和 Antom Dashboard 中都指定了此链接，接口中配置的链接优先。
注意：Antom Dashboard 中只能配置一个订阅通知链接。
更多信息：
- 最大长度：2048 字符
paymentNotificationUrl URL REQUIRED
用于接收每个订阅周期支付结果通知的链接。
您也可以在 Antom Dashboard 中配置订阅通知链接。如果在此接口和 Antom Dashboard 中都指定了此链接，接口中配置的链接优先。
注意：您只能在 Antom Dashboard 中配置一个订阅通知链接。
更多信息：
- 最大长度：2048 字符
orderInfo OrderInfo REQUIRED
订阅的订单信息。 此字段用于不同目的：
- 在支付过程中，此字段主要用于 Antom 的风险控制或反洗钱。
- 支付完成后，此字段用于记录和报告，如采购追踪和监管报告。
paymentAmount Amount REQUIRED
每个订阅周期向用户收取的支付金额。
settlementStrategy SettlementStrategy REQUIRED
支付请求的结算策略。
env Env REQUIRED
下单的环境信息，如设备信息。
trials Array<Trial>
订阅的试用信息列表。
如果订阅包含任何试用期，请指定此参数。
更多信息：
- 最多可包含元素个数：无限
出参
result Result REQUIRED
指示此接口是否调用成功。如果接口调用成功，将返回订阅授权链接。
schemeUrl URL
在 Android 或 iOS 系统中，应用安装成功时，跳转应用的 URL scheme。
注意：当 result.resultCode 的值为
S时，需要返回 schemeUrl、applinkUrl 或 normalUrl 中的至少一个。
更多信息：
- 最大长度：2048 字符
applinkUrl URL
应用安装成功时，跳转应用的链接，安装失败则跳转至 WAP 页面。对于 Android，该链接是 Native App Link。对于 iOS，该链接是 Universal Link。
注意：当 result.resultCode 的值为
S时，需要返回 schemeUrl、applinkUrl 和 normalUrl 中的至少一个。
更多信息：
- 最大长度：2048 字符
normalUrl URL
用于在默认浏览器或嵌入式 WebView 中重定向用户到 WAP 或网页的链接。
注意：当 result.resultCode 的值为
S时，需要返回 schemeUrl、applinkUrl 和 normalUrl 中的至少一个。
更多信息：
- 最大长度：2048 字符
appIdentifier URL
Android 包名，用于 Android 应用打开收银台页面。
注意：当 result.resultCode 为
S且 terminalType 为APP或WAP时，返回此字段。
更多信息：
- 最大长度：128 字符
请求
响应
结果处理逻辑
对于不同的请求结果，需要执行不同的操作。详细信息如下：
- 如果 result.resultStatus 的值为
S，响应中的 schemeUrl、applinkUr 或 normalUrl 字段成功返回了授权链接。您可以将用户重定向到这个链接以授权订阅支付。 - 如果 result.resultStatus 的值为
U，接口调用状态未知。您可以再次调用此接口以重试过程。 - 如果 result.resultStatus 的值为
F，未能返回授权链接。通常，这是由于系统缺陷或系统故障导致的。检查错误代码并采取相应措施，或联系 Antom 技术支持。
结果码
| 结果码 | 值 | 结果码信息 | 行动建议 |
|---|---|---|---|
| SUCCESS | S | 成功 | 接口调用成功。从响应中获取 schemeUrl、applinkUrl 或 normalUrl。 |
| ACCESS_DENIED | F | 访问被拒绝。 | 请咨询 Antom 技术支持以获取详细原因。 |
| CLIENT_FORBIDDEN_ACCESS_API | F | 访问被拒绝。 | 请咨询 Antom 技术支持以获取详细原因。 |
| INVALID_API | F | 调用的接口无效或未激活。 | 请咨询 Antom 技术支持以解决问题。 |
| INVALID_CLIENT_STATUS | F | 客户端状态无效。 | 请联系 Antom 技术支持以获取详细原因。 |
| INVALID_SIGNATURE | F | 签名验证失败。用于签署请求的私钥与Antom Dashboard的公钥不匹配。 | |
| KEY_NOT_FOUND | F | 未找到Antom或商户的私钥或公钥。 | 检查私钥或公钥是否存在。如果不存在，请在 Antom Dashboard 中上传私钥。 |
| MERCHANT_NOT_REGISTERED | F | 商户未注册。 | 请使用注册接口进行商户注册。如果调用注册接口失败，请联系 Antom 技术支持。 |
| OAUTH_FAILED | F | OAuth授权流程失败。 | 请咨询 Antom 技术支持以获取详细原因。 |
| PARAM_ILLEGAL | F | 缺少必需的参数，或者存在非法参数。例如，非数字输入，无效的日期，或者参数的长度和类型错误。 |
检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。 |
| PAYMENT_NOT_QUALIFIED | F | 商户因未注册、未签订自动扣款协议或被禁止支付，不具备支付资格。 | 详细原因请咨询 Antom 技术支持。 |
| PROCESS_FAIL | F | 发生了常见的业务失败。 | 获取 Antom 技术支持前请勿重试。 |
| RISK_REJECT | F | 由于风险控制，交易无法进一步处理。如果用户已为交易付款，交易将被退款。 | 如果用户在两周内未收到退款，请联系 Antom 技术支持。 |
| UNKNOWN_CLIENT | F | 客户端未知。 | 请联系 Antom 技术支持以获取详细原因。 |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | 请求流量超过了限制。 | 再次调用接口解决问题。如果问题仍未解决，请联系 Antom 技术支持。 |
| UNKNOWN_EXCEPTION | U | 由于未知原因，接口调用失败。 | 再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。 |
| REPEAT_REQ_INCONSISTENT | F | 金额或币种与先前请求不同。 | 确保请求中的所有字段相同，或使用新的 subscriptionRequestId 重新启动支付。 |