订阅创建
入参
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 重新启动支付。 |