PayerMax

English

简体中文

English

简体中文

APM - Periodic Subscription Integration ​

This document introduces the relevant integration steps for periodic subscriptions, specifically including: creating a subscription plan, activating the subscription plan, and receiving subscription deduction results, etc.

1. Preparation Items ​

According to the guidance in Configuration and Signature , obtain the merchant self-service platform account, obtain the merchant appId and secret key, configure the asynchronous notification address, and configure the public key and private key.

2. Interaction Process ​

3. Subscription Plan Rules ​

  • PayerMax provides various types of subscription plans: ordinary subscription, n-day trial subscription, and preferential subscription for the first n periods; when creating a subscription plan, different types of subscription plans can be created by passing in different parameters.

  • The total duration of the subscription plan managed by PayerMax cannot exceed 3 years.

  • After creating the subscription plan, it needs to be activated before the start time of the first period's deduction. If the difference between the first period's deduction time and the subscription creation time is more than 24 hours, it needs to be activated within 24 hours. Otherwise, the subscription plan will be set to expired, and PayerMax will notify that the subscription plan has expired after it expires.

  • After activating the subscription plan, subsequent deductions will be initiated by PayerMax; for each subsequent period's deduction, the deduction will be made within 24 hours before the start of that period. If the deduction fails, the system will automatically retry within 24 hours. If the retry fails 5 times, the subscription deduction will fail, and the subscription plan will be terminated.

Subscription Plan Status Explanation

Status ValueStatus ExplanationRemarks
INACTIVENot ActivatedThe status is not activated after creating the subscription plan
ACTIVE_FAILEDActivation FailedThe status after activation fails
ACTIVEIn EffectThe status after successful activation
TERMINATESubscription TerminatedThe subscription plan will be terminated after a deduction fails in a certain period
CANCELSubscription CancelledActively cancel the subscription plan
FINISHSubscription CompletedAll periods of the subscription plan have completed the deduction
EXPIREDExpired and Not ActivatedThe subscription plan has not been activated after the start of the first period's deduction time

Subscription Deduction Status Explanation

Status ValueStatus Explanation
PENDINGDeduction in Progress
SUCCESSDeduction Successful
FAILEDDeduction Failed

4. Creating a Subscription Plan ​

The following are examples of API creation request responses for several types of subscription plans. For the complete API specification, please refer to the Create Subscription API. The request addresses for creating a subscription plan in different environments are as follows:

4.1 Ordinary Subscription Plan ​

The start time of the first period's deduction (firstPeriodStartDate) is within 24 hours after the request time (requestTime), and there is no preferential configuration (trialPeriodConfig); the input parameters for creating an ordinary subscription plan are as follows:

json
{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "2025-02-26T05:00:00+00:00",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "subscriptionRequestId": "subscription100000000000001", // Required, the order number for the merchant to create the subscription plan
        "userId": "test10001", // Required, the user ID
        "language": "en", // Not required, the language
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // Required, the notification address for the subscription result and the deduction result
        "subscriptionPlan": { // Required, the subscription plan information
            "subject": "subject", // Required, the title
            "description": "PMMAX periodic first period deduction", // Not required, the description
            "totalPeriods": 24, // Required, the total number of periods
            "periodRule": { // Required, the deduction rule
                "periodUnit": "M", // Required, deduct by month (M), day (D), week (W), or year (Y)
                "periodCount": 2 // Required, deduct once every 2 months
            },
             // The deduction amount for each period
            "periodAmount": { // Required
                "amount": 10.0, // Required
                "currency": "USD" // Required
            },
            "firstPeriodStartDate": "2025-02-26T12:00:00+00:00" // Required, the start time of the first period's deduction is the current day, and firstPeriodStartDate - requestTime < 24 hours
        }
    }
}

4.2 n-day Trial ​

The start time of the first period's deduction (firstPeriodStartDate) is after the request time (requestTime), and the difference between the two times is n days, and there is no preferential configuration (trialPeriodConfig). The following is an example of the input parameters for the subscription plan in the scenario of a 2-day trial, where the difference between firstPeriodStartDate and requestTime is 2 days; the input parameters for creating a 2-day trial subscription plan are as follows:

