How Do I Set Up and Troubleshoot Apple Pay in Piano Checkout?

How Apple Pay Works in Piano

Apple Pay availability depends on a combination of factors. If any one of these fails, you may see symptoms such as a missing or greyed-out button, the Apple Pay sheet flashing and closing, checkout looping back to payment selection, or generic payment error messages.

• Checkout flow configuration — Apple Pay must be enabled and the correct provider option included. See Configure Apple Pay in Piano.

• Merchant identifier — must be correctly set via JavaScript. See Set the Apple Pay Merchant Identifier.

• Domain association file — must be hosted and publicly accessible on your site. See the Apple Pay setup article.

• Payment provider configuration — domains registered, correct credentials. See Provider-Side Setup Requirements.

• End-user eligibility — Safari on a supported OS/device, with a configured wallet. See User Experience in the setup article.

Prerequisites

Before proceeding, confirm the following:

• Your checkout page is served over HTTPS.

• You are testing on a supported Apple Pay device and browser. For full hardware and OS requirements, see the Troubleshooting section of the Apple Pay setup article.

• The user has Apple Pay set up with an active card available in their wallet.

Set the Apple Pay Merchant Identifier

Add the merchant identifier snippet before tp.start() and before any other tp.push(...) commands that might initialize checkout:

tp.push(['setApplePayMerchantId', '<your_apple_pay_merchant_id>']);

Merchant Identifier Values by Provider

The value you pass depends on your payment provider. For full details on where to retrieve this value, see the Apple Pay setup article.

Verifying the Value in Safari

In Safari DevTools Console, run tp.applePayMerchantId(). This should return the configured value. If it is missing or incorrect, Apple Pay validation will fail.

Host the Apple Pay Domain Association File

Apple Pay requires a domain verification file hosted at:

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

For provider-specific instructions on obtaining and hosting this file, see the Additional Steps for Production section of the Apple Pay setup article. Note that Payway requires a .txt extension on this file.

Requirements for the File Endpoint

The file must be accessible via a direct GET request over HTTPS, with no authentication, no IP restrictions, and no redirects. If this file is unreachable, the Apple Pay button may stay disabled and device eligibility checks may not behave as expected.

Configure Apple Pay in Piano

Enable Apple Pay on the Payment Provider Record

In Piano, confirm your Apple Pay-capable provider record has correct credentials, the right environment setting, and that Apple Pay support is enabled. For step-by-step setup instructions per provider, see the Apple Pay setup article.

Add Apple Pay to the Checkout Flow

In Manage → Checkout Flows, ensure the appropriate Apple Pay option is included in Available Payment Provider Options, such as Stripe Apple Pay or Braintree Apple Pay.

Confirm Your Checkout Template Includes Apple Pay Markup

If you use custom templates, ensure the required provider wrapper is present. For example, for Braintree:

<div class="braintree-applepay-wrapper">…</div>

Provider-Side Setup Requirements

For full setup instructions on the provider side, refer to the Apple Pay setup article. Key points to verify when troubleshooting:

Stripe

• Your domain must be registered under Payment method domains in Stripe, using your live secret key for production.

• Do not register the same domain multiple times. Include exact hostnames — www.example.com and example.com are treated as separate entries.

Braintree

• Each testing and production hostname must be added under Apple Pay → Web Domains in the Braintree Control Panel.

• Ensure the Braintree Apple Pay merchant ID matches what you pass via setApplePayMerchantId.

Datatrans / Payway

• Ensure the domain is registered in the provider dashboard, and that credentials and environment settings (sandbox vs. production) match where you're testing.

Testing and Validation in Safari

Use Safari DevTools Console to check eligibility. For full verification steps including the canMakePaymentsWithActiveCard script, see the Troubleshooting section of the Apple Pay setup article.

ApplePaySession.canMakePayments()

If this returns false, the device, browser, or user is not eligible for Apple Pay.

Check the validateMerchant Network Request

In Safari DevTools → Network, look for the validateMerchant request:

Common Issues and Fixes

Apple Pay Sheet Flashes and Closes Immediately

This is most commonly caused by a failing merchant validation. Confirm:

• The domain association file is reachable with no redirects or authentication (see Host the Apple Pay Domain Association File)

• The domain is allowlisted in your provider (see Provider-Side Setup Requirements)

• setApplePayMerchantId runs before tp.start() (see Set the Apple Pay Merchant Identifier)

• The merchant ID value matches provider requirements (see Merchant Identifier Values by Provider)

Apple Pay Button Visible but Not Functional

• Ensure the user has a payment card configured in Apple Wallet.

• Ensure the domain registration in Stripe or Braintree includes the correct subdomain (for example, www).

Apple Pay Not Appearing

• You are not on Safari or are using an unsupported device — see User Experience for hardware requirements.

• Apple Pay provider option is not included in the checkout flow — see Add Apple Pay to the Checkout Flow.

• Template is missing required Apple Pay markup — see Confirm Your Checkout Template Includes Apple Pay Markup.

• Merchant ID is not set, or set too late — see Set the Apple Pay Merchant Identifier.

Environment Mismatches (Sandbox vs. Production)

Duplicate Errors or Confusing Defaults on iOS

On iOS Safari, Apple Pay may be pre-selected by default for eligible users. If configuration is incomplete, this can result in repeated error messages. Consider adjusting which payment method is pre-selected for iOS users while validating your setup.

Notes on Frictionless Checkout and Login Dependencies

Some frictionless checkout implementations depend on passwordless login flows. If you have extensive template customizations, test Apple Pay with a default template first to isolate whether the issue is caused by template logic.

When to Escalate

If the issue persists after completing all steps above, contact Piano Support and provide:

• Safari console output for ApplePaySession.canMakePayments() and ApplePaySession.canMakePaymentsWithActiveCard(...)

• A screenshot or copy of the merchant identifier being used

• A HAR export showing the validateMerchant request and response

• The exact hostname being tested and confirmation of whether it is registered in your provider dashboard

Last updated: June 26, 2026