Apple Pay Registration

Apple Pay is a fast, easy, and secure way to pay accepted by over 85% of retailers in the U.S. Apple Pay enables users to add bank and credit cards to their phones for secure payments at stores. Card numbers are converted to unique, secure numbers stored on the phone's chip for safer transactions. Apple Pay replaces the need for customers to take a physical card or type in personal information during sales.

Apple Pay functionality is built into our existing platform requiring little-to-no development work, with three easy integration options for embedded payment options like PayFrame and PayFields and contactless payment terminals.

Compatibility

Apple Pay is compatible with Apple devices, Windows devices, and other devices in third-party browsers. 

The minimum requirements for testing or accepting Apple Pay are:

• Meeting Apple’s minimum requirements and guidelines.

• Devices compatible with Apple Pay

• Add at least one credit or debit card to the cardholder’s Apple Wallet.

• Domain Registration

Domain Registration

As a Referrer, you can register one or multiple Merchants for Apple Pay using the Portal. Domain registration involves providing each Merchant’s web domain to Apple for server call authorization, enabling transaction verification for Apple Pay. Host a file on your website for Apple to verify your domain, ensuring eligibility for Apple Pay integration.

An acceptable Merchant domain for Apple Pay is a public URL with a valid SSL certificate, using a secure HTTPS protocol.

The following sections guide you through the steps for enabling Apple Pay, including registration and domain whitelisting, for both single-merchant and multi-merchant enablement.

1. Initiate the Apple Pay Registration.

2. Configure the Domains.

3. Enter the Domains for Apple Pay.

4. Register with Apple Pay.

1. Initiate the Apple Pay Registration

Follow these steps to initiate the Apple Pay registration for your Merchants domains linked to each Merchant’s website.

1. Access the Payment Methods page from Settings.

2. Click Enable on the Apple Pay panel to initiate the registration process by configuring the domain.

2. Configure the Domain

Here, you’ll need to configure each domain and register it with the Apple Pay service. This is a crucial step in validating the Merchant for future transactions, ensuring the security of both the Merchant and the cardholder.

Important!!

You must meet the following Apple Pay domain configuration requirements:

• Your website URL must be publicly accessible and cannot be set to localhost.

• Your website must begin with https and have a valid SSL certificate for secure communication.

1. Download the domain association file: Sandbox | Production

2. Host the file here: {baseURL}/.well-known/apple-developer-merchantid-domain-association
   

Result: After you successfully hosted the domain configuration file and have the domains you need to register with the Apple Pay service, proceed to the Enter Domain section.

3. Enter the Domains for Apple Pay

After completing the steps above, the Apple Pay service will search each website's specific URL path: /.well-known/apple-developer-merchantid-domain-association for the matching file once the registration is initiated from the Portal.

To begin, follow the steps below:

Bulk Upload (CSV)

Bulk Upload allows you to upload a pre-configured CSV file containing domain and Merchant ID pairings.

The registration system selects and registers each merchant listed in the CSV file upon completing the "Register with Apple Pay" steps.

Tip

Download a sample Bulk Upload CSV file here: apple-pay-merchant-domains.csv

It is recommended to download your true domain registration file from the Portal as it is pre-populated with your portfolio’s Merchant IDs. If there are multiple domains, each domain should be separated and added to each applicable row, as shown in the example below.

1. Select Bulk Upload (CSV) from at the top of the page.

2. Click the Template File Download button for a CSV file to add each applicable domain(s).

3. Add the applicable domain. If there are multiple, add them to each relevant row like the example below:

4. Using the Template File Upload prompt, upload your completed CSV file to the Portal.

5. Click Continue to proceed to the Register with Apple Pay section.

4. Register With Apple Pay

When you click Register in the Register with Apple Pay section, each domain registration file uploaded to the provided domains is compared against the domains provided to Payrix Pro. Apple Pay swiftly verifies each domain by cross-referencing files, typically completing the process within seconds.

Note
If you receive a failure message, see the Apple Pay Registration Failure Messages section below for troubleshooting steps.

Result: After registration is completed, you’ll see an on-screen notification based on your method of enablement:

Merchant registration process is complete.

Your Merchants are now able to start accepting Apple Pay payments.

Enabled: # | Failed: # | Pending: #

Domain Validation Check - Registration Verification

To manually validate that the Merchant domain has been properly verified and that Apple Pay is enabled for that Merchant, you can optionally run the following API call shown in the expandable content below:

/applePayValidation/{id} - Request & Response Snippets

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

CODE

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

Request Body Parameters:

Parameter	Description
{{apple_pay_domain}}	The full domain hosting your Apple Pay domain registration file(s) is used to validate the domain to ensure the Apple Pay service is approved for use by Apple itself.