json
{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "2025-02-26T05:00:00+00:00",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "subscriptionRequestId": "subscription100000000000001", // Required, the order number for the merchant to create the subscription plan
        "userId": "test10001", // Required, the user ID
        "language": "en", // Not required, the language
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // Required, the notification address for the subscription result and the deduction result
        "subscriptionPlan": { // Required, the subscription plan information
            "subject": "subject", // Required, the title
            "description": "PMMAX periodic first period deduction", // Not required, the description
            "totalPeriods": 24, // Required, the total number of periods
            "periodRule": { // Required, the deduction rule
                "periodUnit": "M", // Required, deduct by month (M), day (D), week (W), or year (Y)
                "periodCount": 2 // Required, deduct once every 2 months
            },
             // The deduction amount for each period
            "periodAmount": { // Required
                "amount": 10.0, // Required, the subscription amount
                "currency": "USD" // Required, the subscription currency
            },
            "firstPeriodStartDate": "2025-02-28T05:00:00+00:00" // Required, the start time of the first period's deduction is the current day, and firstPeriodStartDate - requestTime > 24 hours
        }
    }
}

4.3 Preferential Subscription for the First n Periods ​

The start time of the first period's deduction (firstPeriodStartDate) is within 24 hours after the request time (requestTime), and it includes preferential configuration information (trialPeriodConfig). The following is an example of the input parameters for the subscription plan in the scenario of preferential treatment for the first 2 periods. The deduction amount during the preferential period is 3USD, and starting from the 3rd period, the deduction amount is 10USD; the input parameters for the preferential treatment for the first 2 periods are as follows:

json
{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "2025-02-26T05:00:00+00:00",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "subscriptionRequestId": "subscription100000000000001", // Required, the order number for the merchant to create the subscription plan
        "userId": "test10001", // Required, the user ID
        "language": "en", // Not required, the language
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // Required, the notification address for the subscription result and the deduction result
        "subscriptionPlan": { // Required, the subscription plan information
            "subject": "subject", // Required, the title
            "description": "PMMAX periodic first period deduction", // Not required, the description
            "totalPeriods": 24, // Required, the total number of periods
            "periodRule": { // Required, the deduction rule
                "periodUnit": "M", // Required, deduct by month (M), day (D), week (W), or year (Y)
                "periodCount": 2 // Required, deduct once every 2 months
            },
             // The deduction amount for the non-preferential period
            "periodAmount": { // Required
                "amount": 10.0, // Required, the subscription amount
                "currency": "USD" // Required, the subscription currency
            },
            "firstPeriodStartDate": "2025-02-26T12:00:00+00:00", // Required, the start time of the first period's deduction is the current day, and firstPeriodStartDate - requestTime < 24 hours
            "trialPeriodConfig": { // Not required, the preferential period configuration
                "trialPeriodCount": 2, // The number of preferential periods
                "trialPeriodAmount": { // The deduction amount during the preferential period
                    "amount": 3.0, // The deduction amount during the preferential period, an amount of 0 indicates that the preferential period is free
                    "currency": "USD" // The currency for the deduction during the preferential period
                }
            }
        }
    }
}

Example of the response parameters for creating a subscription plan:

json
{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "subscriptionRequestId": "subscription100000000000001", // The request order number sent by the merchant when creating the subscription plan
    "subscriptionPlan": {
        "subscriptionNo": "SUB20250202620949065212112", // The subscription order number generated by PayerMax
        "subscriptionStatus": "INACTIVE", // Not activated
    }
  }
}

5. Activating the Subscription Plan ​

After creating the subscription plan, the subscription plan is in an inactive state at this time. The user needs to complete a payment or authorization to activate the subscription plan before it can take effect. PayerMax provides 3 integration modes, namely the payment checkout mode, the API mode, and the front-end component mode, to complete the first payment or authorization.

Explanation of the activation request parameters:

  • If the subscription plan type is an n-day trial, the value of totalAmount during activation is 0; if the subscription plan type is preferential for the first n periods, the value of totalAmount during activation is the amount set for the preferential period; if the subscription plan type is an ordinary subscription, the value of totalAmount during activation is the fixed-period amount;

  • The currency during activation must be consistent with the currency in the subscription plan;

  • The userId during activation must be consistent with the userId in the subscription plan;

  • The subscription order number subscriptionNo returned by PayerMax after creating the subscription plan must be sent during activation;

  • The value of subject during activation must be consistent with the subject in the subscription plan.

