Apple Pay

Apple Pay requires additional setup before it can be shown to customers in checkout.

To enable Apple Pay on the web, your platform or merchant must:

• host a domain verification file on the website
• register the domain with Paypercut using the API

Until both steps are complete, Apple Pay may not be available in checkout.

Why Apple Pay requires setup

Apple Pay on the web requires each website domain to be verified before it can be used for payment presentation.

Step 1: Download the verification file

The static download remains available during the gradual rollout of dynamic file retrieval. Existing integrations can continue using the static file. For integrations using the dynamic flow, retrieve the file for the account, test/live mode, and exact domain as described below.

Static verification file

Download the Apple Pay domain verification file:

https://cdn.paypercut.io/.well-known/apple-developer-merchantid-domain-association

Download the Apple Pay verification file

Dynamic verification file

Your backend or deployment process can retrieve the verification file through the Apple Pay domain association API before registering the domain. The response contains the file selected for your account and test/live mode, including any existing or pending registration for the supplied hostname.

Use your API key with the same account and test/live mode when retrieving the file and registering the domain. Platforms acting for a connected account must select that account with the Paypercut-Account header on both requests.

Send the bare hostname in domain_name, without https://, a port, or a path:

curl --fail-with-body --get \
  'https://api.paypercut.io/v1/apple-pay/domain-association' \
  --header "Authorization: Bearer $PAYPERCUT_SECRET_KEY" \
  --data-urlencode 'domain_name=shop.example.com' \
  --output apple-pay-association.json

The API returns JSON. The content below is illustrative; use the complete value returned by your request:

{
  "object": "apple_pay_domain_association",
  "domain_name": "shop.example.com",
  "path": "/.well-known/apple-developer-merchantid-domain-association",
  "content_type": "text/plain",
  "content": "EXAMPLE_ASSOCIATION_FILE_CONTENT\n"
}

After a successful response, extract content into the verification file. With jq, use --join-output to avoid appending an extra newline:

jq --join-output '.content' apple-pay-association.json \
  > apple-developer-merchantid-domain-association

Publish only the extracted content, preserving its whitespace and line endings. Do not publish the JSON response, Base64-decode the content, trim it, or reformat it. Continue with Step 2 to serve the file at the returned path with the returned content_type. If your application serves the file dynamically, retrieve the file from your backend and return only the file content at the public URL.

Include domain_name when preparing a particular storefront. Omitting it returns the account/mode default without checking that hostname. Retrieve the file for each domain and mode you are registering; do not assume another account's or mode's file is suitable.

Step 2: Host the verification file

Host the file at the following path on the exact domain that will display Apple Pay:

https://your-domain/.well-known/apple-developer-merchantid-domain-association

The file must return HTTP 200 over public HTTPS without requiring authentication. For the dynamic flow, serve it with the returned content_type (text/plain).

Step 3: Register the domain

After the file is hosted, register the domain with Paypercut.

For the dynamic flow, use the same domain_name, account, and test/live mode as the discovery request. Retrieving the file does not register or verify the domain. Domain registration starts verification; an accepted request does not mean Apple Pay is ready to display.

POST /v1/payment_method_domains

Payment Method Domains API

When to register a domain

Register a domain when:

• you are showing checkout on your own website
• you are adding a new production or staging domain that will display Apple Pay

You should register each relevant domain separately.

Subdomains and iframe integrations

If Apple Pay is shown on more than one domain or subdomain, each one may need to be registered separately.

Examples:

• checkout.example.com
• pay.example.com
• www.example.com

For embedded or iframe-based integrations, the top-level domain and the iframe source domain may both need to be registered, depending on how checkout is rendered.

Merchant and platform responsibilities

Depending on your integration model, the verification file may be hosted by:

• the platform
• the merchant
• a plugin or storefront integration

Your integration is responsible for ensuring that:

• the file is hosted correctly
• the domain is registered through the API
• Apple Pay is not expected to work before verification completes

Plugins and storefront integrations

If you are using a plugin or storefront integration, Apple Pay may still require domain verification.

Today, this setup may need to be completed manually.

Troubleshooting

For the dynamic flow, handle discovery errors before publishing or replacing a file:

If Apple Pay does not appear in checkout:

• confirm that the verification file is hosted on the correct domain
• confirm that the domain has been registered through the API
• confirm that checkout is rendered on the registered domain
• confirm that Apple Pay is supported in the customer’s browser and device environment

Related references

• Retrieve the Apple Pay domain association file
• Payment Method Domains API