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:

1. During the test, 127.0.0.1, LAN, and localhost will be all failed to pull up ApplePay;
   
2. The validity period of ApplePay domain name certification is consistent with the validity period of the domain name SSL certificate. For details, please refer to Apple Official Website Instructions;
   
3. Merchants need to complete the certificate renewal and notify PayerMax 15 days before the expiration of their domain SSL certificate.; if the validity period is less than 7 days before completing the certificate update, it is necessary to contact PayerMax to re-certify the domain name;
   
4. If the domain name certification is still valid, the renewal operation will not affect normal transactions, but if the domain name certification has expired, the transaction will fail.

(a) Merchants provide their test environment and production environment domain names to PayerMax;

(b) PayerMax will generate certificates corresponding to each domain name for merchants;

(c) The merchant adds the certificate file apple-developer-merchantid-domain-association.txt to the ./well-known path;

Note:

Please note the certificate configuration path.

(4) After the merchant configures the certificate, it notifies PayerMax to verify the domain name certificate, and PayerMax will perform domain name certificate verification in the Apple developer backend.

If verification fails:

1. The certificate path may be configured incorrectly: Please check again whether the path is correct;
   
2. Maybe the domain name firewall blocks the Apple check service: Please configure the domain name of the link page to the server whitelist, please refer to the screenshot below;
   
3. You may have configured certificates for other MerchantIDs: You can use a new domain name, or delete the corresponding domain name certificate on the original developer account.

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].