ApplePay Periodic Subscription - Merchants Manage Subscription Plans

This document describes the relevant integration steps for non-periodic auto debit, 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 Manage Subscription Plans, subscription plan details will be displayed on the ApplePay pop-up, but not on the PayerMax cashier.

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, SCHEDULED indicates periodic subscription, and UNSCHEDULED 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 as true;
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 as false.
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;
Amount Matching:
- If the subscriptionPlan includes the trial period parameter trialConfig, then totalAmount must match trialConfig.amount;
- If the subscriptionPlan does not include the trial period parameter trialConfig, but includes the promotional period parameter trialPeriodConfig, then totalAmount must match trialPeriodAmount.amount;
- If the subscriptionPlan includes neither trialConfig nor trialPeriodConfig, then totalAmount must be consistent with periodAmount.amount.

3.1 Binding the Payment Method Using the PayerMax Payment Cashier

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as Merchant Client
    participant MServer as Merchant Server
    participant Checkout as PayerMax Cashier
    participant PMServer as PayerMax Server
    participant Apple as Apple

    %% 1. Binding Process Initialization
    Client->>MServer: 1.1 User selects subscription product to place order
    MServer->>MServer: 1.2 Create subscription plan
    MServer->>PMServer: 1.3 Bind payment method
(call orderAndPay)
    PMServer-->>MServer: 1.4 Return PayerMax Cashier URL
    MServer-->>Client: 1.5 Return PayerMax Cashier URL

    %% 2. Apple Pay Authorization and Payment
    Client->>Checkout: 2.1 Redirect to PayerMax Cashier
    Checkout->>Checkout: 2.2 User selects Apple Pay for payment
    Checkout->>Apple: 2.3 Invoke Apple Wallet
    Apple->>Apple: 2.4 Display subscription plan information
    Apple->>Apple: 2.5 User completes Face ID or Touch ID authentication
    Apple-->>Checkout: 2.6 Return Apple payment credentials
    Checkout->>PMServer: 2.7 Initiate payment
    PMServer-->>Checkout: 2.8 Return binding result
    Checkout-->>Client: 2.9 Redirect to Merchant Result Page after payment

    %% 3. Result Notification
    PMServer->>MServer: 3.1 Asynchronous notification of binding result
& paymentTokenID
    MServer-->>PMServer: 3.2 Acknowledge receipt of notification result

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:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Required, merchant's unique order number for the transaction
    "subject": "Deduction Title", // Title
    "totalAmount": 10, // Deduction amount
    "country": "US",
    "currency": "USD", // Deduction 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 First Periodic Payment.",
        "totalPeriods": 12,
        "periodRule": {
            "periodUnit": "M", // Payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
            "periodCount": 1 // Payment every 1 month
        },
        "periodAmount": { // Fixed period payment amount
            "amount": 20,
            "currency": "USD"
        },
        "trialPeriodConfig": { // Promotional period rules
            "trialPeriodCount": 1, // Number of promotional periods
            "trialPeriodAmount": { // Promotional period payment amount
                "amount": 10,
                "currency": "USD"
            }
        },
        // Trial period 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
        }
    },
    "mitManagementUrl": "http://your.subscription.com",
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", // Required, value must be APPLEPAY
      "mitType": "SCHEDULED", // Required, MIT type. Use SCHEDULED for periodic deductions, UNSCHEDULED for non-periodic deductions.
      "tokenForFutureUse": true, // Required, value is true to generate paymentTokenID for future deductions
      "merchantInitiated": false, // Required, false indicates user participation is required; true indicates merchant-initiated deduction without user involvement
      "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:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Required, merchant's unique order number for the transaction
    "subject": "Deduction Title", // Title
    "totalAmount": 0, // Deduction amount
    "currency": "USD", // Deduction 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 First Periodic Payment.",
        "totalPeriods": 12,
        "periodRule": {
            "periodUnit": "M", // Payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
            "periodCount": 1 // Payment every 1 month
        },
        "periodAmount": { // Fixed period payment amount
            "amount": 20,
            "currency": "USD"
        },
        "trialPeriodConfig": { // Promotional period rules
            "trialPeriodCount": 1, // Number of promotional periods
            "trialPeriodAmount": { // Promotional period payment amount
                "amount": 10,
                "currency": "USD"
            }
        },
        // Trial period parameters, optional. If `trialConfig` is included, the fields below are required.
        "trialConfig": {
            "trialAmount": { // Trial period amount
                "amount": 0, // 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
        }
    },
    "mitManagementUrl": "http://your.subscription.com", // Required
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", // Required, value must be APPLEPAY
      "mitType": "SCHEDULED", // Required, MIT type. Use SCHEDULED for periodic deductions, UNSCHEDULED for non-periodic deductions.
      "tokenForFutureUse": true, // Required, value is true to generate paymentTokenID for future deductions
      "merchantInitiated": false, // Required, false indicates user participation is required; true indicates merchant-initiated deduction without user involvement
      "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 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 Apple 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 ApplePay, please refer to: ApplePay - Direct API Integration.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as Merchant Client
    participant Apple as Apple
    participant MServer as Merchant Server
    participant PMServer as PayerMax Server

    %% 1. Client Interaction and Apple Authentication
    Client->>Client: 1.1 User enters merchant subscription page and selects a product
    Client->>Client: 1.2 User enters merchant checkout and selects Apple Pay
    Client->>Apple: 1.3 User clicks Apple Pay
