Create Subscription

Endpoint: POST /aggregate-pay/api/gateway/subscriptionCreate
Tags: Collection Service/Subscription Management

Description

PayerMax offers various types of subscription plans: regular subscriptions, n-day trials, and n-period promotions. The type of subscription plan can be controlled through the parameters when creating the subscription plan.

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		API version. Current value: 1.5
`keyVersion`	string	Yes		Signature Algorithm Version, Current value: 1
`requestTime`	string	Yes		Request time, compliant with rfc3339 specification, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX The time must be within two minutes of the current time
`appId`	string	Yes		Merchant AppId，The unique identifier assigned to the merchant app by PayerMax
`merchantNo`	string	No	maxLength: 32	Merchant Id, the unique identifier generated when the merchant signs the contract with PayerMax
`data`	object	Yes
`data.subscriptionRequestId`	string	Yes	maxLength: 64	Merchant's unique request ID for creating the subscription plan.
`data.userId`	string	Yes	maxLength: 64	User ID.
`data.callbackUrl`	string	Yes	maxLength: 256	Notification URL for subscription and payment deduction results.
`data.subscriptionPlan`	object	Yes		Subscription plan details.
`data.subscriptionPlan.subject`	string	Yes	maxLength: 256	Subscription title.
`data.subscriptionPlan.description`	string	No	maxLength: 256	Subscription description.
`data.subscriptionPlan.totalPeriods`	number	Yes		Total number of subscription periods.
`data.subscriptionPlan.firstPeriodStartDate` ⚠️	string	No		First payment date. Format: 2025-02-26T12:00:00+00:00
`data.subscriptionPlan.periodRule`	object	No		Subscription rules. When the prices is empty, periodRule is required, when the prices is not empty, periodRule must be null.
`data.subscriptionPlan.periodRule.periodUnit`	string	Yes	maxLength: 2	Subscription frequency unit: M (Month), D (Day), W (Week), Y (Year).
`data.subscriptionPlan.periodRule.periodCount`	number	Yes		Subscription frequency. Example: periodUnit=M and periodCount=1 indicates monthly payment.
`data.subscriptionPlan.periodAmount`	object	No		Recurring payment amount per period. When the prices is empty, periodAmount is required, when the prices is not empty, periodAmount must be null.
`data.subscriptionPlan.periodAmount.amount`	number	Yes		Payment amount.
`data.subscriptionPlan.periodAmount.currency`	string	Yes	maxLength: 3	Currency code.
`data.subscriptionPlan.trialPeriodConfig`	object	No		Trial period configuration.
`data.subscriptionPlan.trialPeriodConfig.trialPeriodCount`	number	No		Number of trial periods.
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount`	object	No		Trial period payment amount.
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.amount`	number	No		Trial amount.
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.currency`	string	No	maxLength: 3	Currency code.
`data.subscriptionPlan.trialConfig`	object	No		Subscription trial for n days information
`data.subscriptionPlan.trialConfig.trialAmount`	object	Yes		Trial fee information
`data.subscriptionPlan.trialConfig.trialAmount.amount`	number	Yes		Trial fee
`data.subscriptionPlan.trialConfig.trialAmount.currency`	string	Yes		Trial currency
`data.subscriptionPlan.trialConfig.trialDays`	number	Yes		Trial days
`data.subscriptionPlan.prices`	array[object]	Yes		prices info
`data.subscriptionPlan.prices[].priceId`	string	Yes		The Price ID.
`data.subscriptionPlan.prices[].quantity`	number	Yes		The Price quantity.

Example: 1

Regular subscription

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": "Regular subscription description.",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 404.35,
        "currency": "USD"
      }
    }
  }
}

Example: 2

N-days trial and N-periods promotion

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": "description.",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 404.35,
        "currency": "USD"
      },
      "trialPeriodConfig": {
        "trialPeriodAmount": {
          "amount": 10,
          "currency": "USD"
        },
        "trialPeriodCount": 2
      },
      "trialConfig": {
        "trialAmount": {
          "amount": 10,
          "currency": "USD"
        },
        "trialDays": 7
      }
    }
  }
}

Example: 3

N-period promotions

json

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

Example: 4

N-days trial

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": "description.",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 404.35,
        "currency": "USD"
      },
      "trialConfig": {
        "trialAmount": {
          "amount": 10,
          "currency": "USD"
        },
        "trialDays": 7
      }
    }
  }
}

Responses

200

Field	Type	Required	Constraints	Description
`code`	string	Yes		Return code, ‘APPLY_SUCCESS’ means success
`msg`	string	Yes		Return message, ‘Success.’
`data`	object	Yes
`data.subscriptionRequestId`	string	Yes	maxLength: 64	Merchant's unique request ID for creating the subscription plan.
`data.subscriptionPlan`	object	Yes
`data.subscriptionPlan.subscriptionNo`	string	Yes		PayerMax subscription plan management order number
`data.subscriptionPlan.subscriptionStatus`	string	Yes	maxLength: 32	Subscription plan status. INACTIVE: Not activated ACTIVE_FAILED: Activation failed ACTIVE: Activation is successful EXPIRED: Expired and not activated FINISH: Subscription Completed CANCEL: Subscription Cancel TERMINATE: Subscription termination
`data.subscriptionPlan.subject`	string	No		subscription topic, required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.description`	string	No		subscription description, required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.totalPeriods`	string	No		total subscription periods. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.periodRule`	object	No		subscription rules
`data.subscriptionPlan.periodRule.periodUnit`	string	Yes		subscription deduction cycle, deduct by month (M), day (D), week (W), year (Y). Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.periodRule.periodCount`	string	Yes		subscription deduction frequency. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.periodAmount`	object	No		fixed period deduction amount. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.periodAmount.amount`	number	Yes		fixed period deduction amount. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.periodAmount.currency`	string	Yes		fixed period deduction currency. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.trialPeriodConfig`	object	No		discount period rules
`data.subscriptionPlan.trialPeriodConfig.trialPeriodCount`	string	Yes		discount period count.
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount`	object	Yes		discount deduct amount.
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.amount`	number	No		discount deduct amount. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.currency`	string	No		discount deduct currency. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
`data.subscriptionPlan.trialConfig`	object	No		Subscription trial for n days information
`data.subscriptionPlan.trialConfig.trialAmount`	object	Yes		Trial fee information
`data.subscriptionPlan.trialConfig.trialAmount.amount`	number	Yes		Trial fee
`data.subscriptionPlan.trialConfig.trialAmount.currency`	string	Yes		Trial currency
`data.subscriptionPlan.trialConfig.trialDays`	number	Yes		Trial days
`data.subscriptionPlan.prices`	array[object]	No		The price info.
`data.subscriptionPlan.prices[].priceID`	string	Yes		The price ID.
`data.subscriptionPlan.prices[].quantity`	number	Yes		The price quantity.

Response Example

json

{
  "code": "APPLY_SUCCESS",
  "msg": "Success.",
  "data": {
    "subscriptionRequestId": "testRequestId0001",
    "subscriptionPlan": {
      "subscriptionStatus": "INACTIVE",
      "subscriptionNo": "SUB26052902512201000064003",
      "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"
      },
      "periodRule": {
        "periodCount": 1,
        "periodUnit": "M"
      },
      "prices": [
        {
          "quantity": 1,
          "priceId": "PRICE0029177685919882013650001"
        },
        {
          "quantity": 2,
          "priceId": "PRICE0060177727844403510340001"
        }
      ]
    }
  }
}

Create Subscription ​

Description ​

Parameters ​

Parameter Examples ​

Request Body ​

Example: 1 ​

Example: 2 ​

Example: 3 ​

Example: 4 ​

Responses ​

200 ​

Response Example ​

Create Subscription

Description

Parameters

Parameter Examples

Request Body

Example: 1

Example: 2

Example: 3

Example: 4

Responses

200

Response Example