5.1 Activating the Subscription Plan in the Payment Cashier Mode ​

Note:

When activating a subscription plan in cashier mode, Full cashier mode, Specify payment method, and Specify payment method + target institution are supported.

For the API document of activating the subscription plan in the payment checkout mode, please refer to the Payment Checkout - Place an Order API. The request addresses in different environments are as follows:

Example of request parameters for activating a subscription plan for the full cashier:

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Unique order number for merchant's order placement
    "subject": "Title of the Subscription Plan", // Keep consistent with the subject of the subscription plan
    "totalAmount": 10, // Keep consistent with the subscription amount: 0 for 【n-day trial】; discounted period amount for 【first n periods discount】; periodic deduction amount for 【regular subscription】
    "currency": "USD", // Keep consistent with the subscription currency
    "userId": "test1111", // Keep consistent with the user ID of the subscription plan
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Hosted_Checkout", // Fixed value for activation: Hosted_Checkout
    "expireTime": "1800",
    "subscriptionPlan": { // Subscription information
        "subscriptionNo": "SUB25022603353890000002003" // Subscription number to be activated
    },
    "paymentDetail": {
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
    }
  }
}

Example of request parameters for activating a subscription plan by specifying a payment method:

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Unique order number for merchant's order placement
    "subject": "Title of the Subscription Plan", // Keep consistent with the subject of the subscription plan
    "totalAmount": 10, // Keep consistent with the subscription amount: 0 for 【n-day trial】; discounted period amount for 【first n periods discount】; periodic deduction amount for 【regular subscription】
    "currency": "USD", // Keep consistent with the subscription currency
    "country": "KR", // Required
    "userId": "test1111", // Keep consistent with the user ID of the subscription plan
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Hosted_Checkout", // Fixed value for activation: Hosted_Checkout
    "expireTime": "1800",
    "subscriptionPlan": { // Subscription information
        "subscriptionNo": "SUB25022603353890000002003" // Subscription number to be activated
    },
    "paymentDetail": {
      "paymentMethodType": "WALLET",
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
    }
  }
}

Example of request parameters for activating a subscription plan by specifying a payment method and a target institution (wallet):

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Unique order number for merchant's order placement
    "subject": "Title of the Subscription Plan", // Keep consistent with the subject of the subscription plan
    "totalAmount": 10, // Keep consistent with the subscription amount: 0 for 【n-day trial】; discounted period amount for 【first n periods discount】; periodic deduction amount for 【regular subscription】
    "currency": "USD", // Keep consistent with the subscription currency
    "country": "KR", // Required
    "userId": "test1111", // Keep consistent with the user ID of the subscription plan
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Hosted_Checkout", // Fixed value for activation: Hosted_Checkout
    "expireTime": "1800",
    "subscriptionPlan": { // Subscription information
        "subscriptionNo": "SUB25022603353890000002003" // Subscription number to be activated
    },
    "paymentDetail": {
      "paymentMethodType": "WALLET",
      "targetOrg": "NAVERPAY",
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false, // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
      "buyerInfo": {
            "firstName": "Deborah",
            "lastName": "Swinstead",
            "email": "your@gmail.com",
            "phoneNo": "0609 031 114",
            "address": "Test Address",
            "city": "Holden Hill",
            "region": "SA",
            "zipCode": "5088",
            "clientIp": "211.52.321.225",
            "userAgent": "Mozilla/5.0 (iPad; CPU OS 18_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22E252 [FBAN/FBIOS;FBAV/513.1.0.55.90;FBBV/735017191;FBDV/iPad13,16;FBMD/iPad;FBSN/iPadOS;FBSV/18.4.1;FBSS/2;FBID/tablet;FBLC/en_GB;FBOP/5;FBRV/737247184]"
        }
    }
  }
}

Example of the Response:

