GooglePay Periodic Subscription - Merchants Manage Subscription Plans
This document describes the steps for integrating Google Pay with recurring subscription plans managed by merchants, specifically including: binding the payment method, obtaining the result of binding the payment method, initiating the direct debit, and obtaining the direct debit result, etc.
1. Front-End Interaction
Note:
In Cashier Mode, when Merchant Manages Subscription Plans, subscription plan details will not be displayed on the PayerMax cashier; and due to Google Pay restrictions, Google Pay will only display subscription plans for the European Economic Area (EEA). 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. Binding the Payment Method
Core parameter description:
totalAmount: The transaction amount, which supports passing 0 or an amount greater than 0;paymentDetail.mitType: The auto debit type,SCHEDULEDindicates periodic subscription, andUNSCHEDULEDindicates non-periodic auto debit;paymentDetail.tokenForFutureUse:true/false, whether to generate a token for subsequent direct debits; when binding the payment method for the first time, this value should be passed astrue;paymentDetail.merchantInitiated:true/false, whether it is a transaction initiated by the merchant; when binding the payment method for the first time, the user needs to participate in completing the authentication or authorization, and the value should be passed asfalse.mitManagementUrl: The address where merchants manage subscription plans. Users can access this address to manage subscription plans, such as canceling a subscription;subscriptionPlan: Subscription plan information.
3.1 Binding the Payment Method Using the PayerMax Payment Cashier
For the interface document of binding the payment method in the Checkout mode, please refer to the Checkout - Place Order API. The request addresses for 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
When the transaction amount is greater than 0 yuan, the request parameter example is as follows:
{
"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 direct debit order placement
"subject": "Direct Debit Title", // Title
"totalAmount": 10, // Direct debit amount
"country": "US",
"currency": "USD", // Direct debit currency
"userId": "test1111", // User ID
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "http://www.frontCallbackUrl.com",
"notifyUrl": "http://www.notifyUrl.com",
"integrate": "Hosted_Checkout", // Fixed value: Hosted_Checkout
"expireTime": "1800",
"subscriptionPlan": { // Subscription information
"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 month
},
"periodAmount": { // Fixed-period direct debit amount
"amount": 20,
"currency": "USD"
},
"firstPeriodStartDate": "2025-08-26T12:00:00+00:00",
"trialPeriodConfig": { // Promotional period rules
"trialPeriodCount": 1, // Number of promotional periods
"trialPeriodAmount": { // Direct debit amount for promotional periods
"amount": 10,
"currency": "USD"
}
}
},
"mitManagementUrl": "http://your.subscription.com",
"paymentDetail": {
"paymentMethodType": "GOOGLEPAY", // Required, value is GOOGLEPAY
"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]"
}
}
}
}When the transaction amount is 0, the request parameter example is as follows:
{
"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": "Direct Debit Title", // Title
"totalAmount": 0, // Direct debit amount
"currency": "USD", // Direct debit currency
"userId": "test1111", // User ID
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "http://www.frontCallbackUrl.com",
"notifyUrl": "http://www.notifyUrl.com",
"integrate": "Hosted_Checkout", // Fixed value: Hosted_Checkout
"expireTime": "1800",
"subscriptionPlan": { // Required. Subscription information
"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 month
},
"periodAmount": { // Fixed-period direct debit amount
"amount": 20,
"currency": "USD"
},
"firstPeriodStartDate": "2025-08-26T12:00:00+00:00",
"trialPeriodConfig": { // Promotional period rules
"trialPeriodCount": 1, // Number of promotional periods
"trialPeriodAmount": { // Direct debit amount for promotional periods
"amount": 10,
"currency": "USD"
}
}
},
"mitManagementUrl": "http://your.subscription.com", // Required
"paymentDetail": {
"paymentMethodType": "GOOGLEPAY", // Required, value is GOOGLEPAY
"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:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
// PayerMax Checkout 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 Binding the Payment Method in Direct API Mode
Merchants need to obtain payment elements from Google at the merchant's checkout counter. When calling PayerMax to bind the payment method, they need to decrypt the payment elements and send them to PayerMax to complete the binding.
For merchants' self-integration of Google Pay, please refer to: Google Pay - Direct API Mode Integration.
For the API document of binding the payment method in API mode, please refer to the Direct API Payment API. The request addresses for 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", // Unique order number for merchant's order placement
"subject": "Direct Debit Title", // Title
"totalAmount": 10, // Direct debit amount
"currency": "USD", // Direct debit currency
"userId": "test1111", // User ID
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "http://www.frontCallbackUrl.com",
"notifyUrl": "http://www.notifyUrl.com",
"integrate": "Direct_Payment", // Fixed value: Direct_Payment
"expireTime": "1800",
"terminalType": "WEB", // Terminal type: WEB, WAP or APP
"osType": "ANDROID", // Operating system type: ANDROID or IOS
"subscriptionPlan": { // Optional. Subscription information
"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 month
},
"periodAmount": { // Fixed-period direct debit amount
"amount": 20,
"currency": "USD"
},
"firstPeriodStartDate": "2025-08-26T12:00:00+00:00",
"trialPeriodConfig": { // Promotional period rules
"trialPeriodCount": 1, // Number of promotional periods
"trialPeriodAmount": { // Direct debit amount for promotional periods
"amount": 10,
"currency": "USD"
}
}
},
"mitManagementUrl": "http://your.subscription.com", // Optional
"paymentDetail": {
"paymentMethodType": "GOOGLEPAY", // Required, value is GOOGLEPAY
"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, // false indicates user parameters are required; 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.
// CRYPTOGRAM_3DS Response Parameters
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"outTradeNo": "APIFOXDEV1745388079422",
"tradeToken": "T2025042306527802000033",
"status": "SUCCESS"
}
}// 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"
}
}3.3 Binding the Payment Method Using the Front-end Component
For binding the payment method using the front-end component, the merchant needs to complete the integration through two steps. For details, please refer to: Integration Process.
When binding the payment method using the front-end component, 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
Merchant client integration example:
// 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) => {
// 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 month
},
"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:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-17T09:05:52.194+00:00",
"appId": "3b242b56a8b64274bcc37dac281120e3",
"merchantNo": "020213827212251",
"data": {
"totalAmount": "10", // Direct debit amount
"mitType": "SCHEDULED", // Required, value is SCHEDULED or UNSCHEDULED
"currency": "USD", // Required
"country": "SA", // Not required
"userId": "U10001", // Required, user ID
"componentList": [ // Required, payment methods supported by the component
"GOOGLEPAY"
]
}
}Example of the Response:
{
"code": "APPLY_SUCCESS",
"msg": "Success.",
"data": {
"clientKey": "37114858239eur2384237r810482390",
"sessionKey": "bdsf8982348974hhf82934bf8239424"
}
}The request addresses for different environments of the front-end component Payment interface 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", // Unique order number for merchant's order placement
"subject": "Direct Debit Title", // Title
"totalAmount": 10, // Direct debit amount
"currency": "USD", // Direct debit currency
"userId": "test1111", // User ID
"language": "en",
"reference": "test mit",
"frontCallbackUrl": "http://www.frontCallbackUrl.com",
"notifyUrl": "http://www.notifyUrl.com",
"integrate": "Direct_Payment", // Fixed value: Direct_Payment
"expireTime": "1800",
"terminalType": "WEB", // Terminal type: WEB, WAP or APP
"osType": "ANDROID", // Operating system type: ANDROID or IOS
"subscriptionPlan": { // Optional. Subscription information
"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 month
},
"periodAmount": { // Fixed-period direct debit amount
"amount": 20,
"currency": "USD"
},
"firstPeriodStartDate": "2025-08-26T12:00:00+00:00",
"trialPeriodConfig": { // Promotional period rules
"trialPeriodCount": 1, // Number of promotional periods
"trialPeriodAmount": { // Direct debit amount for promotional periods
"amount": 10,
"currency": "USD"
}
}
},
"mitManagementUrl": "http://your.subscription.com", // Optional
"paymentDetail": {
"paymentToken": "CPT4f200d278f3a454b9e91c81edc641e2b", // Required
"sessionKey": "bdsf8982348974hhf82934bf8239424", // Required
"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:
{
"code": "APPLY_SUCCESS",
"msg": "",
"data": {
"outTradeNo": "P1642410680681",
"tradeToken": "T2024062702289232000001",
"status": "SUCCESS"
}
}4. Obtaining the Result of Binding the Payment Method
Merchants can receive the result of binding the payment method through the notifyUrl address provided when binding the payment method. For the detailed result message, please refer to: Result Notifications API.
Example of notification parameters for successful binding of the payment method:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "APPLY_SUCCESS",
"data": {
"channelNo": "TPC425300174064927201759000685",
"completeTime": "2025-02-27T09:41:12.267Z",
"country": "UN",
"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"
}After the payment method is successfully bound, PayerMax will generate a paymentTokenID, which needs to be used for subsequent direct debits.
Example of notification parameters for failed binding of the payment method:
{
"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"
}5. Initiating a Auto Debit
Parameter description:
totalAmount: The transaction amount must begreater than 0;integrate: Pass the fixed valueDirect_Payment;paymentDetail.mitType: The direct debit type,SCHEDULEDis for periodic subscription, andUNSCHEDULEDis for non-periodic auto debit;paymentDetail.tokenForFutureUse:true/false, whether to generate a token for subsequent direct debits; for subsequent deductions, passfalseor do not pass it;paymentDetail.merchantInitiated:true/false, whether it is a transaction initiated by the merchant; for subsequent deductions, it is initiated by the merchant and the user does not need to participate, so pass the value astrue.paymentDetail.paymentTokenID: The Token returned by PayerMax after the binding method is successful.
For the API document of subsequent direct debits, please refer to the Direct API Payment API. The request addresses for 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", // Unique order number for merchant's order placement
"subject": "Direct Debit Title", // Title
"totalAmount": 10, // Direct debit amount
"currency": "USD", // Direct debit currency
"country": "SA", // Required
"userId": "test1111", // User ID
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "http://www.frontCallbackUrl.com",
"notifyUrl": "http://www.notifyUrl.com",
"integrate": "Direct_Payment", // Fixed value: Direct_Payment
"expireTime": "1800",
"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 direct debits, UNSCHEDULED for non-periodic direct debits
"tokenForFutureUse": false, // Optional, value is true to generate paymentTokenID for subsequent direct debits
"merchantInitiated": true, // Required, false indicates user parameters are needed; true indicates merchant-initiated direct debit (no user participation required)
"paymentTokenID": "PMTOKEN20230424072005899168200035002", // Token value returned to the merchant by PayerMax after the first successful direct debit
"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:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"outTradeNo": "APIFOXDEV1745388079422",
"tradeToken": "T2025042306527802000033",
"status": "SUCCESS"
}
}6. Obtaining the Direct Debit Result
Whether it is binding the payment method or subsequent direct debits, after the deduction is successful or fails, PayerMax will notify the merchant of the deduction result, and the merchant can also actively query the direct debit result.
6.1 Obtaining the Payment Result Using a Callback
Merchants can receive the payment result through the notifyUrl address provided during payment. For the detailed notification message, please refer to: Result Notifications API.
Example of notification parameters for successful auto debit:
{
"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 notification parameters for failed auto debit:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "PAYMENT_FAILED",
"data": {
"channelNo": "TPC462800174064934688659000687",
"completeTime": "2025-02-27T09:44:00.216Z",
"country": "US",
"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"
}After receiving the notification result, the correct code and message need to be responded to PayerMax. Otherwise, PayerMax will think that the merchant has not received the notification message normally and will retry the notification 6 times.
Example of Merchant Response Parameters:
{
"msg": "Success",
"code": "SUCCESS"
}6.2 Obtaining the Payment Result Using a Query
For the API document of obtaining the payment result, please refer to the Transaction Inquiry API. The request addresses for different environments are as follows:
Prod request address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderQuery
Test request address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderQuery
Example of request parameters for querying the auto debit result:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-17T07:51:15.597+00:00",
"appId": "a0dddd1f622243cb9aa1b676e808b5f8",
"merchantNo": "02021382719993",
"data": {
"outTradeNo": "P1642410680681"
}
}Example of response parameters for querying the auto debit result:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"reference": "Reference query and callback return",
"country": "SA",
"totalAmount": 10,
"outTradeNo": "P1642410680681",
"currency": "USD",
"channelNo": "DMCP000000000177005",
"thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
"paymentCode": "2312121212",
"tradeToken": "T2024062702289232000001",
"completeTime": "2023-10-20T03:28:23.092Z",
"paymentDetails": [
{
"targetOrg": "*",
"googlePayInfo": {
"cardIdentifierNo": "123456******1234"
},
"paymentMethodType": "GOOGLEPAY",
"paymentTokenID": "PMTOKEN20250224063712195626335000250",
"payAmount": 10,
"exchangeRate": "1",
"payCurrency": "USD"
}
],
"status": "SUCCESS",
"resultMsg": ""
}
}7. Unbinding the Payment Method
After the user cancels the auto debit, the merchant needs to unbind the payment method for the user. For the API document of unbinding the payment method, please refer to removePaymentToken API. The request addresses for different environments are as follows:
Prod request address: https://pay-gate.payermax.com/aggregate-pay/api/gateway/removePaymentToken
Test request address: https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/removePaymentToken
Example of Request Parameters:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-22T10:00:00.500+08:00",
"appId": "46153e2b787241ae8b01857bb087d1bd",
"merchantNo": "010229810189301",
"data": {
"userId": "TEST",
"paymentTokenID": "PMTOKEN20230424072005899168200035002",
"removeReason": "remove"
}
}Example of the Response:
{
"code": "APPLY_SUCCESS",
"msg": "Success",
"data": {
"paymentTokenID": "PMTOKEN20230424072005899168200035002",
"userId": "Test",
"paymentTokenStatus": "Deleted"
}
}