Invoke Apple Wallet
(Pass subscription plan and
management URL to Apple)
    Apple->>Apple: 1.4 User confirms info and selects card for authentication
    Apple-->>Client: 1.5 Apple returns payment credentials (payment data)

    %% 2. Backend Processing and Binding
    Client->>MServer: 2.1 Initiate payment
with selected subscription info and Apple payment credentials
    MServer->>MServer: 2.2 Save subscription plan
    MServer->>MServer: 2.3 Decrypt Apple payment credentials
    MServer->>PMServer: 2.4 Bind payment method
with decrypted Apple payment info
    PMServer-->>MServer: 2.5 Return binding result
    MServer-->>Client: 2.6 Return binding result
    Client->>Client: 2.7 Redirect to subscription result page

    %% 3. Result Notification
    PMServer->>MServer: 3.1 Asynchronous notification of binding result
& paymentTokenID
    MServer-->>PMServer: 3.2 Merchant acknowledges receipt of results

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:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Required, merchant's unique order number for the transaction
    "subject": "Deduction Title", // Title
    "totalAmount": 10, // Deduction amount
    "currency": "USD", // Deduction 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 First Periodic Payment.",
        "totalPeriods": 12,
        "periodRule": {
            "periodUnit": "M", // Payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
            "periodCount": 1 // Payment every 1 month
        },
        "periodAmount": { // Fixed period payment amount
            "amount": 20,
            "currency": "USD"
        },
        "trialPeriodConfig": { // Promotional period rules
            "trialPeriodCount": 1, // Number of promotional periods
            "trialPeriodAmount": { // Promotional period payment amount
                "amount": 10,
                "currency": "USD"
            }
        },
        // Trial period 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
        }
    },
    "mitManagementUrl": "http://your.subscription.com", // Optional
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", // Required, value must be APPLEPAY
      "mitType": "SCHEDULED", // Required, MIT type. Use SCHEDULED for periodic deductions, UNSCHEDULED for non-periodic deductions.
      "tokenForFutureUse": true, // Required, value is true to generate paymentTokenID for future deductions
      "merchantInitiated": false, // false indicates user participation is required; true indicates merchant-initiated deduction without user involvement
      "applePayPaymentData": { // Required, decrypted parameters of Apple Pay payment elements
        "applicationExpirationDate": "231231",
        "applicationPrimaryAccountNumber": "1234209400123456",
        "currencyCode": "344",
        "deviceManufacturerIdentifier": "040010030273",
        "paymentData": {
            "eciIndicator": "7",
            "onlinePaymentCryptogram": "AqhVFUwAAuM69WEZxe+OMAACAAA="
        },
        "paymentDataType": "3DSecure",
        "transactionAmount": "100",
        "network": "Visa",
        "type": "credit",
        "displayName": "VISA 5743"
      },
      "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": {
        "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.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as Merchant Client
    participant MServer as Merchant Server
    participant Checkout as PayerMax Cashier
    participant Apple as Apple
    participant PMServer as PayerMax Server

    %% 1. Initialization Phase
    Client->>Client: 1.1 User enters merchant subscription product page
    Client->>MServer: 1.2 Get component information
    MServer->>PMServer: 1.3 Request applyDropinSession
    PMServer-->>MServer: 1.4 Return clientKey and sessionKey
    MServer-->>Client: 1.5 Return clientKey and sessionKey
    Client->>Client: 1.6 Render PayerMax component

    %% 2. Payment Initiation Process
    rect rgb(235, 245, 255)
    Note over Client, PMServer: Payment Initiation Process
    Client->>Client: 2.1 User selects product and Apple Pay to initiate payment
    Client->>MServer: 2.2 Save subscription plan
    MServer-->>Client: 2.3 Return subscription plan information

    Client->>Checkout: 2.4 Call component canMakePayment API to invoke Apple Wallet
(Pass subscription info and mitManagementUrl to PayerMax component)
    Checkout->>Apple: 2.5 Invoke Apple Wallet
    Apple->>Apple: 2.6 Display subscription plan information
    Apple->>Apple: 2.7 User selects card and completes authentication
    Apple-->>Checkout: 2.8 Return Apple payment credentials
    Checkout->>Checkout: 2.9 Generate paymentToken
    Checkout-->>Client: 2.10 Return paymentToken

    Client->>MServer: 2.11 Submit
paymentToken and sessionKey
    MServer->>PMServer: 2.12 Call orderAndPay to bind payment method
(Submit paymentToken and sessionKey)
    PMServer-->>MServer: 2.13 Return binding result
    MServer-->>Client: 2.14 Return binding result
    end
    Client->>Client: 2.15 Redirect to subscription result page

    %% 3. Notification Phase
    PMServer->>MServer: 3.1 Asynchronous notification of binding result & paymentTokenID
    MServer-->>PMServer: 3.2 Merchant acknowledges receipt of results

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", {
    // Notify the server that this is a subscription payment?
    ...params
})
// Create Apple Pay view
applePay = PMdropin.create('applepay', {
  clientKey: data.clientKey,
  sessionKey: data.sessionKey,
  theme: yourTheme,
  payButtonStyle: data.yourPayButtonStyle,
  sandbox: data.yourFrameEnv
})
// Mount to DOM
applePay.mount('.frame-applepay')
// Load event - check if successfully loaded
applePay.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 Apple Pay button click event. When users select a subscription plan and click the Apple Pay button, this event can be used to monitor it.
applePay.on('payButtonClick', (res) => {
    // Disable Apple Pay button click state
     applePay.emit('setDisabled', true)
     // Must pass subscriptionPlan and mitManagementUrl;
     applePay.emit('canMakePayment', { 
         // subscriptionPlan is required for periodic subscriptions
          subscriptionPlan: {
            "subject": "subject",
            "description": "PMMAX First Periodic Payment.",
            "totalPeriods": 12,
            "periodRule": {
                "periodUnit": "M", // Payment frequency: Monthly (M), Daily (D), Weekly (W), Yearly (Y)
                "periodCount": 1 // Payment every 1 month
            },
            "periodAmount": { // Fixed period payment amount
                "amount": 404.35,
                "currency": "SAR"
            },
            "trialPeriodConfig": { // Promotional period rules
                "trialPeriodCount": 1, // Number of promotional periods
                "trialPeriodAmount": { // Promotional period payment amount
                    "amount": 10,
                    "currency": "SAR"
                }
            },
            // Trial period 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
            }
        },
        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 parameters do not meet the format requirements, an error message will be thrown here
            // Error response example: { code: "MIT_PARAMS_VALIDATION_ERROR", message: "xxx is required" }
          _payLog(JSON.stringify(res))  
          applePay.emit('setDisabled', false)
        }
      })
      .catch(err => {
         // If validation fails, report a clear error. TODO
        console.log('canMakePayment catch', err)
        applePay.emit('payFail')
        applePay.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", // 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
      "APPLEPAY"
    ]
  }
}

