Skip to content

GooglePay Periodic Subscription - PayerMax Manage Subscription Plans

This document describes the steps for integrating Google Pay with recurring subscription plans managed by PayerMax, including creating a subscription plan, activating a subscription plan, and receiving payment results.

1. Front-End Interaction

Note:

In Cashier Mode, when PayerMax Manage Subscription Plans, the subscription plan details will be displayed at the PayerMax cashier; however, due to Google Pay restrictions, Google Pay will only display subscription plans for the European Economic Area (EEA), and no payment button will be displayed in non-EEA regions.

2. 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.

3. 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:

3.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
            "advanceDays": 2  // Optional, specify the number of days for early deduction for each subsequent period
        }
    }
}

3.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. Order number for the merchant to create the subscription plan
        "userId": "test10001", // Required. User ID
        "language": "en", // Optional. Language
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // Required. Notification URL for subscription results and deduction results
        "subscriptionPlan": { // Required. Subscription plan information
            "subject": "subject", // Required. Title
            "description": "PMMAX Periodic First Deduction", // Optional. Description
            "totalPeriods": 24, // Required. Total number of periods
            "periodRule": { // Required. Deduction rule
                "periodUnit": "M", // Required. Deduction unit: M (Month), D (Day), W (Week), Y (Year)
                "periodCount": 2 // Required. Deduction once every 2 units (e.g., once every 2 months here)
            },
            // Deduction amount per period
            "periodAmount": { // Required
                "amount": 10.0, // Required. Subscription amount
                "currency": "USD" // Required. Subscription currency
            },
            "firstPeriodStartDate": "2025-02-28T05:00:00+00:00", // Required. The start date of the first period deduction shall be the current day. Note: firstPeriodStartDate - requestTime > 24 hours
            "advanceDays": 2  // Optional. Specifies the number of advance days for subsequent periodic deductions
        }
    }
}

3.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. Order number for the merchant to create the subscription plan
        "userId": "test10001", // Required. User ID
        "language": "en", // Optional. Language
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // Required. Notification URL for subscription results and deduction results
        "subscriptionPlan": { // Required. Subscription plan information
            "subject": "subject", // Required. Title
            "description": "PMMAX Periodic First Deduction", // Optional. Description
            "totalPeriods": 24, // Required. Total number of periods
            "periodRule": { // Required. Deduction rule
                "periodUnit": "M", // Required. Deduction unit: M (Month), D (Day), W (Week), Y (Year)
                "periodCount": 2 // Required. Deduction once every 2 units (e.g., once every 2 months here)
            },
            // Deduction amount for non-promotional periods
            "periodAmount": { // Required
                "amount": 10.0, // Required. Subscription amount
                "currency": "USD" // Required. Subscription currency
            },
            "firstPeriodStartDate": "2025-02-26T12:00:00+00:00", // Required. The start date of the first period deduction shall be the current day. Note: firstPeriodStartDate - requestTime < 24 hours
            "trialPeriodConfig": { // Optional. Promotional period configuration
                "trialPeriodCount": 2, // Number of promotional periods
                "trialPeriodAmount": { // Deduction amount for promotional periods
                    "amount": 3.0, // Deduction amount for promotional periods (0 indicates free trial)
                    "currency": "USD" // Currency for promotional period deductions
                }
            },
            "advanceDays": 2  // Optional. Specifies the number of advance days for subsequent periodic deductions
        }
    }
}

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
    }
  }
}

4. 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;

  • When activating a subscription plan, merchants must provide PayerMax with their subscription plan information subscriptionPlan and the user's subscription plan management URL mitManagementUrl. This URL allows users to access the user's subscription plan and perform other operations, such as canceling a subscription;

  • When activating a subscription plan via the API, merchants must provide PayerMax with Google's payment processing information; otherwise, activation will fail.

4.1 Activating the Subscription Plan in the Payment Cashier Mode

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 the Request Parameters:

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", // Must be consistent with the subject of the subscription plan
    "totalAmount": 10, // Must be consistent with the subscription amount: 0 for "n-day trial"; promotional period amount for "first n periods discount"; periodic deduction amount for "regular subscription"
    "country": "US",
    "currency": "USD", // Must be consistent with the subscription currency
    "userId": "test1111", // Must be 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
    },
    "mitManagementUrl": "http://your.subscription.com",
    "paymentDetail": {
      "paymentMethodType": "GOOGLEPAY", // Required for activation, value is GOOGLEPAY
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, value is true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false, // Required, false indicates not initiated by merchant (with user participation); true indicates initiated by merchant (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"
    }
}

4.2 Activating the Subscription Plan in Direct API Mode

Merchants need to obtain Google's payment elements from Google Wallet at the merchant's checkout counter. When calling PayerMax to activate the subscription plan, they need to decrypt the Google payment elements and send them to PayerMax to complete the subscription activation.

For merchants' self-integration of Google Pay, please refer to: Google Pay - Direct API Mode Integration.

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:

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", // Must be consistent with the subject of the subscription plan
        "totalAmount": 10, // Must be consistent with the subscription amount: 0 for "n-day trial"; promotional period amount for "first n periods discount"; periodic deduction amount for "regular subscription"
        "country": "US",
        "currency": "USD", // Must be consistent with the subscription currency
        "userId": "test1111", // Must be 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": "GOOGLEPAY", // Required, value is GOOGLEPAY
            "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic subscriptions, UNSCHEDULED for non-periodic direct debits
            "tokenForFutureUse": true, // Required, value is true to generate paymentTokenID for subsequent direct debits
            "merchantInitiated": false, // Required, false indicates user parameters are needed; true indicates merchant-initiated direct debit (no user participation required)
            "googlePayDetails": { // Required, Google Pay order parameters
                "authMethod": "PAN_ONLY", // Optional value: CRYPTOGRAM_3DS
                "pan": "4111111111111111", // Card number
                "expirationMonth": "12",
                "expirationYear": "2029",
                "cryptogram": "xxxxxxxxxxxx",
                "eciIndicator": "5",
                "description": "VISA 1234",
                "cardNetwork": "VISA",
                "cardHolderFullName": "zhangsan" // Required when authMethod is PAN_ONLY
            },
            "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:

Note:

When paymentDetail.googlePayDetails.authMethod=PAN_ONLY, the redirecUrl response parameter will return the 3DS verification address. When paymentDetail.googlePayDetails.authMethod=CRYPTOGRAM_3DS, the redirecUrl response parameter will not be returned.

json
// CRYPTOGRAM_3DS Response Parameters
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "SUCCESS"
    }
}
json
// PAN_ONLY Response Parameters
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // 3ds address
        "redirectUrl": "https://cashier-n.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": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "SUCCESS"
    }
}

4.3 Activating the Subscription Plan in the Front-end Component Mode

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:

Merchant client integration example:

js
// Get clientKey and sessionKey
const data = await post("applyDropinSession", {
    // Inform the server if it is a subscription payment?
    ...params
});

// Create Google Pay view
const googlepay = PMdropin.create('googlepay', {
    clientKey: data.clientKey,
    sessionKey: data.sessionKey,
    theme: yourTheme,
    payButtonStyle: data.yourPayButtonStyle,
    sandbox: data.yourFrameEnv
});

// Mount to DOM
googlepay.mount('.frame-googlepay');

// Load event: Determine if loading is successful
googlepay.on('load', (res = {}) => {
    const { code, msg } = res || {};
    if (code === "SUCCESS") {
        console.log('[merchant][load]success:', res);
    } else {
        console.log('[merchant][load]fail:', res);
    }
});

