创建订阅计划

Endpoint: POST /aggregate-pay/api/gateway/subscriptionCreate
Tags: 收单/订阅计划管理

Description

PayerMax提供多种类型的订阅计划：普通订阅、n天试用、前n期优惠；可以通过创建订阅计划的入参来控制订阅计划的类型。

Parameters

Field	In	Type	Required	Constraints	Description
`Content-Type`	header	string	Yes
`sign`	header	string	Yes		签名信息请参考技术文档

Parameter Examples

Content-Type: "application/json"
sign: "FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Request Body

Content-Type: application/json

Field	Type	Required	Constraints	Description
`version`	string	Yes	maxLength: 8	接口版本当前值为：1.5
`keyVersion`	string	Yes	maxLength: 8	密钥版本当前值为：1
`requestTime`	string	Yes	maxLength: 32	请求时间，符合rfc3339规范，格式：yyyy-MM-dd'T'HH:mm:ss.SSSXXX 时间需要在当前时间两分钟内
`appId`	string	Yes	maxLength: 64	商户应用Id，PayerMax分配给商户应用的唯一标识
`merchantNo`	string	No	maxLength: 32	商户号，商户与PayerMax业务签约时生成的唯一标识
`data`	object	Yes
`data.subscriptionRequestId`	string	Yes	maxLength: 64	商户创建订阅计划的单号。
`data.userId`	string	Yes	maxLength: 64	用户id。
`data.callbackUrl`	string	Yes	maxLength: 256	订阅结果和扣款结果的通知地址。
`data.subscriptionPlan`	object	Yes		订阅计划信息。
`data.subscriptionPlan.subject`	string	Yes	maxLength: 256	标题。
`data.subscriptionPlan.description`	string	No	maxLength: 256	描述。
`data.subscriptionPlan.totalPeriods`	number	Yes		总期数。
`data.subscriptionPlan.firstPeriodStartDate` ⚠️	string	No		第一期扣款开始时间。如：2025-02-26T12:00:00+00:00
`data.subscriptionPlan.periodRule`	object	No		扣款规则。当填写prices后，periodRule不用填写，否则periodRule必填
`data.subscriptionPlan.periodRule.periodUnit`	string	Yes	maxLength: 2	按M（月），D(日)，W（周），Y（年）扣款。
`data.subscriptionPlan.periodRule.periodCount`	number	Yes		扣款频次。如periodUnit=M、periodCount=1表示每1个月扣款一次。
`data.subscriptionPlan.periodAmount`	object	No		每期扣款金额。当填写prices后，periodAmount不用填写，否则periodAmount必填
`data.subscriptionPlan.periodAmount.amount`	number	Yes		金额。
`data.subscriptionPlan.periodAmount.currency`	string	Yes	maxLength: 3	币种。
`data.subscriptionPlan.trialPeriodConfig`	object	No		优惠期配置。
`data.subscriptionPlan.trialPeriodConfig.trialPeriodCount`	number	Yes		优惠期数。
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount`	object	Yes		优惠期扣款金额。
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.amount`	number	No		金额。
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.currency`	string	No	maxLength: 3	币种。
`data.subscriptionPlan.trialConfig`	object	No		试用期配置
`data.subscriptionPlan.trialConfig.trialAmount`	object	Yes		试用期金额信息
`data.subscriptionPlan.trialConfig.trialAmount.amount`	number	Yes		试用期金额
`data.subscriptionPlan.trialConfig.trialAmount.currency`	string	Yes		试用期币种
`data.subscriptionPlan.trialConfig.trialDays`	number	Yes		试用天数
`data.subscriptionPlan.prices`	array[object]	No		价格和坐席列表
`data.subscriptionPlan.prices[].priceId`	string	Yes		价格ID
`data.subscriptionPlan.prices[].quantity`	number	Yes		坐席或数量

Example: 1

固定周期订阅

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2025-02-26T05:00:00+00:00",
  "appId": "6666c8b036a245799744912345a123456",
  "merchantNo": "010213834123456",
  "data": {
    "subscriptionRequestId": "testRequestId0001",
    "userId": "test0001",
    "callbackUrl": "http://***.com/notifyUrl/",
    "subscriptionPlan": {
      "subject": "subject",
      "description": "PMMAX周期首期扣款",
      "totalPeriods": 4,
      "periodAmount": {
        "amount": 4000,
        "currency": "KRW"
      },
      "periodRule": {
        "periodCount": 1,
        "periodUnit": "M"
      }
    }
  }
}

Example: 2

N期优惠订阅

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2025-02-26T05:00:00+00:00",
  "appId": "6666c8b036a245799744912345a123456",
  "merchantNo": "010213834123456",
  "data": {
    "subscriptionRequestId": "testRequestId0001",
    "userId": "test0001",
    "callbackUrl": "http://***.com/notifyUrl/",
    "subscriptionPlan": {
      "subject": "subject",
      "description": "PMMAX周期首期扣款。",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 404.35,
        "currency": "USD"
      },
      "trialPeriodConfig": {
        "trialPeriodAmount": {
          "amount": 10,
          "currency": "USD"
        },
        "trialPeriodCount": 2
      }
    }
  }
}

Example: 3

7天低价试用

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2025-02-26T05:00:00+00:00",
  "appId": "6666c8b036a245799744912345a123456",
  "merchantNo": "010213834123456",
  "data": {
    "subscriptionRequestId": "testRequestId0001",
    "userId": "test0001",
    "callbackUrl": "http://***.com/notifyUrl/",
    "subscriptionPlan": {
      "subject": "subject",
      "description": "PMMAX周期首期扣款。",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 404.35,
        "currency": "USD"
      },
      "trialConfig": {
        "trialAmount": {
          "amount": 4,
          "currency": "USD"
        },
        "trailDays": 7
      }
    }
  }
}

Example: 4

7天免费试用

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2025-02-26T05:00:00+00:00",
  "appId": "6666c8b036a245799744912345a123456",
  "merchantNo": "010213834123456",
  "data": {
    "subscriptionRequestId": "testRequestId0001",
    "userId": "test0001",
    "callbackUrl": "http://***.com/notifyUrl/",
    "subscriptionPlan": {
      "subject": "subject",
      "description": "PMMAX周期首期扣款。",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 10,
        "currency": "USD"
      },
      "trialConfig": {
        "trialAmount": {
          "amount": 0,
          "currency": "USD"
        },
        "trailDays": 7
      }
    }
  }
}

Responses

200

Field	Type	Required	Constraints	Description
`code`	string	Yes		返回码，’APPLY_SUCCESS’代表成功
`msg`	string	Yes		返回描述，’Success.’
`data`	object	Yes
`data.subscriptionRequestId`	string	Yes	maxLength: 64	商户创建订阅计划的单号。
`data.subscriptionPlan`	object	Yes
`data.subscriptionPlan.subscriptionNo`	string	Yes	maxLength: 64	订阅单号，PayerMax管理订阅计划时必传，商户管理订阅计划时不传
`data.subscriptionPlan.subscriptionStatus`	string	Yes	maxLength: 32	订阅计划状态。 INACTIVE：未激活 ACTIVE_FAILED：激活失败 ACTIVE：激活成功 EXPIRED：过期未激活 FINISH：订阅完成 CANCEL：订阅取消 TERMINATE：订阅终止
`data.subscriptionPlan.subject`	string	No		订阅主题，商户管理订阅计划时必传
`data.subscriptionPlan.description`	string	No		订阅描述，商户管理订阅计划时必传
`data.subscriptionPlan.totalPeriods`	string	No		总期数，商户管理订阅计划时必传
`data.subscriptionPlan.periodRule`	object	No		订阅扣款规则，商户管理订阅计划时必传
`data.subscriptionPlan.periodRule.periodUnit`	string	Yes		扣款周期：月（M），D(日)，W（周），Y（年）扣款，商户管理订阅计划时必传
`data.subscriptionPlan.periodRule.periodCount`	string	Yes		扣款频率，商户管理订阅计划时必传
`data.subscriptionPlan.periodAmount`	object	No		扣款金额，商户管理订阅计划时必传
`data.subscriptionPlan.periodAmount.amount`	number	Yes		扣款金额，商户管理订阅计划时必传
`data.subscriptionPlan.periodAmount.currency`	string	Yes		扣款币种，商户管理订阅计划时必传
`data.subscriptionPlan.trialPeriodConfig`	object	No		优惠期规则
`data.subscriptionPlan.trialPeriodConfig.trialPeriodCount`	string	Yes		优惠期数
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount`	object	Yes		优惠期扣款金额
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.amount`	number	No		优惠期扣款金额
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.currency`	string	No		优惠期扣款币种
`data.subscriptionPlan.trialConfig`	object	No		试用期参数
`data.subscriptionPlan.trialConfig.trialAmount`	object	Yes		试用期金额信息
`data.subscriptionPlan.trialConfig.trialAmount.amount`	number	Yes		试用期金额
`data.subscriptionPlan.trialConfig.trialAmount.currency`	string	Yes		试用期币种
`data.subscriptionPlan.trialConfig.trialDays`	string	Yes		试用天数
`data.subscriptionPlan.prices`	array[object]	No		价格和坐席列表
`data.subscriptionPlan.prices[].priceId`	string	Yes		价格ID
`data.subscriptionPlan.prices[].quantity`	number	Yes		坐席、数量

