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:

PayFrames
PayFields
Standalone button

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:

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.

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:

Request Headers and URL:

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

Path Parameter:

Parameter	Description

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

Request Body

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

Example Response Body

{
  "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"
}

Setup PayFrames for Apple Pay

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

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:

Example PayFrame Setup

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.

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

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.

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

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

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

Example PayField Code

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:

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:

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.

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.

Payrix Resource Center