Integration Process

1. Implementation Process

Before integration: You need to provide an https domain name to payermax configuration (two domain names for the official environment and the test environment) for ApplePay to initiate payment.

Special Reminder:

During the test, 127.0.0.1, LAN, and localhost will be all failed to pull up ApplePay

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.

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 need to deploy it on a domain with an ApplePay certificate and open it 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-applepay">
  <!-- form will be added here -->
</div>

(c) Initialize PayerMax Frames；

// Initialize the card component
const applePay = PMdropin.create('applepay', {
  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
  theme: 'dark',// Theme, the default value is light
});
// Mounting an instance
applePay.mount('.frame-applepay'); // Will be mounted on the first matched DOM element
// Component loading completed
applePay.on('ready', () => {
    // Except for custom loading               
})

(d) Listen for applePay button clicks and get paymentToken;

Note:

Get paymentToken, used to initiate the payment interface.

applePay.on('payButtonClick', (res) => {
  applePay.emit('setDisabled', true) // Freeze the form to prevent repeated button clicks
  applePay.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 interface to place orders
        // 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') {     
              applepay.emit('paySuccess')// Payment is successful, ApplePay control disappears
            } else {
              applepay.emit('payFail')// Payment failed, ApplePay control disappeared
            }
        applePay.emit('setDisabled', false) // ❗️Unfreeze the form after the payment interface is completed
      } 
    })
    .catch(err => {
      applePay.emit('setDisabled', false) // Unfreeze the form after an exception occurs
    })
})

(e) 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

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 applepay.emit('paySuccess') or applepay.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: [ApplePay Frontend API].