变更订阅

2024-08-08 04:20

POST /v1/subscriptions/change

使用此接口来更改订阅信息，例如订阅周期规则、每个订阅周期的支付金额或其他信息。订阅信息只能更改未取消或已终止的订阅。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

subscriptionChangeRequestId String REQUIRED

商户为识别订阅变更请求而分配的专属 ID。Antom 使用此字段进行幂等性控制。

注意：对于使用相同的 subscriptionChangeRequestId 发起并达到最终状态S或F的订阅变更请求，应返回相同的结果。

更多信息：

此为幂等字段。
最大长度：64 字符

subscriptionId String REQUIRED

Antom 为识别订阅而分配的订阅编号。此参数的值与首次订阅时 支付通知（订阅） 和 订阅结果通知 返回的同名参数的值相同。

更多信息：

最大长度：64 字符

subscriptionDescription String

订阅的描述，用于显示用户消费记录和其他操作。

注意：如果要更改此信息，请指定此参数。

更多信息：

最大长度：256 字符

subscriptionStartTime Datetime

订阅生效的日期和时间。

注意：如果要指定更改后的订阅的开始时间，请提供此参数。如果留空此参数，其默认值为 Antom 接收到此请求的时间。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

subscriptionEndTime Datetime

订阅结束的日期和时间。此参数的默认值为 2099-12-31T23:59:59+08:00。

注意：如果要更改此信息，请指定此参数。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

periodRule PeriodRule object

订阅期规则，用于定义订阅的计费周期。

注意：如果要更改此信息，请指定此参数。

Show child parameters

subscriptionExpiryTime Datetime

订阅有效期。订阅过期后，订单必须终止。此参数的默认值是订阅创建请求发送后的 30 分钟。

注意：如果要更改订阅创建的过期时间，请指定此参数。指定的支付过期时间必须在订阅请求发送后 48 小时内。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

orderInfo OrderInfo object

订阅的订单信息。此字段用于不同目的：

在支付过程中，此字段主要用于 Antom 的风险控制或反洗钱。
支付完成后，此字段用于记录和报告，如采购追踪和监管报告。

注意：如果您想更改此信息，请指定此参数。

Show child parameters

paymentAmount Amount object

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

注意：如果您想更改此信息，请指定此参数。

Show child parameters

paymentAmountDifference Amount object

更改续订费用后的初次订阅费用。

注意：如果要为每个订阅期更改支付金额，请指定此参数。

Show child parameters

出参

result Result object REQUIRED

指示此接口是否成功调用。

注意：该字段不表示订阅变更的结果。Antom 会通过 订阅结果通知 接口通知订阅变更的结果。

Show child parameters

API Explorer

示例代码沙箱运行

请求

URL

请求体

响应

响应体

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	接口调用成功。
ACCESS_DENIED	F	访问被拒绝。	请咨询 Antom 技术支持以获取详细原因。
CLIENT_FORBIDDEN_ACCESS_API	F	客户端无权使用此接口。	请咨询 Antom 技术支持以获取详细原因。
INVALID_API	F	调用的接口无效或未激活。	请咨询 Antom 技术支持以解决问题。
INVALID_CLIENT_STATUS	F	客户端状态无效。	请咨询 Antom 技术支持以获取详细原因。
INVALID_SIGNATURE	F	签名验证失败。用于签署请求的私钥与 Antom Dashboard 的公钥不匹配。	检查用于签署请求的私钥是否与 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 技术支持。