Response Example

json

{
  "code": "APPLY_SUCCESS",
  "msg": "Success.",
  "data": {
    "subscriptionRequestId": "testRequestId0001",
    "subscriptionPlan": {
      "subject": "subject",
      "trialConfig": {
        "trialDays": 3,
        "trialAmount": {
          "amount": 100,
          "currency": "KRW"
        }
      },
      "description": "PMMAX周期首期扣款",
      "totalPeriods": 4,
      "trialPeriodConfig": {
        "trialPeriodCount": 2,
        "trialPeriodAmount": {
          "amount": 200,
          "currency": "KRW"
        }
      },
      "periodAmount": {
        "amount": 4000,
        "currency": "KRW"
      },
      "subscriptionStatus": "INACTIVE",
      "subscriptionNo": "SUB26052902512201000064003",
      "periodRule": {
        "periodCount": 1,
        "periodUnit": "M"
      },
      "prices": [
        {
          "quantity": 1,
          "priceId": "PRICE0029177685919882013650001"
        },
        {
          "quantity": 2,
          "priceId": "PRICE0060177727844403510340001"
        }
      ]
    }
  }
}

创建订阅计划 ​

Description ​

Parameters ​

Parameter Examples ​

Request Body ​

Example: 1 ​

Example: 2 ​

Example: 3 ​

Example: 4 ​

Responses ​

200 ​

Response Example ​

创建订阅计划

Description

Parameters

Parameter Examples

Request Body

Example: 1

Example: 2

Example: 3

Example: 4

Responses

200

Response Example