Example Response Body

CODE

{
  "epoch Timestamp": 1703096936817,
  "expiresAt": 1703100536817,
  "merchantSessionIdentifier": "SSHAE307774E06A4F8AA003ECE385F65EF7_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
  "nonce": "1c7ec01c",
  "merchantIdentifier": "A18AF97960823C2C2BC19BB3C2C03CA1E81329C172D06EF14CD28B924A9E579F",
  "domainName": "https://payrix-apple-pay.{{apple_pay_domain}}.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.

Apple Pay Registration Failure Messages

Throughout the mass enablement process, you might face issues or errors that could result in one or more of your Merchants being unable to accept Apple Pay transactions.

The following messages pertain to unsuccessful Merchant domain registrations that receive a FAILED status, outlining specific issues encountered and providing instructions for resolution.

Message	Issue	Troubleshooting Steps
Configuration File Not Found	The configuration file for the Merchant's domain is not located where it is expected.	Add the missing configuration file to the Merchant domain. Check the configuration file location is: https://{merchantBaseURL}.well-known/apple-developer-merchantid-domain-association
Unexpected Configuration File Contents	The contents of the domain configuration file do not align with the expected contents hosted by the service or are not readable.	Ensure that the domain URL has public, read permissions for the configuration file.
Domain Configuration Failed. Try Again.	The domain configuration file is missing the required Merchant ID(s), Domain(s), or both from the Bulk Upload CSV file.	Review the domain configuration CSV to identify the missing or incorrect information. Click the Back button on the Register with Apple Pay section to return to the Bulk Upload CSV file upload prompt. Repeat the upload and re-try the registration step. If you’re still having issues here, contact Support for additional assistance.
Access Denied, Unauthorized	The Merchant domain is not accessible without authorization.	Ensure that reading the configuration file does not require any authorization.
Timeout	Apple's Merchant Registration API failed to register and verify the domain within the anticipated timeframe.	Retry the registration process from the Apple Pay domains details page, accessible by clicking on a listed Merchant from the Apple Pay Mass Enablement table.
Bad request	Portal or client sent an invalid request	Escalate to Support for further investigation. Note: Retry option is unavailable.
Internal Server Error	Internal server errors that occur either in connection with the Apple registration service or the registration service of this platform.	Wait and retry if available, and escalate if failure is persistent. Escalate to Support for further investigation.

Integrate Apple Pay Into Your Webpage

Our platform Apple Pay integration offers three methods to display the Apply Pay payment button:

1. PayFields provides a highly customizable embedded payment form solution.

2. PayFrame offers a swift integration using the platform-hosted payment form.

3. The standalone button displays only the embedded Apple Pay button using PayFields.

Manage Your Merchant Apple Pay Registrations

When onboarding new merchants to your portfolio, you must register each one for the Apple Pay service. Select Payment Methods from the Settings page to access the Apple Pay Registration management dashboard. This dashboard offers a simplified registration process, allowing you to manage registrations seamlessly without causing any interruptions to the operations of previously registered merchants.

Tip

To register newly onboarded Merchants or another existing, non-registered Merchant to domains you’ve already configured, bypass the domain configuration step. Instead, update and re-upload your domain registration CSV file with the new Merchant information.

Note

To register a new domain, you’ll need to perform the above steps again, including configuring domain configuration, providing and registering the domain.

The Apple Pay registration table shown in the Payment Method section of Settings, allows you to see a consolidated table of Merchants that have successfully been registered, Merchant IDs, their associated domains, and their Apple Pay enablement status:

Apple Developer Apple Pay Error Resources

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

Payment Data Decryption for Currently Registered Merchants

For Merchants that have registered directly with the Apple Pay payment service through the steps outlined in the Apple Pay Merchant Integration Guide provided in Apple’s developer documentation, you’ll need to decrypt the payment data captured by the service for the Payrix Pro platform to successfully read and accept the payment data when using the /txns endpoint.

Important!

If you are currently enrolled in Apple Pay using an independent Apple Developer Account with registered Merchants, you must provide ongoing support for their payment token decryption operations and manually resubmit transaction payment information using a conventional /txns endpoint request.

To decrypt payment data, follow the steps provided in the Apple Pay Payment token format reference guide.

Tip

For the best experience, unregister each relevant Merchant from the Apple Pay Web Merchant Registration first. Then, re-register the Merchants using the Domain Registration guidelines above.

This process allows Payrix Pro to handle payment data decryption automatically and aims to enhance the seamless transfer of encrypted payment information to the payment processor, Worldpay.

Additional Resources from Apple

• Apple Pay Merchant Integration Guide

• Payment Token Reference

• Decrypting Payment Data

• Unregistering a Merchant