Apple Pay Registration

Apple Pay is a fast, easy, and secure way to pay that’s accepted by over 85% of retailers in the U.S. Apple Pay replaces the need for your customers to take a physical card or type in personal information during the sales process.

Apple Pay functionality is built into our existing platform and requires little-to-no development work, with three easy integration options:

These options include everything you need to directly implement the Apple Pay solution into a checkout flow for a fully customizable customer experience.

Note: Cardholders must have a credit or debit card set up in their mobile Apple Wallet to use Apple Pay.

Compatible browsers and devices

Apple Pay is compatible with the Safari browser and does not work with Microsoft Edge/IE or Google Chrome. We recommend downloading the latest version of Safari available, as noted below.

Safari on Mac running macOS Sierra or later
Mobile Safari on iOS 10.1 or later
Accepted Apple Device - Apple is compatible with iPhone, iPad or Mac, which have thumbprint or facial recognition capabilities.

Safari supports Apple Javascript libraries (which are native to the Safari browser) so Apple Pay is not available in other web browsers.

Click here to view a list of all Apple devices compatible with Apple Pay.

Apple Pay Registration and Domain Whitelisting

Domain whitelisting means to provide your web domain (https://www.exampledomain.com) to Apple in order to authorize server calls from Apple’s Apple Pay service. Domain whitelisting is required for Apple to validate transactions being processed by the authorized entity. To provide this whitelisting capability, you’ll be required to host a specific file on your website and make it accessible via a secure URL.

This file is used for domain verification by Apple Pay's service to ensure the legitimacy of your website. Here are the key requirements and steps to prepare your website and codebase before initiating the Apple Pay registration process.

Requirements for Apple Pay Registration:

Your website URL cannot be set to 'localhost,' as it needs to be publicly accessible.
Your website must have a valid SSL certificate, beginning with https, for secure communication.

This verification ensures that a website is eligible for Apple Pay integration, providing a secure payment experience for partners, merchants and their customers. To begin accepting Apple Pay, contact your service provider or self-register using the Portal to begin accepting payments:

Click here to see all Apple Pay Registration and Domain Whitelisting steps.

Step 1: Navigate to Settings from the main Dashboard, under the Admin category. Then, click Payment Methods.

Step 2: On the Payment Methods page, click the START REGISTRATION button under the Apple Pay section.

Step 3: Click the Download link under “Download the File” to have the domain registration file downloaded.

Note: You can also manually download the required domain registration file using the links below:

Step 4: Open the Merchant’s website package in an IDE or file browser, and create a new folder within the website’s static folder titled .well-known.

Step 5: Open the downloaded domain registration file from earlier in a text editor and copy the contents of the file.

Step 6: In the .well-known folder, create a new file and paste the contents copied from the domain registration file. Then, save this new file as apple-developer-merchantid-domain-association.

Step 7: Download the received from the Portal against the following URL: /.well-known/apple-developer-merchantid-domain-association.

Step 8: Visit {baseURL}/.well-known/apple-developer-merchantid-domain-association to test if the file automatically downloads with the matching domain registration contents matching the original file downloaded from the Portal.

Step 9: Return to the Portal Payment Methods page and click the APPLEPAY - REGISTER ALL button to complete the registration.

Result

Once the requirements have been met and you’ve initiated the registration process, the following system actions will occur:

The registration process will search your website for a specific URL path: /.well-known/apple-developer-merchantid-domain-association.
Once found, the registration file downloaded from this URL. This is the file that is being stored in the codebase, previously downloaded from Payrix.
Apple Pay will then compare the downloaded file from your website to the reference copy it has on record from Payrix
If the files match, Apple Pay will instantly verify your domain, a process that usually takes no more than several seconds.

Setup PayFrames for Apple Pay

When enabling Apple Pay, the payment options will automatically display within the PayFrame without requiring additional integration work.

Click here to learn how to integrate PayFrames into your website.

For additional guidance, set up your PayFrame inside the sandbox view so you can preview how to embed the button inside the frame.

To test, use this code snippet to create a test PayFrame and replace it with your own API Key and desired Merchant ID when creating your finalized PayFrame:

Click here to see a completed PayFrame setup code for HTML.

Example PayFrame Setup

HTML

<script type="text/javascript" src="https://test-api.{domain}.com/payFrameScript"></script> 
<script> 
  PayFrame.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p"; 
  PayFrame.config.merchant = "t1_mer_123ab4c567defg8h90123i45"; 
  PayFrame.config.hideBillingAddress = false; 
  PayFrame.config.amount = 100; 
  PayFrame.config.color = "c351e8"; 
  PayFrame.config.mode = "txn"; 
  PayFrame.config.txnType = 'sale'; // Setting Transaction type to sale
</script>

Setup PayFields for Apple Pay

For clients using PayFields, there is a simple and easy solution to add the Apple Pay payment option to your checkout flow.

Click here to learn how to integrate PayFields into your website.

PayFields will allow your customers to select to input their card information or utilize Apple Pay at the point of sale.

Click here for PayFields Apple Pay Integration steps.

Step 1: Register for Apple Pay using the Apple Pay Registration and Domain Whitelisting steps above.

Step 2: (Optional) Create a new PayField if you don’t have an existing one.

Step 3: Add the Apple Pay JavaScript within the <head> tag.

HTML

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

Step 3B: Add the Apple Pay button within the <body> tag.

HTML

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

Step 4: Style the button with the following CSS properties or adjust as desired.

HTML

<style>
    apple-pay-button {
      --apple-pay-button-width: 150px;
      --apple-pay-button-height: 30px;
      --apple-pay-button-border-radius: 3px;
      --apple-pay-button-padding: 0px 0px;
      --apple-pay-button-box-sizing: border-box;
    }
</style>

Step 5: Test the button and confirm the transaction is successful in your Merchant’s Portal or using the API.

PayField example is available on Safari browsers.

Example PayField Code

HTML

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script type="text/javascript" src="https://api.payrix.com/payFieldsScript"></script>
  <script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
  <title>PayField Testing</title>
</head>
<body>
  <apple-pay-button buttonstyle="black" type="plain" locale="en"></apple-pay-button>
  <div id="submit">
    <!-- Button needed for PayFields -->
  </div>
<script>
    PayFields.button = {element: "#submit", value: "Pay"};
</script>
<script>
  PayFields.fields = [
    {type: "number", element: "#number"},
    {type: "cvv", element: "#cvv"},
    {type: "name", element: "#name"},
    {type: "address", element: "#address"},
    {type: "expiration", element: "#expiration"}
  ];
</script>
<script>
  PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p";
  PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45";
  PayFields.config.amount = 500;
  PayFields.config.txnType = ‘sale’;  
</script>   
<script>
  PayFields.customizations = {
    style: {
      ".input": {
        color: "#555",
        font: "14px Arial, Helvetica, sans-serif",
        background: "white"
      }
    }
  }
</script>
</body>
<style>
    apple-pay-button {
      --apple-pay-button-width: 150px;
      --apple-pay-button-height: 30px;
      --apple-pay-button-border-radius: 3px;
      --apple-pay-button-padding: 0px 0px;
      --apple-pay-button-box-sizing: border-box;
    }
</style>
</html>

Standalone Apple Pay Button

To provide you with greater control of the checkout experience for your merchants, we offer a “standalone” Apple Pay button option. This solution allows you to implement Apple Pay into your existing PayField integration and strip away all other PayField elements except for the Apple Pay button (for supported browsers).

After you complete the registration and whitelisting process with Apple, you can build your custom Apple Pay solution:

Click here to see Apple Pay standalone button configuration steps.

Step 1: Create a PayField and add the standalone button

Step 2: Add the Apple Pay button using the code below in your <body> tag:

HTML

<body> 
... {Your HTML Body}
  <script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
  <apple-pay-button buttonstyle="black" type="plain" locale="en"></apple-pay-button>
</body>

This will style the button as shown in the example below, then can be implemented and customized to match your checkout flow.
Note: The <script> cdn for Apple Pay SDKs must be placed in the <body> tag, and not <head>.

Step 3: Style the button.

Note: You can also use these parameters in a separately linked package CSS file.

CODE

<style>
    apple-pay-button {
      --apple-pay-button-width: 150px;
      --apple-pay-button-height: 30px;
      --apple-pay-button-border-radius: 3px;
      --apple-pay-button-padding: 0px 0px;
      --apple-pay-button-box-sizing: border-box;
    }
</style>

Step 4: Test your solution and confirm you are able to create a successful Apple Pay transaction. If you are having trouble, please contact customer support.

At this point in the implementation, you can choose to delete all PayFields related HTML input fields to allow you to embed just the button into your existing website HTML.

Example Standalone Button Code

HTML

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script type="text/javascript" src="https://api.payrix.com/payFieldsScript"></script>
  <title>Standalone Apple Pay Testing</title>
</head>
<body>
  ... {Your HTML Body}
  <script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
  <apple-pay-button buttonstyle="white-outline" type="plain" locale="en" style="display: block;"></apple-pay-button>
<script>
  PayFrame.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p"; // Merchant API Key
  PayFrame.config.merchant = "t1_mer_123ab4c567defg8h90123i45"; // Merchant ID 
  PayFrame.config.amount = '500'; // Transaction Amount
  PayFrame.config.txnType = 'sale'; // "Sale" Transaction Type 
</script>
</body>
<style>
    apple-pay-button {
      --apple-pay-button-width: 150px;
      --apple-pay-button-height: 30px;
      --apple-pay-button-border-radius: 3px;
      --apple-pay-button-padding: 0px 0px;
      --apple-pay-button-box-sizing: border-box;
    }
</style>
</html>

Additional Resources

Apple Pay - Frequently Asked Questions

What is Apple Pay?

Apple Pay allows cardholders to add their eligible bank credit or debit cards to their phone to pay at participating retailers. When the card is added to your iPhone, the card number is converted to a unique number secured on a chip inside the phone. When you make a purchase, the merchant is passed this number instead of your card information, making the payment more secure.

What devices can I use with Apple Pay?

Apple Pay is available in iPhone 6 and later models, iPad and Apple Watch.

Is Apple Pay secure?

Yes. Apple introduced a two-part security solution for Apple Pay. You must approve the transaction using biometric authentication. Plus, your credit card information is never stored on the device.

Will I be charged a fee for Apple Pay?

No, there is no additional charge to offer or use Apple Pay

Does Apple Pay work Online and In-Store?

Yes. Apple will work as a contactless payment solution in-store using an Apple Pay-enabled device, as well as in an eCommerce environment utilizing the Apple Device verification and authentication feature.

How Do I Offer Apple Pay?

For a card-present or retail environment, your payment terminal must be enabled to accept Apple Pay and contactless payments.

For an eCommerce environment, the partner/merchant must register their domain with Apple and implement the payment solution into the checkout flow. Payrix offers Apple pay in all of its current online payment solutions and the option to create a custom solution tailored to your company's brand.

Will it work on my Android phone or Chrome browser?

No, Apple Pay is only compatible with Apple devices and the Safari browser.

Can I use Apple Pay to create an Auth/Capture workflow?

No, Apple Pay is only used to run a SALE for cardholders.

Will Apple Pay create a token that I can save for my cardholders

Currently, the application does not support the creation of a separate and unique token for future use when using Apple Pay.

Apple Pay - Error Codes and PayField Callback Responses

See a list of Apple Pay error codes that could be returned from the Apple Pay server by visiting the ApplePayErrorCode Apple Developer Documentation.

PayField Response	Description
`onSuccess`	This callback function will execute only if the payment was successfully submitted. Example: Use `onSuccess` to customize a customer message indicating that their payment was successfully processed. A common example of a use for this function is to
`onFailure`	This callback function will execute only if a payment fails. This means, if the payment form was submitted, and a request to process the payment was sent to the API, but the transaction failed, the `onFailure` function will be initiated. Example: A payment request was submitted to the API, but the bank declined the charge, triggering the `onFailure` function. For example,
`onValidationFailure`	This callback function will execute only if PayFields returns an error, and cannot send a payment request to the API. Example: A customer attempts to submit a payment, but leaves the `number` field blank, triggering the `onValidationFailure` function.
`onFinish`	This callback function will execute whenever the API has completed a payment submission, whether the payment was successful or not.

Apple Pay - Card Not Present, Card Present, and Blueooth Compatibility Information

Card Not Present (CNP)

Apple Pay is an innovative way to remove friction from the online checkout process, creating a fast, secure way for your customers to make payments online. It also improves security by utilizing biometric cardholder authentication and removing the need to input card data. We will work with you to create a customized Apple Pay solution to meet your needs.

Card Present (CP)

For “brick and mortar” customers accepting card-present transactions, Apple Pay enables retail transactions. This option reduces friction at the point of sale, provides a contactless solution with multiple checkout options, increases sales, and improves your customer experience.

Apple Pay - Set up Example Videos

Apple Pay Registration Example

PayFrame Example

PayField Example

Standalone Button Example

Apple Pay - PayFrame Example Screenshots

Example Cardholder View Demo: