ProvisioningEOS APIs
Provisioning

Apple Pay Integration

This guide provides a step-by-step process for enabling Apple Pay with Vortex, simplifying integration with an Apple Pay button, merchant identifier file, and an implementation guide for seamless checkout experiences.

Suggest Edits

Introduction

Apple Pay offers a fast, secure, and easy way for customers to complete transactions on your website. By integrating Apple Pay with Vortex, you enhance the checkout experience, reducing friction and increasing conversion rates. This guide will walk you through the process of enabling Apple Pay for your online store using Vortex, simplifying key steps and ensuring a smooth integration.

In this guide, you’ll discover 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. You don’t need to follow the manual merchant validation process outlined in Apple’s documentation; instead, follow these streamlined steps:

Steps for Domain Association

  1. Save the Domain Association ID

PRTH provides a pre-configured domain association id to simplify your setup. Save this ID:

7b2276657273696f6e223a312c227073704964223a2236423941383537323431454241453339444337383437374142453845413443364235373132324331464239434531323235344532314146393736433035444446222c22637265617465644f6e223a313733323132303831363731387d

Hosting the ID

Host it on your website’s server at the following path: /.well-known/apple-developer-merchantid-domain-association.

For instance, 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.

  1. Register Your Domain with PRTH

Once the domain association file is hosted, notify PRTH to register your domain with Apple. You can do this directly 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 https://api.prth.com/v1/payment_method_domains \
-u "live_api_key_here:" \
-d domain_name="yourwebsite.com"

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

  1. Begin Apple Pay Transactions

After PRTH registers your domain with Apple, you’ll be able to start accepting Apple Pay payments on your site using your live API keys. No further action is needed on your end for merchant validation.

Why is this step important?

By following these steps, PRTH takes care of the complex Apple Pay merchant validation process for you. This setup ensures that your domain is fully validated and ready to process Apple Pay transactions, reducing integration complexity and allowing you to focus on enhancing the customer checkout experience.

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

To enable Apple Pay on your website using Vortex, the first step is to integrate the Apple Pay button into your checkout page. This process involves working on the client side and ensuring your website complies with Apple's requirements.

  1. Ensure HTTPS is Enabled

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

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

  1. Set Up Payment Request

When a customer clicks the Apple Pay button, initiate a payment request using the following basic structure:

var request = {
    countryCode: 'US',
    currencyCode: 'USD',
    total: {
        label: 'Your Store Name',
        amount: '10.00' // Total amount for the transaction
    }
};

Ensure you configure the request to reflect your specific business needs, such as country code, currency, and total amount.

  1. 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 more details on customizing the Apple Pay button and initiating payment requests, please refer to Apple’s official Apple Pay Web Merchant Registration API Documentation.

Step 3: Implementing Apple Pay with Vortex

Please, check the API Reference documentation for this implementation.

Now that you have integrated the Apple Pay button and validated the merchant, the final step is to handle the transaction using Vortex. This involves sending the encrypted payment payload from Apple Pay to Vortex, ensuring the transaction is processed correctly.

How to Implement Apple Pay with Vortex

  1. Configure Payment Requests in Vortex:

After adding the Apple Pay button, configure the payment request so that Vortex can process the transaction.

var paymentRequest = {
    merchantCapabilities: ['supports3DS'],
    supportedNetworks: ['visa', 'masterCard', 'amex'],
    countryCode: 'US',
    currencyCode: 'USD',
    total: {
        label: 'Your Store Name',
        amount: '10.00'
    }
};
  1. Merchant Validation with Vortex:

Your server must validate the merchant using Vortex’s system

var validationURL = event.validationURL;
fetch('https://your-vortex-server/merchant-validation', {
    method: 'POST',
    body: JSON.stringify({ validationURL: validationURL })
}).then(function(response) {
    return response.json();
}).then(function(session) {
    event.completeMerchantValidation(session);
});
  1. Send Transaction Payload to Vortex (Priority):

After acquiring the encrypted payment payload from Apple Pay, construct a new payload to be sent to Vortex’s system (referred to as "Priority"). This step ensures that the transaction is securely processed through Vortex.

Transaction Payload Structure

Ensure the payload defines the following fields:

  • provider: Set this to "Apple_Pay" to indicate that the platform is using Apple Pay.
  • tenderType: Set this to "Card" as Apple Pay transactions use card payments.
  • amount: The final transaction amount.
  • posData: Specifies the transaction data for POS. For Apple Pay transactions, this includes:
    • terminalId: Example, "001"
    • transactionType: Example, "Purchase"
  • cardAccount: Contains the mobileWallet object, which holds the encrypted payment token sent by Apple Pay.
  • merchantId: This is the Vortex merchant ID for the Checkout platform.
    Note: Do not input your Apple Pay merchant ID here.

Example:

var transactionPayload = {
    provider: 'Apple_Pay',
    tenderType: 'Card',
    amount: '10.00',
    posData: {
        terminalId: '001',
        transactionType: 'Purchase'
    },
    cardAccount: {
        mobileWallet: {
            encryptedPayload: event.payment.token
        }
    },
    merchantId: 'your-vortex-merchant-id'
};
  1. Authorize the Payment with Vortex:

Send the transaction payload to Vortex’s payment authorization endpoint:

fetch('https://your-vortex-server/payment', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer yourAccessToken',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(transactionPayload)
}).then(function(response) {
    if (response.status === 200) {
        event.completePayment(ApplePaySession.STATUS_SUCCESS);
    } else {
        event.completePayment(ApplePaySession.STATUS_FAILURE);
    }
});
  1. Handling the Transaction Payload:

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

Testing the Integration

Make sure to test the Apple Pay integration using Vortex’s sandbox environment. This will ensure that transactions are processed as expected before going live.

Updated about 1 year ago