json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // PayerMax cashier address
        "redirectUrl": "https://cashier-n-uat.payermax.com/static/processApiV2.html?tradeToken=T2025042306527802000033&integrate=DIRECT_API&country=UN&payRequestNo=20250423060120EP4366527897000250005&merchantId=010213834784554&merchantAppId=6666c8b036a24579974497c2f9a33333&token=902170aeaadb4621af8d9530398d0efa&orderLan=en&countryLan=en&strategyLan=LUBCO&pmaxLinkV=1",
        "outTradeNo": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "PENDING"
    }
}

5.2 Activating the Subscription Plan in Direct API Mode ​

Note:

Activate the subscription plan in API mode. You can specify the card payment method or the wallet payment method for activation.

For the API document of activating the subscription plan in API mode, please refer to the Direct API Payment API. The request addresses in different environments are as follows:

Example of Request Parameters when Specify a wallet payment method to activate the subscription plan:

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Unique order number for merchant's order placement
    "subject": "Title of the Subscription Plan", // Keep consistent with the subject of the subscription plan
    "totalAmount": 10, // Keep consistent with the subscription amount: 0 for 【n-day trial】; discounted period amount for 【first n periods discount】; periodic deduction amount for 【regular subscription】
    "currency": "USD", // Keep consistent with the subscription currency
    "country": "KR", // Required
    "userId": "test1111", // Keep consistent with the user ID of the subscription plan
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Direct_Payment", // Fixed value for activation: Direct_Payment
    "expireTime": "1800",
    "subscriptionPlan": { // Subscription information
        "subscriptionNo": "SUB25022603353890000002003" // Subscription number to be activated
    },
    "terminalType": "WEB", // Terminal type: WEB, WAP or APP
    "osType": "ANDROID", // Operating system type: ANDROID or IOS
    "paymentDetail": {
      "paymentMethodType": "WALLET", // Required, payment method
      "targetOrg": "NAVERPAY", // Required, target organization
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic subscriptions, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false // false indicates user parameters are required; true indicates merchant-initiated direct debit without user participation
    }
  }
}

Example of the Response:

json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // 3ds challenge page address
        "redirectUrl": "https://cashier-n-uat.payermax.com/static/processApiV2.html?tradeToken=T2025042306527802000033&integrate=DIRECT_API&country=UN&payRequestNo=20250423060120EP4366527897000250005&merchantId=010213834784554&merchantAppId=6666c8b036a24579974497c2f9a33333&token=902170aeaadb4621af8d9530398d0efa&orderLan=en&countryLan=en&strategyLan=LUBCO&pmaxLinkV=1",
        "outTradeNo": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "PENDING"
    }
}

5.3 Activating the Subscription Plan in the Front-end Component Mode ​

Note:

The Drop In mode does not support wallet payment methods, only card payment methods are supported to activate subscription plans.

For the integration of the front-end component, please refer to: Integration Process.

When activating the subscription plan in the front-end component mode, the merchant's server needs to call two API interfaces provided by PayerMax: Apply Drop-in Session API and Front-end Component Payment API. The request addresses of the Apply Drop-in Session interface in different environments are as follows:

Example of Input Parameters for the Apply Drop-in Session Request:

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "data": {
    "totalAmount": "10", // Keep it consistent with the subscription amount: 0 for [n-day trial] and [n-day trial + preferential for the first n periods]; the preferential period amount for [preferential for the first n periods]; the deduction amount for each period for [ordinary subscription]; it can also be left blank
    "mitType": "SCHEDULED", // Required, when PayerMax manages the subscription plan, the value is SCHEDULED
    "currency": "USD", // Required
    "country": "SA", // Not required
    "userId": "U10001", // Required, the user ID
    "componentList": [ // Required, the payment methods supported by the component
      "CARD"
    ]
  }
}

Example of the Response:

json
{
  "code": "APPLY_SUCCESS",
  "msg": "Success.",
  "data": {
    "clientKey": "37114858239eur2384237r810482390",
    "sessionKey": "bdsf8982348974hhf82934bf8239424"
  }
}

The request addresses of the front-end component payment interface in different environments are as follows:

