Antom, leading provider of tailored payment solutions

update

POST /v1/subscriptions/update
调用此接口来更新已经创建的订阅信息,例如升级订阅,降级订阅,更新订阅描述信息,变更订阅周期类型,以及调整订阅周期等。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息,有关报文头的结构信息,请参阅:
注意:将每个参数(除数组外)的数据类型设置为字符串,即参数的值必须使用英文双引号(" ")包裹起来。例如:
  • 如果参数的数据类型为整数属性,且其值为 20,设置为 "20"。
  • 如果参数的数据类型为布尔属性,且其值为 true,设置为 "true"。

入参

subscriptionUpdateRequestId String  REQUIRED

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

更多信息:

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

subscriptionId String  REQUIRED

Antom 为识别订阅而分配的订阅编号。

更多信息:

  • 最大长度:64 字符

subscriptionDescription String  

订阅的描述,用于显示用户消费记录和其他操作。
注意:如果您需要更新订阅描述信息,请指定此参数。

更多信息:

  • 最大长度:256 字符

periodRule PeriodRule  

订阅期规则,用于定义订阅的计费周期。
注意:如果您需要变更订阅周期类型,请指定此参数。

paymentAmount Amount  

每个订阅周期向用户收取的支付金额。   
注意:如果您需要升级或者降级订阅,请指定此参数。

subscriptionEndTime Datetime  

订阅结束的日期和时间。

更多信息:

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

orderInfo OrderInfo  

订阅的订单信息。此字段用于不同目的:
  • 在支付过程中,此字段主要用于 Antom 的风险控制或反洗钱。
  • 支付完成后,此字段用于记录和报告,如采购追踪和监管报告。
注意:如果您需要升级或者降级订阅,请指定此参数。

prorationSettings ProrationSettings  

差价处理的规则与方法。
注意:当有差价处理需求时传入该参数。

nextSubscriptionDate Datetime  

由您指定的下次扣款时间。
注意:由于订阅产品会在履约时间 24 小时前开始尝试扣款,所以您指定的扣款时间至少要在当前时间的 24 小时之后。如您指定的下次扣款时间小于当前时间的 24 小时,订阅升级将失败并返回 PROCCESS_FAIL 错误码。

更多信息:

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

出参

result Result  REQUIRED

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

请求

URL
Method
POST
json
{
  "subscriptionUpdateRequestId": "amsmdsubscription_update_20250601_143228_641",
  "paymentAmount": {
    "currency": "USD",
    "value": "5000"
  },
  "periodRule": {
    "periodType": "MONTH",
    "periodCount": 1
  },
  "subscriptionDescription": "subscriptiondesc_change_20250601_143228_641",
  "subscriptionEndTime": "2026-06-13T14:32:28+08:00",
  "subscriptionId": "20221207190000000000000050000004531",
  "orderInfo": {
    "orderAmount": {
      "currency": "USD",
      "value": "5000"
    }
  },
  "prorationSettings": {
    "prorationMode": "IMMEDIATE_PAY_CUSTOM_AMOUNT",
    "customAmount": {
      "currency": "USD",
      "value": "1100"
    }
  },
  "nextSubscriptionDate": "2025-06-13T14:32:28+08:00"
}

响应

json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

结果码

结果码值结果码信息行动建议
SUCCESSS成功。
接口调用成功。
UPDATE_FORBIDDEN_DURING_PAYMENTF支付处理期间禁止更新操作。
请稍后重试。若错误依然存在,请联系 Antom 技术支持。
CURRENCY_NOT_SUPPORTF暂不支持该币种。
请联系 Antom 技术支持以获取详细原因。
PAYMENT_COUNT_EXCEED_LIMITF支付笔数已超过该支付方式规定的上限。
请联系 Antom 技术支持以以了解具体限制。
REPEAT_REQ_INCONSISTENTF金额或币种与先前请求不一致。
请确保请求中的所有字段保持一致,或使用新的 paymentRequestId 重新发起支付。
PAYMENT_IN_PROCESSF支付正在处理中。
请联系 Antom 技术支持以获取详细原因。
USER_AMOUNT_EXCEED_LIMITF支付金额超过用户限额,无法完成支付。
请使用小于或等于账户余额的金额创建新请求,或联系 Antom 技术支持。
RISK_REJECTF由于风控原因,当前交易无法完成。若用户已完成支付,该交易将进行退款。
如果用户两周内未收到退款,请联系 Antom 技术支持。
USER_NOT_EXISTF用户不存在。
请联系 Antom 技术支持以获取详细原因。
ORDER_NOT_EXISTF订单不存在。
请检查传入的 paymentId 是否正确。
ACCESS_DENIEDF访问被拒绝。
请咨询 Antom 技术支持以获取详细原因。
UNKNOWN_CLIENTF客户端未知。
请咨询 Antom 技术支持以获取详细原因。
UNKNOWN_EXCEPTIONU由于未知原因,接口调用失败。
再次调用接口解决问题。如果问题未解决,请联系 Antom 技术支持。
REQUEST_TRAFFIC_EXCEED_LIMITF请求流量超过了限制。
再次调用接口解决问题。如果问题未解决,请联系 Antom 技术支持。
PROCESS_FAILF发生了常见的业务失败。
获取 Antom 技术支持前请勿重试。
KEY_NOT_FOUNDF未找到 Antom 或商户的私钥或公钥。
检查私钥或公钥是否存在。如果不存在,请在 Antom Dashboard 中上传私钥。
OAUTH_FAILEDFOAuth 授权流程失败。
请咨询 Antom 技术支持以获取详细原因。
MERCHANT_NOT_REGISTERED F商户未注册。
请使用注册接口进行商户注册。如果调用注册接口失败,请联系 Antom 技术支持。 
INVALID_SIGNATUREF签名验证失败。用于签署请求的私钥与 Antom Dashboard 的公钥不匹配。
检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息很有用:
INVALID_APIF调用的接口无效或未激活。
请咨询 Antom 技术支持以解决问题。
CLIENT_FORBIDDEN_ACCESS_APIF客户端无权使用此接口。
请咨询 Antom 技术支持以获取详细原因。
SYSTEM_ERRORF发生系统错误。
详细原因请咨询 Antom 技术支持。 
PARAM_ILLEGALF缺少必需的参数,或者存在非法参数。例如,非数字输入,无效的日期,或者参数的长度和类型错误。
检查并验证当前接口所需的请求字段(包括头部字段和正文字段)是否正确传递并有效。