Example of the Response:

json

{
  "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:

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": "Direct Debit Title", // Title
    "totalAmount": 10, // Direct debit amount
    "currency": "USD", // Direct debit currency
    "userId": "test1111", // User ID
    "language": "en",
    "reference": "test mit",
    "frontCallbackUrl": "https://[your domain name]/[your callback URL]",
    "notifyUrl": "https://[your domain name]/[your notify URL]",
    "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", // Deducted monthly (M), daily (D), weekly (W), yearly (Y)
            "periodCount": 1 // Deducted once a month
        },
        "periodAmount": { // Fixed period deduction amount
            "amount": 20,
            "currency": "USD"
        },
        "trialPeriodConfig": { // Trial period rules
            "trialPeriodCount": 1, // Number of trial periods
            "trialPeriodAmount": { // Deduction amount during trial period
                "amount": 10,
                "currency": "USD"
            }
        }
    },
    "mitManagementUrl": "https://[your domain name]/[your subscription management URL]", // Optional
    "paymentDetail": {
      "paymentToken": "CPT4f200d278f3a454b9e91c81edc641e2b", // Required
      "sessionKey": "bdsf8982348974hhf82934bf8239424", // Required
      "mitType": "SCHEDULED", // Required, MIT type: SCHEDULED for periodic direct debit, UNSCHEDULED for non-periodic direct debit
      "tokenForFutureUse": true, // Required, set to true to generate paymentTokenID for subsequent direct debits
      "merchantInitiated": false, // Required, false indicates not initiated by the merchant actively (with user participation); true indicates initiated by the merchant actively (no user participation required)
      "buyerInfo": {
        "firstName": "Deborah",
        "lastName": "Swinstead",
        "email": "your@gmail.com",
        "phoneNo": "0609 031 114",
        "address": "Test Address",
        "city": "Holden Hill",
        "region": "SA",
        "zipCode": "5088",
        "clientIp": "211.52.321.225",
        "userAgent": "Mozilla/5.0 (iPad; CPU OS 18_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22E252 [FBAN/FBIOS;FBAV/513.1.0.55.90;FBBV/735017191;FBDV/iPad13,16;FBMD/iPad;FBSN/iPadOS;FBSV/18.4.1;FBSS/2;FBID/tablet;FBLC/en_GB;FBOP/5;FBRV/737247184]"
      }
    }
  }
}

