APM Periodic Subscription - Merchants Manage Subscription Plans
This document describes the relevant integration steps for merchants managing subscription plans, 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. 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. 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,SCHEDULED
indicates periodic subscription, andUNSCHEDULED
indicates 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
.
2.1 Binding the Payment Method Using the PayerMax Payment Cashier
Note:
The cashier mode binds the payment method to support Full cashier mode
, Specify payment method
, and Specify payment method + target institution
.
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 full cashier transaction amount is greater than 0, the request parameter example is:
{
"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": "Hosted_Checkout", // Fixed value: Hosted_Checkout
"expireTime": "1800",
"paymentDetail": {
"mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
"tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
"merchantInitiated": false, // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
"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 of the specified wallet payment method is greater than 0, the request parameter example is:
{
"version": "1.5",
"keyVersion": "1",
"requestTime": "2022-01-17T09:05:52.194+00:00",
"appId": "bbd8d2639a7c4dfd8df7d005294390df",
"merchantNo": "020113838535952",
"data": {
"outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
"subject": "代扣标题", // 标题
"totalAmount": 10, // 代扣金额
"currency": "USD", // 代扣币种
"country": "KR", // 必传
"userId": "test1111", // 用户号
"language": "en",
"reference": "test subscription",
"frontCallbackUrl": "http://www.frontCallbackUrl.com",
"notifyUrl": "http://www.notifyUrl.com",
"integrate": "Hosted_Checkout", // 固定值:Hosted_Checkout
"expireTime": "1800",
"paymentDetail": {
"paymentMethodType": "WALLET", //必传,支付方式类型
"mitType": "SCHEDULED", // 必传,MIT类型,周期性代扣时为SCHEDULED,非周期性代扣时为UNSCHEDULED
"tokenForFutureUse": true, // 必传,值为true,生成paymentTokenID,用于后续代扣
"merchantInitiated": false, // 必传,false标识不是商户主动发起,有用户参与;true标识商户主动发起,不需要用户参与
"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 specified wallet payment method and target institution transaction amount is greater than 0, the request parameter example is:
{
"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": "KR", // Required
"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",
"paymentDetail": {
"paymentMethodType": "WALLET", // Required, payment method type
"targetOrg": "NAVERPAY", // Target organization
"mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
"tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
"merchantInitiated": false, // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
"buyerInfo": {
"firstName": "Deborah",
"lastName": "Swinstead",
"email": "your@gmail.com",
"phoneNo": "0609 031 114",
"address": "Test Address",
"city": "Holden Hill",
"region": "SA",
"zipCode": "5088",
"clientIp": "211.52.321.225",
"userAgent": "Mozilla/5.0 (iPad; CPU OS 18_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22E252 [FBAN/FBIOS;FBAV/513.1.0.55.90;FBBV/735017191;FBDV/iPad13,16;FBMD/iPad;FBSN/iPadOS;FBSV/18.4.1;FBSS/2;FBID/tablet;FBLC/en_GB;FBOP/5;FBRV/737247184]"
}
}
}
}
Example of the Response:
{
"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"
}
}
2.2 Binding the Payment Method in Direct API Mode
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 the first debit request parameters for a specified wallet payment method in API mode:
{
"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": "KR", // 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": "WALLET", // Required, payment method type
"targetOrg": "NAVERPAY", // Target organization
"mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
"tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
"merchantInitiated": false // false indicates user parameters are required; true indicates merchant-initiated direct debit without user participation
}
}
}
Example of the Response:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
// Redirect link
"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. 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 wallet payment method:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "APPLY_SUCCESS",
"data": {
"channelNo": "TPC425300174064927201759000685",
"completeTime": "2025-02-27T09:41:12.267Z",
"country": "UN",
"currency": "USD",
"outTradeNo": "20250227174104451122388",
"paymentDetails": [
{
"paymentMethodType": "WALLET",
"targetOrg": "NAVERPAY",
"paymentTokenID": "PMTOKEN20250227071843552050007000094"
}
],
"reference": "reference",
"status": "SUCCESS",
"thirdChannelNo": "mtjxuvedrz58345",
"totalAmount": 10,
"tradeToken": "T2025022709425329000091"
},
"keyVersion": "1",
"merchantNo": "P01010118267336",
"msg": "Success.",
"notifyTime": "2025-02-27T09:41:12 +0000",
"notifyType": "PAYMENT"
}
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 wallet payment method:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "PAYMENT_FAILED",
"data": {
"channelNo": "TPC462800174064934688659000687",
"completeTime": "2025-02-27T09:44:00.216Z",
"country": "UN",
"currency": "USD",
"outTradeNo": "20250227174218727122389",
"paymentDetails": [
{
"paymentMethodType": "WALLET",
"targetOrg": "NAVERPAY"
}
],
"reference": "reference",
"status": "FAILED",
"thirdChannelNo": "dycbhzfsmz69480",
"totalAmount": 10,
"tradeToken": "T2025022709462829000092"
},
"keyVersion": "1",
"merchantNo": "P01010118267336",
"msg": "Provider failed to process.",
"notifyTime": "2025-02-27T09:44:00 +0000",
"notifyType": "PAYMENT"
}
4. 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,SCHEDULED
is for periodic subscription, andUNSCHEDULED
is for non-periodic auto debit;paymentDetail.tokenForFutureUse
:true
/false
, whether to generate a token for subsequent direct debits; for subsequent deductions, passfalse
or 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 subsequent debit request parameters for API mode wallet payment method:
{
"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
"country": "KR",
"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
"paymentDetail": {
"paymentMethodType": "WALLET", // Required, payment method type
"targetOrg": "NAVERPAY",
"mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
"tokenForFutureUse": false, // Required, set to true to generate paymentTokenID for subsequent direct debits
"merchantInitiated": true, // false indicates user parameters are required; true indicates merchant-initiated direct debit without user participation
"paymentTokenID": "PMTOKEN20230424072005899168200035002", // Token value returned to merchant by PayerMax after successful first 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"
}
}
5. 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.
5.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 debit payment using wallet payment method:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "APPLY_SUCCESS",
"data": {
"channelNo": "TPC425300174064927201759000685",
"completeTime": "2025-02-27T09:41:12.267Z",
"country": "US",
"currency": "USD",
"outTradeNo": "20250227174104451122388",
"paymentDetails": [
{
"paymentMethodType": "WALLET",
"targetOrg": "NAVERPAY",
"paymentTokenID": "PMTOKEN20250227071843552050007000094"
}
],
"reference": "reference",
"status": "SUCCESS",
"thirdChannelNo": "mtjxuvedrz58345",
"totalAmount": 10,
"tradeToken": "T2025022709425329000091"
},
"keyVersion": "1",
"merchantNo": "P01010118267336",
"msg": "Success.",
"notifyTime": "2025-02-27T09:41:12 +0000",
"notifyType": "PAYMENT"
}
Example of notification parameters for failed debit payment using wallet payment method:
{
"appId": "d68f5da6a0174388821a64114c6b322c",
"code": "PAYMENT_FAILED",
"data": {
"channelNo": "TPC462800174064934688659000687",
"completeTime": "2025-02-27T09:44:00.216Z",
"country": "US",
"currency": "USD",
"outTradeNo": "20250227174218727122389",
"paymentDetails": [
{
"paymentMethodType": "WALLET",
"targetOrg": "NAVERPAY"
}
],
"reference": "reference",
"status": "FAILED",
"thirdChannelNo": "dycbhzfsmz69480",
"totalAmount": 10,
"tradeToken": "T2025022709462829000092"
},
"keyVersion": "1",
"merchantNo": "P01010118267336",
"msg": "Provider failed to process.",
"notifyTime": "2025-02-27T09:44:00 +0000",
"notifyType": "PAYMENT"
}
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"
}
5.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"
}
}
Wallet payment method debit result query response parameters:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"reference": "reference for 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": [
{
"paymentMethodType": "WALLET",
"targetOrg": "NAVERPAY",
"paymentTokenID": "PMTOKEN20250224063712195626335000250",
"payAmount": 10,
"exchangeRate": "1",
"payCurrency": "USD"
}
],
"status": "SUCCESS",
"resultMsg": ""
}
}
6. 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"
}
}