Integration Process

1. Implementation Process

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":["APPLEPAY","CARD"] 
        }
    }

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, you can 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-card">
  <!-- form will be added here -->
</div>

(c) Initialize PayerMax Frames；

// Initialize the card component
const card = PMdropin.create('card', {
  clientKey: "Client public key", // data.clientKey obtained in step 1.1
  sessionKey: "Session key", // data.sessionKey obtained in step 1.1
  sandbox: false, // The default value is false, which means production environment
  hideSaveCard: false, // Whether to hide the save card information option, the default value is false
  hideCardBrands: false, // Whether to hide the card brand logo in the upper left corner, the default value is false
});
// Mounting an instance
card.mount('.frame-card'); // Will be mounted on the first matched DOM element
// Component loading completed
card.on('ready', () => {
    // Except for custom loading               
})

(d) Monitor form filling status (optional);

Note:

When the status changes, a real-time callback will be made to determine whether the payment button is clickable.

card.on('form-check', (res) => {
  // res.isFormValid is the form status false/true
  // 'true' means the form has been verified and you can try to pay; 'false' means the verification has not been passed and you cannot click the payment button
  console.log('[dropin][form-check]:', res)
})

(e) Check whether payment is available & obtain payment token;

Special Reminder:

Before calling the payment API, be sure to check whether payment is available; if payment is available, you will get paymentToken, which is used to initiate the payment API.

card.emit('setDisabled', true) // Freeze the form after clicking the payment button to prevent repeated submission of the payment process
card.emit('canMakePayment')
  .then(res => {
    if (res.code === 'APPLY_SUCCESS') {
      const paymentToken = res?.data?.paymentToken // Payment token, used for payment API
      // ❗️Initiate payment API
      // Merchants request the backend API to place orders themselves
      // Merchants use params to construct request parameters, and paymentToken is required
        _postapi('orderAndPay',params).then(res =>{
          const code = (res || {}).code
          // The merchant returns the payment result to the front end
          if (code == 'APPLY_SUCCESS') {     
            // Payment successful, display the payment result
          } else {
            // Payment failed, display payment result
          }
    }
      card.emit('setDisabled', false) // ❗️Unfreeze the form after the payment interface is completed
    }
  })
  .catch(err => {
    card.emit('setDisabled', false) // Unfreeze the form after an exception occurs
  })

(f) Initiate payment. For details, please refer to 1.3 Server-side Initiated Payment.

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, passing 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

If the server returns redirectUrl and status=PENDING when placing an order, the front end needs to open the redirectUrl. The user can do 3ds verification and complete payment on this page. In other cases, the payment result can be obtained directly.

• 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": "Chrome"
			},
			"sessionKey": "86409e2c04b44536a484caa5ce3ce0e9"
		},
		"frontCallbackUrl": <To be replaced>,
		"subject": "GoGeal PTE. LTD.",
		"outTradeNo": <Merchant order number, must be unique>,
		"notifyUrl": <To be replaced>,
		"currency": "HKD",
		"userId": "3ff0495692d152be96d84dbc9352dc57",
		"integrate": "Direct_Payment",
		"terminalType": "WEB"
	}
}

2. Other customization

For details on the front-end API, please refer: [Card Pay Frontend API]. For front-end style adjustments, please refer: [Customization].