Integration Process

1. Implementation Process

(a) Follow the process below to complete the test environment test;

(b) The test can be performed under 127.0.0.1 and localhost;

(c) After the test is completed, you can switch to the URL requested by the production line to go online.

1.1 Get clientKey and sessionKey

For detailed interface information, please refer: API.

(a) Request API; the API environment and request URL are as follows:

API Environment	Request URL
Test	https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/applyDropinSession
Live	https://pay-gate.payermax.com/aggregate-pay/api/gateway/applyDropinSession

(b) Get clientKey and sessionKey from the return value.

Note:

The clientKey and sessionKey obtained by the server are returned to the front end for component initialization.

Request Header Example:

{
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <Refer: https://docs-v2.payermax.com/doc-center/developer/config-settings.html>
};

Request Body Example:

request.body = {
    "version": "1.1",
    "keyVersion": "1",
    "requestTime": <To be replaced>, 
    "merchantNo": <To be replaced>,
    "appId": <To be replaced>, 
    "data": {
        "country": "MY", 
        "currency": "MYR", 
        "totalAmount":"50",
        "userId": "20220622_00086",
        "componentList":['CARD', 'APPLEPAY', "GOOGLEPAY"]
    }
    }
    
response={
    "msg": "",
    "code": "APPLY_SUCCESS", 
    "data": {
    "sessionKey": "bf2c47b085e24c299e45dd56fd751a70",
    "clientKey": "bbd8d2639a7c4dfd8df7d005294390df" 
    }
 }

1.2 Rendering Components

• Front-end Example

Download the Demo, after replacing clientKey and sessionKey, open it locally to see the effect.

• Front-end Integration Steps

(a) Introduce the CDN package on the relevant HTML page;

<script src="https://cdn.payermax.com/dropin/js/pmdropin.min.js"></script>

(b) Embed an iframe via a div tag;

<div class="frame-GooglePay">
  <!-- form will be added here -->
 </div>

(c) Initialize PayerMax Frames；

// Initialize the card component
const googlePay = PMdropin.create('googlepay', {
    clientKey: "Client Public Key", // data.clientKey obtained in Step 1.1
    sessionKey: "Session Key", // data.sessionKey obtained in Step 1.1 
    sandbox: true, // The default value is false, which means production environment
    payButtonConfig: {   
        // The following are the default parameter settings. If not passed, it will be equivalent to the following configuration items
        buttonRadius: "12",
        buttonColor: "default",
        buttonType: "plain",
        buttonLocale: "en",
        width: "240px",
        height: "40px"
    }
 });
 
 //  Mounting an instance
 googlePay.mount('.frame-googlepay'); // Will be mounted on the first matched DOM element
 
 // Component loading completed
 googlePay.on('ready', () => {
    // Remove custom loading         
 })

// Monitoring error scenarios
googlePay.on('load', (res = {}) => {
      const { code, msg } = res || {};
      if(code === "SUCCESS"){
        console.log('[merchant][load]success:', res)
      }else{
        console.log('[merchant][load]fail:', res)
      }
    })

(d) Listen for clicks on the GooglePay button and get paymentToken;

Note:

Get paymentToken, which is used to initiate the payment interface.

googlePay.on('payButtonClick', (res) => {
                googlePay.emit('setDisabled', true);
                googlePay.emit('canMakePayment')
                    .then(paymentRes => {
                        if (paymentRes.code === 'APPLY_SUCCESS') {
                            const paymentToken = paymentRes?.data?.paymentToken;
                            console.log('paymentToken:', paymentToken)
                            // ⚠️ Initiate payment interface
                            // Merchants request the backend interface to place orders themselves.
                            // Merchants use params to construct request parameters themselves, and paymentToken is required
                            const params = {  // Add params definition
                                token: paymentToken,
                                
                            };
                            _postapi('orderAndPay', params)
                                .then(apiRes => {
                                    const code = (apiRes || {}).code;
                                    if (code === 'APPLY_SUCCESS') {     
                                        googlePay.emit('paySuccess');//The payment is successful and the GooglePay control disappears
                                    } else {
                                        googlePay.emit('payFail');//Payment failed, googlePay control disappeared
                                    }
                                    googlePay.emit('setDisabled', false);// ⚠️ Unfreeze the form after the payment interface is completed
                                })
                                .catch(err => {
                                    console.error('API request failed:', err);
                                    googlePay.emit('setDisabled', false);// Unfreeze the form after an exception occurs
                                });
                        }
                    })
                    .catch(err => {
                        console.error('Payment ability check failed:', err);
                        googlePay.emit('setDisabled', false);
                    });
            });

(e) Initiate payment. For details, please refer to the next step "Place order in merchant backend".

1.3 Place order on merchant backend

• Order Timing

Please call card.emit('canMakePayment') on the front end and initiate an order request when response.code is 'APPLY_SUCCESS'. At this point, you can get the paymentToken from the canMakePayment method and use it as an input parameter in the subsequent order placement interface.

• Order Steps

(a) The merchant frontend initiates an order to the merchant backend and passes in the paymentToken obtained by the canMakePayment method;

(b) The merchant server generates an order number (outTradeNo) and then initiates a payment request to the PayerMax server;

(c) Process the PayerMax response result.

• Response Processing

The server will return the payment result after placing an order. After processing the payment result, it needs to respond to the front end. The front end calls googlePay.emit('paySuccess') or googlePay.emit('payFail') according to the response result.

• API Environment and Request URL

API Environment	Request URL
Test	https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay
Prod	https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay

Request Header Example:

For the value of the sign field, please refer: [Config Settings and Signature Rules].

{
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <XXX>
};

Request Body Example:

For detailed fields for order placement API, please refer: API.

{
    "appId": "<To be replaced>",
    "version": "1.4",
    "merchantNo": "<To be replaced>",
    "requestTime": "2024-06-05T10:46:01.694+08:00",
    "keyVersion": "1",
    "data": {
        "totalAmount": 77.44,
        "country": "HK",
        "expireTime": "7200",
        "paymentDetail": {
            "paymentToken": "332e4cc1af1740aeafe9e7df82aeb5a1",
            "buyerInfo": {
                "clientIp": "59.82.59.92",
                "userAgent": "Safari"
            },
            "sessionKey": "86409e2c04b44536a484caa5ce3ce0e9"
        },
        "frontCallbackUrl": "<To be replaced>",
        "subject": "<To be replaced>",
        "outTradeNo": "1003052024060510454400707",
        "notifyUrl": "<To be replaced>",
        "currency": "HKD",
        "userId": "3ff0495692d152be96d84dbc9352dc57",
        "integrate": "Direct_Payment", //Fixed value
        "terminalType": "WEB"
    }
}

2. Other customization

For details on the front-end API, please refer: [GooglePay Frontend API].