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 (www.exampledomain.com), not including https:// 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: Host the file at /.well-known/apple-developer-merchantid-domain-association. For example, if you register https://example.com , make that file available at https://example.com/.well-known/apple-developer-merchantid-domain-association.

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

To confirm you configured correctly: 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.

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

Apple Pay Domain Validation and Enablement Verification

To validate that the Merchant domain has been properly verified and that Apple Pay is enabled for that Merchant, you can run the following API call:

Click here to see the Apple Pay Validation API request.

Request Headers and URL:

CODE

POST /applePayValidation/{id} HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

Path Parameter:

Parameter	Description
`{id}`	The Merchant ID for the Merchant validating their domain has been verified by the Apple Pay service.

Request Body

JSON

{
  "validationDomain": "{{apple_pay_domain}}"
}

Example Response Body

JSON

{
  "epoch Timestamp": 1703096936817,
  "expiresAt": 1703100536817,
  "merchantSessionIdentifier": "SSHAE307774E06A4F8AA003ECE385F65EF7_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
  "nonce": "1c7ec01c",
  "merchantIdentifier": "A18AF97960823C2C2BC19BB3C2C03CA1E81329C172D06EF14CD28B924A9E579F",
  "domainName": "https://payrix-apple-pay.herokuapp.com",
  "displayName": "Dine in Vines, Inc.", 
  "signature":
    "ZZ8006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e330820388a00302010202084c304149519d5436300a06082a8648ce3d040302307a3 
    011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3139303531383031333235375a170d3234303531363031333235375a305f3125302306035504030c1c6563632d736d702d62726f6b657
    22d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3
    d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d300c0603551d130101ff0
    4023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f6
    3737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636
    572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206±6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e64697
    4696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2
    f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726
    c301d0603551d0e041604149457db6fd57481868989762f7e578507e79b5824300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020349003046022100be09571fe71
    e1e735b55e5afacb4c72feb445f30185222c7251002b61ebd6f55022100d18b350a5dd6dd6eb1746035b11eb2ce87cfa3e6af6cbd8380890dc82cddaa63308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8
    648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a417
    0706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e7465677"
}

Note: If the format of your response body looks similar to that of the example above, this indicates a successful validation with some additional info like the domain verification expiration date and unique Merchant’s ID on the Apple Pay service and unique signature.

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: