Card Periodic Subscription - PayerMax Manage Subscription Plans
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. 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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/subscriptionCreate
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/subscriptionCreate
2.1 Standard Subscription Plan
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2025-02-26T05:00:00+00:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"subscriptionRequestId": "subscription100000000000001", // Required, merchant's unique ID for creating the subscription plan
"userId": "test10001", // Required, user ID
"language": "en", // Optional, language
"callbackUrl": "http://***.com/notifyUrl/subscription", // Required, notification URL for subscription and payment results
"subscriptionPlan": { // Required, subscription plan information
"subject": "subject", // Required, title
"description": "PMMAX First Periodic Payment", // Optional, description
"totalPeriods": 24, // Required, total number of periods
"periodRule": { // Required, payment rule
"periodUnit": "M", // Required, payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
"periodCount": 2 // Required, payment every 2 months
},
// Amount per payment period
"periodAmount": { // Required
"amount": 10.0, // Required
"currency": "USD" // Required
}
}
}
}2.2 n-day Trial Subscription Plan
Add the trialConfig configuration within subscriptionPlan.
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2025-02-26T05:00:00+00:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"subscriptionRequestId": "subscription100000000000001", // Required, merchant's unique ID for creating the subscription plan
"userId": "test10001", // Required, user ID
"language": "en", // Optional, language
"callbackUrl": "http://***.com/notifyUrl/subscription", // Required, notification URL for subscription and payment results
"subscriptionPlan": { // Required, subscription plan information
"subject": "subject", // Required, title
"description": "PMMAX First Periodic Payment", // Optional, description
"totalPeriods": 24, // Required, total number of periods
"periodRule": { // Required, payment rule
"periodUnit": "M", // Required, payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
"periodCount": 2 // Required, payment every 2 months
},
// Amount per payment period
"periodAmount": { // Required
"amount": 10.0, // Required, subscription amount
"currency": "USD" // Required, subscription currency
},
// Trial period parameters, optional. If `trialConfig` is included, the fields below are required.
"trialConfig": {
"trialAmount": { // Trial period amount
"amount": 4, // Amount must be >= 0. amount=0 indicates a free trial, amount>0 indicates a low-price trial.
"currency": "USD"
},
"trialDays": 7 // Trial days, must be greater than 0
}
}
}
}2.3 First n Periods Promotional Subscription Plan
Add the trialPeriodConfig configuration within subscriptionPlan. The following example shows a scenario with promotional pricing for the first 2 periods. The promotional payment amount is 3 USD per period, and from the 3rd period onward, the payment amount becomes 10 USD.
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2025-02-26T05:00:00+00:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"subscriptionRequestId": "subscription100000000000001", // Required, merchant's unique ID for creating the subscription plan
"userId": "test10001", // Required, user ID
"language": "en", // Optional, language
"callbackUrl": "http://***.com/notifyUrl/subscription", // Required, notification URL for subscription and payment results
"subscriptionPlan": { // Required, subscription plan information
"subject": "subject", // Required, title
"description": "PMMAX First Periodic Payment", // Optional, description
"totalPeriods": 24, // Required, total number of periods
"periodRule": { // Required, payment rule
"periodUnit": "M", // Required, payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
"periodCount": 2 // Required, payment every 2 months
},
// Non-promotional period payment amount
"periodAmount": { // Required
"amount": 10.0, // Required, subscription amount
"currency": "USD" // Required, subscription currency
},
"trialPeriodConfig": { // Optional, promotional period configuration
"trialPeriodCount": 2, // Number of promotional periods
"trialPeriodAmount": { // Promotional period payment amount
"amount": 3.0, // Promotional period payment amount. An amount of 0 indicates the promotional period is free.
"currency": "USD" // Promotional period payment currency
}
}
}
}
}2.4 n-Day Trial + First n Periods Promotional Plan
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2025-02-26T05:00:00+00:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"subscriptionRequestId": "subscription100000000000001", // Required, merchant's unique ID for creating the subscription plan
"userId": "test10001", // Required, user ID
"language": "en", // Optional, language
"callbackUrl": "http://***.com/notifyUrl/subscription", // Required, notification URL for subscription and payment results
"subscriptionPlan": { // Required, subscription plan information
"subject": "subject", // Required, title
"description": "PMMAX First Periodic Payment", // Optional, description
"totalPeriods": 24, // Required, total number of periods
"periodRule": { // Required, payment rule
"periodUnit": "M", // Required, payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
"periodCount": 2 // Required, payment every 2 months
},
// Formal period payment amount
"periodAmount": { // Required
"amount": 10.0, // Required, subscription amount
"currency": "USD" // Required, subscription currency
},
// Promotional period configuration
"trialPeriodConfig": { // Optional, promotional period configuration
"trialPeriodCount": 2, // Number of promotional periods
"trialPeriodAmount": { // Promotional period payment amount
"amount": 3.0, // Promotional period payment amount. An amount of 0 indicates the promotional period is free.
"currency": "USD" // Promotional period payment currency
}
},
// Trial days parameters, optional. If `trialConfig` is included, the fields below are required.
"trialConfig": {
"trialAmount": { // Trial period amount
"amount": 0.99, // Amount must be >= 0. amount=0 indicates a free trial, amount>0 indicates a low-price trial.
"currency": "USD"
},
"trialDays": 7 // Trial days, must be greater than 0
}
}
}
}Example of the response parameters for creating a subscription plan:
{
"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
}
}
}3. 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
totalAmountduring activation is 0; if the subscription plan type is preferential for the first n periods, the value oftotalAmountduring activation is the amount set for the preferential period; if the subscription plan type is an ordinary subscription, the value oftotalAmountduring activation is the fixed-period amount;The
currencyduring activation must be consistent with the currency in the subscription plan;The
userIdduring activation must be consistent with the userId in the subscription plan;The subscription order number
subscriptionNoreturned by PayerMax after creating the subscription plan must be sent during activation;The value of
subjectduring activation must be consistent with thesubjectin the subscription plan;
3.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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay
Example of the Request Parameters:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-17T09:05:52.194+00:00",
"appId": "bbd8d2639a7c4dfd8df7d005294390df",
"merchantNo": "020113838535952",
"data": {
"outTradeNo": "APIFOXDEV1745388079422", // The unique order number for the merchant to place an order
"subject": "The title of the subscription plan", // Keep it consistent with the subject of the subscription plan
"totalAmount": 10, // Keep it consistent with the subscription amount: 0 for [n-day trial]; the preferential period amount for [preferential for the first n periods]; the deduction amount for each period for [ordinary subscription]
"currency": "USD", // Keep it consistent with the subscription currency
"userId": "test1111", // Keep it consistent with the user number of the subscription plan
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "https://[your domain name]/[your callback URL]",
"notifyUrl": "https://[your domain name]/[your notify URL]",
"integrate": "Hosted_Checkout", // The fixed value during activation: Hosted_Checkout
"expireTime": "1800",
"subscriptionPlan": { // The subscription information
"subscriptionNo": "SUB25022603353890000002003" // The subscription order number to be activated
},
"paymentDetail": {
"paymentMethodType": "CARD", // Required during activation, the value is CARD
"mitType": "SCHEDULED", // Required, the MIT type, SCHEDULED for periodic deduction, and UNSCHEDULED for non-periodic deduction
"tokenForFutureUse": true, // Required, the value is true, generate a paymentTokenID for subsequent deduction
"merchantInitiated": false, // Required, false indicates that it is not initiated by the merchant and the user is involved; true indicates that it is initiated by the merchant and the user is not required to participate
"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"
}
}
}
}Example of the Response:
{
"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"
}
}3.2 Activating the Subscription Plan in Direct API Mode
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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay
Example of Request Parameters:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-17T09:05:52.194+00:00",
"appId": "bbd8d2639a7c4dfd8df7d005294390df",
"merchantNo": "020113838535952",
"data": {
"outTradeNo": "APIFOXDEV1745388079422", // The unique order number for the merchant to place an order
"subject": "The title of the subscription plan", // Keep it consistent with the subject of the subscription plan
"totalAmount": 10, // Keep it consistent with the subscription amount: 0 for [n-day trial]; the preferential period amount for [preferential for the first n periods]; the deduction amount for each period for [ordinary subscription]
"currency": "USD", // Keep it consistent with the subscription currency
"userId": "test1111", // Keep it consistent with the user number of the subscription plan
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "https://[your domain name]/[your callback URL]",
"notifyUrl": "https://[your domain name]/[your notify URL]",
"integrate": "Direct_Payment", // The fixed value during activation: Direct_Payment
"expireTime": "1800",
"subscriptionPlan": { // Subscription information
"subscriptionNo": "SUB25022603353890000002003" // The subscription order number to be activated
},
"terminalType": "WEB", // Terminal type, WEB, WAP or APP
"osType": "ANDROID", // Operating system type, ANDROID or IOS
"paymentDetail": {
"paymentMethodType": "CARD", // Required, the value is CARD
"mitType": "SCHEDULED", // Required, the MIT type, SCHEDULED for periodic subscription, and UNSCHEDULED for non-periodic deduction
"tokenForFutureUse": true, // Required, the value is true, generate a paymentTokenID for subsequent deduction
"merchantInitiated": false, // false means user participation is required; true means the deduction is initiated by the merchant without user participation
"cardInfo": { // Required, card information
"cardIdentifierNo": "4001563861135570",
"cardHolderFullName": "James Smith",
"cardExpirationMonth": "05",
"cardExpirationYear": "25",
"cvv": "123"
},
"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"
}
}
}
}Example of the Response:
{
"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"
}
}3.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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/applyDropinSession
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/applyDropinSession
Example of Input Parameters for the Apply Drop-in Session Request:
{
"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:
{
"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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay
Example of Request Parameters:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-17T09:05:52.194+00:00",
"appId": "bbd8d2639a7c4dfd8df7d005294390df",
"merchantNo": "020113838535952",
"data": {
"outTradeNo": "P1642410680681", // The unique order number for the merchant to place an order
"subject": "The title of the subscription plan", // Keep it consistent with the subject of the subscription plan
"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]
"currency": "USD", // Keep it consistent with the subscription currency
"userId": "test1111", // Keep it consistent with the user number of the subscription plan
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "https://[your domain name]/[your callback URL]",
"notifyUrl": "https://[your domain name]/[your notify URL]",
"integrate": "Direct_Payment", // The fixed value during activation: Direct_Payment
"expireTime": "1800",
"subscriptionPlan": { // Subscription information
"subscriptionNo": "SUB25022603353890000002003" // The subscription order number to be activated
},
"terminalType": "WEB", // Terminal type, WEB, WAP or APP
"osType": "ANDROID", // Operating system type, ANDROID or IOS
"paymentDetail": {
"paymentToken": "CPT4f200d278f3a454b9e91c81edc641e2b", // Required during activation
"sessionKey": "bdsf8982348974hhf82934bf8239424", // Required during activation
"mitType": "SCHEDULED", // Required, the MIT type, SCHEDULED for periodic deduction, and UNSCHEDULED for non-periodic deduction
"tokenForFutureUse": true, // Required, the value is true, generate a paymentTokenID for subsequent deduction
"merchantInitiated": false, // Required, false indicates that it is not initiated by the merchant and the user is involved; true indicates that it is initiated by the merchant and the user is not required to participate
"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"
}
}
}
}Example of the Response:
{
"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"
}
}4. 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.
4.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:
{
"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:
{
"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:
{
"msg": "Success",
"code": "SUCCESS"
}4.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:
{
"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, // Number of deduction periods
"paymentStatus": "SUCCESS", // Order status for this period
"periodStartTime": "2025-10-13T15:59:59+0000", // Start time of this period
"periodEndTime": "2025-12-13T15:59:59+0000", // End time of this period
"payAmount": { // Deduction amount
"amount": 10,
"currency": "USD"
},
"paymentMethodType": "CARD",
"cardOrg": "VISA",
"lastPaymentInfo": {
"tradeToken": "T20221212174800970116912", // Payment order number. The tradeToken can be used to initiate a refund.
"lastPaymentStatus": "SUCCESS", // Latest deduction result
"payTime": "2025-02-13T15:59:59+0000" // Payment time
}
}
}
}Example of Notification Parameters for Failed Deduction:
{
"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, // Number of deduction periods
"paymentStatus": "FAILED", // Order status for this period
"periodStartTime": "2022-10-13T15:59:59+0000", // Start time of this period
"periodEndTime": "2022-12-13T15:59:59+0000", // End time of this period
"payAmount": { // Payment amount
"amount": 10,
"currency": "USD"
},
"paymentMethodType": "CARD",
"cardOrg": "VISA",
"lastPaymentInfo": {
"tradeToken": "T20221212174800970116912", // Payment order number. The tradeToken can be used for refund.
"lastPaymentStatus": "FAILED", // Latest deduction result
"payTime": "2022-12-13T15:59:59+0000", // Payment time
"errorCode": "xxxx", // Error code for deduction failure
"errorMsg": "xxxx" // Reason for deduction failure
}
}
}
}Example of Merchant Response Parameters:
{
"msg": "Success",
"code": "SUCCESS"
}4.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:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "APPLY_SUCCESS",
"data": {
"channelNo": "TPC425300174064927201759000685",
"completeTime": "2025-02-27T09:41:12.267Z",
"country": "UN",
"currency": "USD",
"outTradeNo": "20250227174104451122388",
"paymentDetails": [
{
"cardInfo": {
"cardIdentifierName": "**D",
"cardIdentifierNo": "424242******0000",
"cardOrg": "VISA",
"country": "GB"
},
"paymentMethodType": "CARD",
"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:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "PAYMENT_FAILED",
"data": {
"channelNo": "TPC462800174064934688659000687",
"completeTime": "2025-02-27T09:44:00.216Z",
"country": "UN",
"currency": "USD",
"outTradeNo": "20250227174218727122389",
"paymentDetails": [
{
"cardInfo": {
"cardIdentifierName": "**D",
"cardIdentifierNo": "424242******0000",
"cardOrg": "VISA"
},
"paymentMethodType": "CARD"
}
],
"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:
{
"msg": "Success",
"code": "SUCCESS"
}5. 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:
{
"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, // Number of deduction periods
"paymentStatus": "SUCCESS", // Order status for this period
"periodStartTime": "2025-10-13T15:59:59+0000", // Start time of this period
"periodEndTime": "2025-12-13T15:59:59+0000", // End time of this period
"payAmount": { // Deduction amount
"amount": 10,
"currency": "USD"
},
"paymentMethodType": "CARD",
"cardOrg": "VISA",
"lastPaymentInfo": {
"tradeToken": "T20221212174800970116912", // Payment order number. The tradeToken can be used to initiate a refund.
"lastPaymentStatus": "SUCCESS", // Latest deduction result
"payTime": "2025-02-13T15:59:59+0000" // Payment time
}
}
}
}Example of the notification for a failed deduction:
{
"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, // Number of deduction periods
"paymentStatus": "FAILED", // Order status for this period
"periodStartTime": "2022-10-13T15:59:59+0000", // Start time of this period
"periodEndTime": "2022-12-13T15:59:59+0000", // End time of this period
"payAmount": { // Payment amount
"amount": 10,
"currency": "USD"
},
"paymentMethodType": "CARD",
"cardOrg": "VISA",
"lastPaymentInfo": {
"tradeToken": "T20221212174800970116912", // Payment order number. The tradeToken can be used for refund.
"lastPaymentStatus": "FAILED", // Latest deduction result
"payTime": "2022-12-13T15:59:59+0000", // Payment time
"errorCode": "xxxx", // Error code for deduction failure
"errorMsg": "xxxx" // Reason for deduction failure
}
}
}
}6. 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.
6.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:
{
"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"
}
}
}6.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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/subscriptionCancel
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/subscriptionCancel
Example of the request parameters for canceling the subscription plan:
{
"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:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
"userId": "10003",
"subscriptionPlan": {
"subscriptionNo": "SUB20221212174716894496912",
"subscriptionStatus": "CANCEL" // Cancelled
}
}
}6.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:
Prod Request Address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/subscriptionQuery
Test Request Address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/subscriptionQuery
Example of the request parameters for querying the subscription plan:
{
"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:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
"merchantNo": "P01010113865434",
"userId": "10003",
"subscriptionPlan": {
"subscriptionNo": "SUB20221212174716894496912",
"subscriptionStatus": "ACTIVE" // Subscription status
},
"subscriptionPaymentDetails": [
{
"subscriptionIndex": 0, // Number of deduction periods: the first period
"paymentStatus": "SUCCESS", // Order status for this period
"periodStartTime": "2025-01-13T15:59:59+0000", // Start time of this period
"periodEndTime": "2025-02-13T15:59:59+0000", // End time of this period
"payAmount": { // Payment amount
"amount": 100,
"currency": "SAR"
},
"paymentMethodType": "CARD",
"cardOrg": "VISA",
"lastPaymentInfo": {
"tradeToken": "T20221212174800970116912", // Payment order number. The tradeToken can be used for refund.
"lastPaymentStatus": "SUCCESS", // Latest deduction result
"payTime": "2025-01-12T15:59:59+0000" // Payment time
}
},
{
"subscriptionIndex": 1, // Number of deduction periods: the second period
"paymentStatus": "PENDING", // Order status for this period
"periodStartTime": "2025-02-13T15:59:59+0000", // Start time of this period
"periodEndTime": "2025-03-13T15:59:59+0000", // End time of this period
"payAmount": { // Payment amount
"amount": 100,
"currency": "SAR"
},
"paymentMethodType": "CARD",
"cardOrg": "VISA",
"lastPaymentInfo": {
"tradeToken": "T20221212174800970116912", // Payment order number. The tradeToken can be used for refund.
"lastPaymentStatus": "FAILED", // Latest deduction result
"payTime": "2025-02-12T15:59:59+0000", // Payment time
"errorCode": "xxxx", // Error code for deduction failure
"errorMsg": "xxxx" // Reason for deduction failure
}
}
]
}
}