// Listen for Google Pay button click event: This event can be used to listen when the user clicks the Google Pay button after selecting a subscription plan
googlepay.on('payButtonClick', (res) => {
    // Call PayerMax createSubscription API to create a subscription plan
    createSubscription();
    
    // Disable the Google Pay button click status
    googlepay.emit('setDisabled', true);
    
    // Need to pass subscriptionPlan (subscription plan) and mitManagementUrl;
    googlepay.emit('canMakePayment', {
        // subscriptionPlan is required for periodic subscriptions
        subscriptionPlan: {
            "subject": "subject",
            "description": "PMMAX Periodic First Deduction.",
            "totalPeriods": 12,
            "periodRule": {
                "periodUnit": "M", // Deduction unit: M (Month), D (Day), W (Week), Y (Year)
                "periodCount": 1 // Deduction once per 1 unit (e.g., once a month here)
            },
            "periodAmount": { // Fixed-period deduction amount
                "amount": 404.35,
                "currency": "SAR"
            },
            "firstPeriodStartDate": "2025-02-26T12:00:00+00:00",
            "trialPeriodConfig": { // Promotional period rules
                "trialPeriodCount": 1, // Number of promotional periods
                "trialPeriodAmount": { // Deduction amount for promotional periods
                    "amount": 10,
                    "currency": "SAR"
                }
            }
        },
        mitManagementUrl: "http://www.xxx.com"
    })
    .then(res => {
        console.log('canMakePayment', res);
        const paymentToken = res?.data?.paymentToken;
        data.paymentToken = paymentToken; // Encrypted token
        
        if (paymentToken) {
            // Call PayerMax orderAndPay API to initiate payment
            orderAndPay();
        } else {
            // If the input parameters do not match the format, an error message will be thrown here
            // Example of error res: { code: "MIT_PARAMS_VALIDATION_ERROR", message: "xxx is required" }
            _payLog(JSON.stringify(res));
            googlepay.emit('setDisabled', false);
        }
    })
    .catch(err => {
        // If verification fails, a clear error will be reported. TODO
        console.log('canMakePayment catch', err);
        googlepay.emit('payFail');
        googlepay.emit('setDisabled', false);
        _payLog(JSON.stringify(err));
    });
});

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", // Must be consistent with the subscription amount: 0 for "n-day trial" and "n-day trial + first n periods discount"; promotional period amount for "first n periods discount"; periodic deduction amount for "regular subscription"; optional to leave blank
    "mitType": "SCHEDULED", // Required. Value is SCHEDULED when PayerMax manages the subscription plan
    "currency": "USD", // Required
    "country": "SA", // Optional
    "userId": "U10001", // Required. User ID
    "componentList": [ // Required. Payment methods supported by the component
      "GOOGLEPAY"
    ]
  }
}

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", // Must be consistent with the subject of the subscription plan
    "totalAmount": 10, // Must be consistent with the subscription amount: 0 for "n-day trial" and "n-day trial + first n periods discount"; promotional period amount for "first n periods discount"; periodic deduction amount for "regular subscription"
    "country": "UN",
    "currency": "USD", // Must be consistent with the subscription currency
    "userId": "test1111", // Must be 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
    },
    "mitManagementUrl": "http://www.xxx.com",
    "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 debits, UNSCHEDULED for non-periodic direct debits
      "tokenForFutureUse": true, // Required, value is true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false, // Required, false indicates not initiated by merchant (with user participation); true indicates initiated by merchant (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": {
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "status": "SUCCESS"
  }
}

5. 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.

5.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"
}

5.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 Notification Parameters for Successful Deduction:

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": "GOOGLEPAY",
            "cardOrg": "VISA",
            "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 Failed Deduction:

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": "GOOGLEPAY",
            "cardOrg": "VISA",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refund initiation
                "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"
}

5.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 the result for a successful activation request:

json
{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "APPLY_SUCCESS",
    "data": {
        "channelNo": "TPC425300174064927201759000685",
        "completeTime": "2025-02-27T09:41:12.267Z",
        "country": "US",
        "currency": "USD",
        "outTradeNo": "20250227174104451122388",
        "paymentDetails": [
            {
                "googlePayInfo": {
                    "cardIdentifierNo": "123456******1234"
                },
                "paymentMethodType": "GOOGLEPAY",
                "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 the result for a failed 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": [
            {
                "googlePayInfo": {
                    "cardIdentifierNo": "123456******1234"
                },
                "paymentMethodType": "GOOGLEPAY",
            }
        ],
        "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"
}

6. Subsequent Deductions by PayerMax

After a subscription plan is activated, PayerMax will deduct payments according to the pre-debit days specified when creating the subscription plan. If no pre-debit days are specified, PayerMax's default deduction rules will be used. For detailed deduction rules, please refer to Subscription Plan Rules. If all retry attempts for a particular period fail, PayerMax will terminate the subscription plan and notify the merchant.

Merchants can receive deduction results using the callback URL provided when creating the subscription plan. For detailed notification messages, please refer to: Result Notification API.

Example of the notification parameters for a successful deduction:

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": "GOOGLEPAY",
            "cardOrg": "VISA",
            "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 the notification for a failed deduction:

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": "GOOGLEPAY",
            "cardOrg": "VISA",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refund initiation
                "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
            }
        }
    }
}

7. 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.

7.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"
        }
    }
}

7.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", // Version
  "keyVersion": "1",
  "requestTime": "2023-02-13T06:32:50.455+00:00",
  "appId": "82ff47ea6c724a60b666e3ac0ea172dd",
  "merchantNo": "P01010113865434",
  "data": {
    "subscriptionNo": "SUB20221212174716894496912" // PayerMax subscription 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
    }
  }
}

7.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: 1st 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": "GOOGLEPAY",
                "cardOrg": "VISA",
                "lastPaymentInfo": { 
                    "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refund initiation
                    "lastPaymentStatus": "SUCCESS", // Latest deduction result
                    "payTime": "2025-01-12T15:59:59+0000" // Payment time
                }
            },
            {
                "subscriptionIndex": 1, // Deduction period: 2nd 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": "GOOGLEPAY",
                "cardOrg": "VISA",
                "lastPaymentInfo": { 
                    "tradeToken": "T20221212174800970116912", // Payment order number; tradeToken can be used for refund initiation
                    "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
                }
            }
        ]
    }
}

Released under the MIT License.