Example of Request Parameters:

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "P1642410680681", // Unique order number for merchant's order placement
    "subject": "Title of the Subscription Plan", // Keep consistent with the subject of the subscription plan
    "totalAmount": 10, // Keep consistent with the subscription amount: 0 for 【n-day trial】 and 【n-day trial + first n periods discount】; discounted period amount for 【first n periods discount】; periodic deduction amount for 【regular subscription】
    "currency": "USD", // Keep consistent with the subscription currency
    "userId": "test1111", // Keep consistent with the user ID of the subscription plan
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Direct_Payment", // Fixed value for activation: Direct_Payment
    "expireTime": "1800",
    "subscriptionPlan": { // Subscription information
        "subscriptionNo": "SUB25022603353890000002003" // Subscription number to be activated
    },
    "terminalType": "WEB", // Terminal type: WEB, WAP or APP
    "osType": "ANDROID", // Operating system type: ANDROID or IOS
    "paymentDetail": {
      "paymentToken": "CPT4f200d278f3a454b9e91c81edc641e2b", // Required for activation
      "sessionKey": "bdsf8982348974hhf82934bf8239424", // Required for activation
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false, // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
      "buyerInfo": {
            "firstName": "Deborah",
            "lastName": "Swinstead",
            "email": "your@gmail.com",
            "phoneNo": "0609 031 114",
            "address": "Test Address",
            "city": "Holden Hill",
            "region": "SA",
            "zipCode": "5088",
            "clientIp": "211.52.321.225",
            "userAgent": "Mozilla/5.0 (iPad; CPU OS 18_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22E252 [FBAN/FBIOS;FBAV/513.1.0.55.90;FBBV/735017191;FBDV/iPad13,16;FBMD/iPad;FBSN/iPadOS;FBSV/18.4.1;FBSS/2;FBID/tablet;FBLC/en_GB;FBOP/5;FBRV/737247184]"
        }
    }
  }
}

Example of the Response:

json
{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
      // 3ds verification address
    "redirectUrl": "https://cashier-n-uat.payermax.com/index.html#/cashier/home?merchantId=020213827212251&merchantAppId=3b242b56a8b64274bcc37dac281120e3&country=ID&tradeToken=TOKEN20220117091121294138752&language=en&token=IHjqkZ8%2F%2FFcnfDPxWTvJFOrulUAKfXFUkxHJSiTdlnjnX1G6AOuTiSl6%2BN05EzxTaJkcSsSyGh5a1q%2FACwWN0sDD%2FgwY5YdWu3ghDcH2wqm%2BJIcEh0qZqo%2BQFnXp65bvkLZnY7VO7HwZGzyrpMBlPhfRCQxwBbc6lJcSYuPf%2Fe8%3D&amount=10000¤cy=IDR&frontCallbackUrl=https%3A%2F%2Fwww.payermax.com",
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "status": "PENDING"
  }
}

6. Obtaining the Activation Result of the Subscription Plan ​

Merchants can receive the subscription plan status change notification and the subscription deduction result through the callbackUrl address submitted when creating the subscription plan.

6.1 Obtaining the Subscription Plan Status Change Result ​

For the detailed notification message of the subscription plan status change notification, please refer to: Subscription Result Notification API.

Example of Notification Parameters for Successful Subscription Activation:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION",
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "ACTIVE" // Successfully activated
        }
    }
}

Example of Notification Parameters for Failed Subscription Activation:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION",
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "ACTIVE_FAILED" // Activation failed
        }
    }
}

Example of Merchant Response Parameters:

json
{
  "msg": "Success",
  "code": "SUCCESS"
}

6.2 Obtaining the Subscription Deduction Result ​

If the created subscription plan is an ordinary subscription or preferential for the first n periods, the first period's deduction will be carried out simultaneously with the activation of the subscription plan. After the deduction is completed, PayerMax will notify the merchant of the deduction result; for the notification message of the subscription deduction result, please refer to: Payment Result Notification API .

Example of wallet payment method notification parameters:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT",
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // Deduction period number
            "paymentStatus": "SUCCESS", // Current period order status
            "periodStartTime": "2025-10-13T15:59:59+0000", // Current period start time
            "periodEndTime": "2025-12-13T15:59:59+0000", // Current period end time
            "payAmount": { // Deduction amount
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used to initiate refunds
                "lastPaymentStatus": "SUCCESS", // Latest deduction result
                "payTime": "2025-02-13T15:59:59+0000" // Payment time
            }
        }
    }
}

