Apple Pay Setup

Apple Pay requires two things to work with FloPayCheckout:

1. Domain verification — a file served from your domain that proves you own it
2. Stripe Dashboard registration — register your domain in Stripe's Apple Pay settings

1. Domain Verification File

Apple Pay requires a verification file at /.well-known/apple-developer-merchantid-domain-association on every domain that serves the checkout form.

Get the file from Stripe

1. Go to your Stripe Dashboard → Settings → Payments → Payment methods
2. Click Apple Pay
3. Click Add new domain
4. Enter your domain (e.g. checkout.yourdomain.com)
5. Download the verification file

Serve the file

Place the downloaded file in your project's public directory:

your-project/
├── public/
│   └── .well-known/
│       └── apple-developer-merchantid-domain-association
├── src/
└── ...

Next.js automatically serves files from public/ at the root URL. The file will be accessible at:

https://checkout.yourdomain.com/.well-known/apple-developer-merchantid-domain-association

Verify it works

Open the URL in a browser — you should see the file contents (hex-encoded JSON). If you get a 404, check:

• The file is in public/.well-known/ (not public/well-known/ — the dot matters)
• Your web server doesn't strip dotfiles or block .well-known paths
• If using a CDN (CloudFront, Vercel), ensure it forwards requests for /.well-known/*

2. Register Domain in Stripe

1. Go to Stripe Dashboard → Settings → Payments → Payment methods → Apple Pay
2. Click Add new domain
3. Enter your domain exactly as it appears in the browser (e.g. checkout.yourdomain.com)
4. Stripe will verify the domain by fetching the verification file
5. Once verified, the domain shows a green checkmark

3. Multiple Stripe Accounts

If you have multiple Stripe accounts (e.g. different regions), you need to:

1. Download the verification file from each Stripe account
2. The verification files may differ between accounts
3. Register the domain in each Stripe Dashboard separately

If your checkout serves multiple Stripe accounts from the same domain, you may need to use the verification file from the primary account. Contact Stripe support if you encounter issues.

4. Test vs Live Mode

• Test mode: Apple Pay works in Stripe test mode BUT requires real cards. However you won't get charged. You still need the domain verification file, but Stripe's test mode is more lenient.
• Live mode: Full domain verification is required. Apple Pay will not render without it.

5. Device Requirements

Apple Pay only renders on supported devices:

FloPayCheckout automatically detects device support and only shows the Apple Pay button when available.

6. FloPayCheckout Configuration

Apple Pay is enabled by default. No additional props needed:

<FloPayCheckout sessionId={sessionId} onComplete={handleSuccess} />

To disable Apple Pay:

<FloPayCheckout sessionId={sessionId} showApplePay={false} onComplete={handleSuccess} />

Troubleshooting

Apple Pay button not showing

1. Check device: Are you on Safari with Apple Pay set up in Wallet?
2. Check domain: Is the verification file accessible at https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association?
3. Check Stripe: Is the domain registered in Stripe Dashboard → Apple Pay?
4. Check HTTPS: Apple Pay requires HTTPS — it won't work on http://localhost
5. Check console: Open browser DevTools and look for Stripe errors

Works in test mode but not live

• Ensure the domain is registered in live mode (not just test mode) in the Stripe Dashboard
• Verify the domain verification file is from the live mode Stripe account

Multiple domains

Each domain needs its own verification:

• yourdomain.com — needs verification
• checkout.yourdomain.com — needs separate verification
• checkout.stage.yourdomain.com — needs separate verification