Example of the Response:

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "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:

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "APPLY_SUCCESS",
    "data": {
        "channelNo": "TPC425300174064927201759000685",
        "completeTime": "2025-02-27T09:41:12.267Z",
        "country": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174104451122388",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
                "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:

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "PAYMENT_FAILED",
    "data": {
        "channelNo": "TPC462800174064934688659000687",
        "completeTime": "2025-02-27T09:44:00.216Z",
        "country": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174218727122389",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
            }
        ],
        "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 be greater than 0;
integrate: Pass the fixed value Direct_Payment;
paymentDetail.mitType: The direct debit type, SCHEDULED is for periodic subscription, and UNSCHEDULED is for non-periodic auto debit;
paymentDetail.tokenForFutureUse: true/false, whether to generate a token for subsequent direct debits; for subsequent deductions, pass false 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 as true.
paymentDetail.paymentTokenID: The Token returned by PayerMax after the binding method is successful.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant MServer as Merchant Server
    participant PMServer as PayerMax Server

    %% Deduction Process
    MServer->>PMServer: 1. Subsequent Deduction: paymentTokenID Payment
    PMServer->>PMServer: 2. Complete Payment
    PMServer-->>MServer: 3. Synchronously return deduction payment result
    PMServer->>MServer: 4. Asynchronously notify deduction payment result and
paymentTokenID
    MServer-->>PMServer: 5. Respond to message interface result

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:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // Required, merchant's unique order number for the transaction
    "subject": "Deduction Title", // Title
    "totalAmount": 10, // Deduction amount
    "currency": "USD", // Deduction 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
    "subscriptionPlan": {
        "merchantSubscriptionNo": "xxxx", // Merchant's subscription plan ID
        "deductNo": "xxxx", // Unique deduction number for the current period. For multiple retries of the same period deduction, this number should remain consistent.
        "currentPeriod": 2, // Current period number
        "totalPeriods": 36, // Total number of periods
        "startTime": "2026-01-01", // Start time of the current period
        "endTime": "2026-01-31" // End time of the current period
    },
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", // Required, value must be APPLEPAY
      "mitType": "SCHEDULED", // Required, MIT type. Use SCHEDULED for periodic deductions, UNSCHEDULED for non-periodic deductions.
      "tokenForFutureUse": false, // Optional, value is true to generate paymentTokenID for future deductions
      "merchantInitiated": true, // Required, false indicates user participation is required; true indicates merchant-initiated deduction without user involvement
      "paymentTokenID": "PMTOKEN20230424072005899168200035002", // Token value returned by PayerMax to the merchant after the first successful deduction
      "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": {
        "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:

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "APPLY_SUCCESS",
    "data": {
        "channelNo": "TPC425300174064927201759000685",
        "completeTime": "2025-02-27T09:41:12.267Z",
        "country": "US",
        "currency": "USD",
        "outTradeNo": "20250227174104451122388",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
                "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:

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "PAYMENT_FAILED",
    "data": {
        "channelNo": "TPC462800174064934688659000687",
        "completeTime": "2025-02-27T09:44:00.216Z",
        "country": "US",
        "currency": "USD",
        "outTradeNo": "20250227174218727122389",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
            }
        ],
        "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:

json

{
  "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:

json

{
  "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:

json

{
  "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": "*",
        "applePayInfo": {
            "cardOrg": "VISA",
            "cardIdentifierNo": "123456****1234"
        },
        "paymentMethodType": "APPLEPAY",
        "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:

json

{
  "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:

json

{
  "code": "APPLY_SUCCESS",
  "msg": "Success",
  "data": {
    "paymentTokenID": "PMTOKEN20230424072005899168200035002",
    "userId": "Test",
    "paymentTokenStatus": "Deleted"
  }
}

Integration Modes Details

Acquiring Basic Products

CARD

GOOGLEPAY

APPLEPAY

Subscription and Auto Debit

PayerMax Manage Subscription Plans

Merchants Manage Subscription Plans

Non-Periodic Auto Debit

Drop In

Tokenization

Auth-Capture

ChargeBack

Risk Control

Troubleshooting

Payment Method Classification

Payment Method Details

Asia Pacific

Central Asia

Middle East and Africa

Europe

North America and Latin America

Global

ApplePay Periodic Subscription - Merchants Manage Subscription Plans ​

1. Front-End Interaction ​

2. Preparation Items ​

3. Binding the Payment Method ​

3.1 Binding the Payment Method Using the PayerMax Payment Cashier ​

3.2 Binding the Payment Method in Direct API Mode ​

3.3 Binding the Payment Method Using the Front-end Component ​

4. Obtaining the Result of Binding the Payment Method ​

5. Initiating a Auto Debit ​

6. Obtaining the Direct Debit Result ​

6.1 Obtaining the Payment Result Using a Callback ​

6.2 Obtaining the Payment Result Using a Query ​

7. Unbinding the Payment Method ​

ApplePay Periodic Subscription - Merchants Manage Subscription Plans

1. Front-End Interaction

2. Preparation Items

3. Binding the Payment Method

3.1 Binding the Payment Method Using the PayerMax Payment Cashier

3.2 Binding the Payment Method in Direct API Mode

3.3 Binding the Payment Method Using the Front-end Component

4. Obtaining the Result of Binding the Payment Method

5. Initiating a Auto Debit

6. Obtaining the Direct Debit Result

6.1 Obtaining the Payment Result Using a Callback

6.2 Obtaining the Payment Result Using a Query

7. Unbinding the Payment Method