Example of notification parameters for wallet payment method deduction failure:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT",
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // Deduction period number
            "paymentStatus": "FAILED", // Current period order status
            "periodStartTime": "2022-10-13T15:59:59+0000", // Current period start time
            "periodEndTime": "2022-12-13T15:59:59+0000", // Current period end time
            "payAmount": { // Payment amount
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refunds
                "lastPaymentStatus": "FAILED", // Latest deduction result
                "payTime": "2022-12-13T15:59:59+0000", // Payment time
                "errorCode": "xxxx", // Deduction failure code
                "errorMsg": "xxxx", // Reason for deduction failure
            }
        }
    }
}

Example of Merchant Response Parameters:

json
{
  "msg": "Success",
  "code": "SUCCESS"
}

6.3 Obtaining the Result of the Subscription Activation Request ​

Merchants can receive the result of the activation request through the notifyUrl address submitted when activating the subscription plan. For the detailed notification message, please refer to: Result Notifications API.

Example of successful result parameters for a wallet payment method activation request:

json
{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "APPLY_SUCCESS",
    "data": {
        "channelNo": "TPC425300174064927201759000685",
        "completeTime": "2025-02-27T09:41:12.267Z",
        "country": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174104451122388",
        "paymentDetails": [
            {
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY",
                "paymentTokenID": "PMTOKEN20250227071843552050007000094"
            }
        ],
        "reference": "reference",
        "status": "SUCCESS",
        "thirdChannelNo": "mtjxuvedrz58345",
        "totalAmount": 10,
        "tradeToken": "T2025022709425329000091"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118267336",
    "msg": "Success.",
    "notifyTime": "2025-02-27T09:41:12 +0000",
    "notifyType": "PAYMENT"
}

Example of result parameters for a failed wallet payment method activation request:

json
{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "PAYMENT_FAILED",
    "data": {
        "channelNo": "TPC462800174064934688659000687",
        "completeTime": "2025-02-27T09:44:00.216Z",
        "country": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174218727122389",
        "paymentDetails": [
            {
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY"
            }
        ],
        "reference": "reference",
        "status": "FAILED",
        "thirdChannelNo": "dycbhzfsmz69480",
        "totalAmount": 10,
        "tradeToken": "T2025022709462829000092"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118267336",
    "msg": "Provider failed to process.",
    "notifyTime": "2025-02-27T09:44:00 +0000",
    "notifyType": "PAYMENT"
}

Example of Merchant Response Parameters:

json
{
  "msg": "Success",
  "code": "SUCCESS"
}

7. Subsequent Deductions by PayerMax ​

After the subscription plan is activated, PayerMax will start the deduction 24 hours before the start of each period according to the subscription cycle. After each deduction is completed, PayerMax will notify the merchant of the deduction result for this period. For each deduction, PayerMax will attempt to deduct 5 times. If all attempts fail, PayerMax will terminate the subscription plan and notify the merchant. Merchants can receive the deduction result through the callbackUrl address submitted when creating the subscription plan.

Example of notification parameters for successful deduction of wallet payment:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT",
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // Deduction period number
            "paymentStatus": "SUCCESS", // Current period order status
            "periodStartTime": "2025-10-13T15:59:59+0000", // Current period start time
            "periodEndTime": "2025-12-13T15:59:59+0000", // Current period end time
            "payAmount": { // Deduction amount
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used to initiate refunds
                "lastPaymentStatus": "SUCCESS", // Latest deduction result
                "payTime": "2025-02-13T15:59:59+0000" // Payment time
            }
        }
    }
}

Example of notification parameters for wallet payment method deduction failure:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT",
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // Deduction period number
            "paymentStatus": "FAILED", // Current period order status
            "periodStartTime": "2022-10-13T15:59:59+0000", // Current period start time
            "periodEndTime": "2022-12-13T15:59:59+0000", // Current period end time
            "payAmount": { // Payment amount
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refunds
                "lastPaymentStatus": "FAILED", // Latest deduction result
                "payTime": "2022-12-13T15:59:59+0000", // Payment time
                "errorCode": "xxxx", // Deduction failure code
                "errorMsg": "xxxx", // Reason for deduction failure
            }
        }
    }
}

