Introduction

Apple Pay offers a fast, secure, and seamless payment option for customers. Integrating Apple Pay into your checkout process enhances the user experience while maintaining compliance with Apple’s merchant validation requirements.

This guide simplifies the implementation process using PRTH and MXMerchant.com, eliminating the need for manual configurations.

In this guide, you’ll find how to:

• Add an Apple Pay button to your checkout page.
• Access and use a pre-configured merchant identifier file, reducing setup time.
• Follow a streamlined implementation guide to complete your Apple Pay integration efficiently.

Apple Pay Implementation Guide

Step 1: Setting Up Domain Association for Apple Pay

PRTH handles Apple Pay’s merchant validation on behalf of merchants using Vortex. This includes creating an Apple Merchant ID and the necessary Certificate Signing Request.
Instead of following the manual merchant validation process outlined in Apple’s documentation, you can use these steps:

Steps for Domain Association

1. Download the domain association file:
   PRTH provides a pre-configured domain association file to simplify your setup. Download this file and host it on your website’s server at the following path:

/.well-known/apple-developer-merchantid-domain-association

For example, if your website domain is https://yourwebsite.com, ensure that this file is accessible at:

https://yourwebsite.com/.well-known/apple-developer-merchantid-domain-association.

2. Register your domain with PRTH:

After hosting the domain association file, notify PRTH to register your domain with Apple. You can do this through the PRTH Dashboard under Payment Methods - Domain Registration, or by using the API with your live credentials as shown below.

Example Command Line Registration:

curl --request POST \
     --url 'https://sandbox.api.mxmerchant.com/checkout/v3/applepay/register' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "merchantId": 1000003276,
	 "domainNames": ["[email protected], [email protected], [email protected]"],
	 "merchantName": "Display Merchant",
	 "merchantUrl": "https://your-merchant-url-to-be-registered",
}
'

Important: Register your domain only once per PRTH account to avoid duplication.

3. Begin Apple Pay Transactions:
   Once PRTH registers your domain with Apple, you can start accepting Apple Pay payments using your live API keys. No further action is needed on your end for merchant validation.

Why are these steps Important?
By following these steps, PRTH manages the Apple Pay merchant validation process for you. This setup ensures that your domain is fully validated and ready to process Apple Pay transactions.

Step 2: Adding the Apple Pay Button to Your Checkout Page

To enable Apple Pay on your website using Vortex, you must integrate the Apple Pay button into your checkout page. This involves client-side implementation and compliance with Apple’s requirements.

What You Need to Do

1. Ensure HTTPS is enabled:

Apple Pay requires all pages that offer Apple Pay functionality to be served over HTTPS. Ensure your checkout page is fully secure with a valid SSL certificate.

2. Reference Apple Pay JS API:

Apple provides a JavaScript API that enables the Apple Pay button on your website. Include this script in the header of your checkout page:

<script type="text/javascript" src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

3. Configure the Apple Pay button:

Using the Apple Pay API, add the button element to your checkout page. Ensure that the button follows Apple’s design guidelines:

<apple-pay-button buttonstyle="black" type="plain" locale="en-US"></apple-pay-button>

This is the visual representation of Apple Pay on your site, offering customers a familiar and trusted option for payments.

5. Verify the button functionality:

Test that the button is properly displayed and functional across all relevant devices, including iPhones, iPads, and MacBooks. Use Apple’s sandbox environment to run test transactions and ensure a smooth experience.

Reference Documentation

For detailed instructions on customizing the Apple Pay button and initiating payment requests, refer to Apple’s Apple Pay Web Merchant Registration API Documentation.

Step 3: Implementing Apple Pay with MXMerchant.com (Checkout)

After registering your merchant with Priority, the next step is to handle transactions using MXMerchant.com. This involves sending an encrypted payment payload to MXMerchant.com for secure processing.

How to Implement Apple Pay with MXMerchant.com

Refer to the API Reference documentation and follow the Apple Pay JS API Documentation.

Below are key events to modify:

1. Provide merchant validation:

• Request the PaymentSession object from Priority instead of directly from Apple.
• Upon receiving the PaymentSession object from Priority, forward it to Apple to retrieve a payment token.
• Construct a payload with the necessary details and send it to Priority. Priority will respond with a paymentSession.

To request a payment session from Priority, use one of the following URLs. :

MXMerchant URLs:

• Sandbox: https://sandbox.api.mxmerchant.com/checkout/v3/applepay/authorize?echo=true

• Production: https://api.mxmerchant.com/checkout/v3/applepay/authorize?echo=true

Payload example:

{"merchantId": 1000009526, // your platform merchant id "merchantUrl": "apple-pay-unc-enggss-spring.net", // your registered merchant url "merchantName": "Display Merchant", // your registered merchant name}

Client response example:

{"ResponseCode": 200, "ResponseMessage": "Success", "PaymentSession": "payment session object"}

Complete the merchant validation step
Send the authorized PaymentSession object to Apple to receive a payment token.

2. Authorize Apple Pay payments

Once you receive the payment token from Apple, create a new payload containing the token. Send this payload to Priority’s system for processing via MXMerchant.com. Use one of the following URLs to transmit the payload:

MXMerchant URLs:

• Sandbox: https://sandbox.api.mxmerchant.com/checkout/v3/payment?includeCustomerMatches=false&echo=true
• Production: https://api.mxmerchant.com/checkout/v3/payment?includeCustomerMatches=false&echo=true

Create the payment transaction payload:

const payload = {"provider": "Apple_Pay", "tenderType": "Card", "amount" : this.amount, "posData": { "cardholderPresence": "ecom", "deviceAttendance":"HomePc", "deviceInputCapability":"VoiceAru", "deviceLocation":"HomePc", "panCaptureMethod":"manual", "partialApprovalSupport":"notsupported", "pinCaptureCapability":"incapable", "cardPresent": false }, "cardAccount": { "mobileWallet": { "data": token.paymentData.data, "signature": token.paymentData.signature, "header": token.paymentData.header , "version": token.paymentData.version, "paymentMethod": token.paymentMethod, "transactionIdentifier": token.transactionIdentifier } }, "merchantId": merchantId // platform merchant id};

Post the payment to Priority MXMerchant.com

Step 4. Handling the Transaction Payload

Once MXMerchant authorizes the payment, it returns a transaction payload with key details such as the transaction ID, amount, and status. Store this information securely for record-keeping and auditing purposes.

Testing the Integration

Test the Apple Pay integration using Priority’s sandbox environment to ensure that transactions are processed correctly. Once the integration is verified, proceed to the production environment.