8. Managing the Subscription Plan ​

After the subscription plan is activated, the subscription plan can be managed, such as querying the subscription deduction result and canceling the subscription plan. After the status of the subscription plan changes, PayerMax will notify the merchant of the status of the subscription plan.

8.1 Subscription Status Change Notification ​

Merchants can receive the result of the subscription plan status change through the callbackUrl address submitted when creating the subscription plan. For the detailed notification message, please refer to: Subscription Result Notification API.

Example of the notification parameters for the termination of the subscription plan:

json
{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "TERMINATE"
        }
    }
}

8.2 Canceling the Subscription Plan ​

Merchants can cancel the subscription plan. If the latest period is in the process of deduction, they must wait until the deduction for this period succeeds or fails before canceling the subscription plan. For the detailed API message, please refer to: Cancel Subscription API. The request addresses in different environments are as follows:

Example of the request parameters for canceling the subscription plan:

json
{
  "version": "1.5", // The version is 1.5
  "keyVersion": "1",
  "requestTime": "2023-02-13T06:32:50.455+00:00",
  "appId": "82ff47ea6c724a60b666e3ac0ea172dd",
  "merchantNo": "P01010113865434",
  "data": {
    "subscriptionNo": "SUB20221212174716894496912" // PayerMax subscription order number
  }
}

Example of the response parameters for canceling the subscription plan:

json
{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
    "userId": "10003",
    "subscriptionPlan": {
        "subscriptionNo": "SUB20221212174716894496912",
        "subscriptionStatus": "CANCEL" // Cancelled
    }
  }
}

8.3 Querying the Subscription Deduction Result ​

For the API document of querying the subscription deduction result, please refer to: Query Subscription API. The request addresses in different environments are as follows:

Example of the request parameters for querying the subscription plan:

json
{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2023-02-13T06:32:50.455+00:00",
  "appId": "82ff47ea6c724a60b666e3ac0ea172dd",
  "merchantNo": "P01010113865434",
  "data": {
    "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP", // Either subscriptionNo or requestId must be provided.
    "subscriptionNo": "SUB20221212174716894496912" // Either subscriptionNo or requestId must be provided.
  }
}

Example of the response parameters for querying the subscription plan:

json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "ACTIVE" // Subscription status
        },
        "subscriptionPaymentDetails": [
            {
                "subscriptionIndex": 0, // Deduction period: First period
                "paymentStatus": "SUCCESS", // Current period order status
                "periodStartTime": "2025-01-13T15:59:59+0000", // Current period start time
                "periodEndTime": "2025-02-13T15:59:59+0000", // Current period end time
                "payAmount": { // Payment amount
                    "amount": "100",
                    "currency": "SAR"
                },
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY",
                "lastPaymentInfo": { 
                    "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refunds
                    "lastPaymentStatus": "SUCCESS", // Latest deduction result
                    "payTime": "2025-01-12T15:59:59+0000", // Payment time
                }
            },
            {
                "subscriptionIndex": 1, // Deduction period: Second period
                "paymentStatus": "PENDING", // Current period order status
                "periodStartTime": "2025-02-13T15:59:59+0000", // Current period start time
                "periodEndTime": "2025-03-13T15:59:59+0000", // Current period end time
                "payAmount": { // Payment amount
                    "amount": "100",
                    "currency": "SAR"
                },
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY",
                "lastPaymentInfo": { 
                    "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refunds
                    "lastPaymentStatus": "FAILED", // Latest deduction result
                    "payTime": "2025-02-12T15:59:59+0000", // Payment time
                    "errorCode": "xxxx", // Deduction failure code
                    "errorMsg": "xxxx", // Reason for deduction failure
                }
            }
        ]
    }
}

9. Merchants Manage Subscriptions by Themselves ​

PayerMax also supports merchants to manage subscription plans by themselves. Merchants design subscription product forms according to their own scenarios, and PayerMax only accepts merchant deduction requests. The specific integration interaction process is the same as Auto Debit Integration.

Released under the MIT License.

Copyright © 2023-present PayerMax