Register domains for payment methods
Register and verify domains to use payment methods (including Link, Apple Pay, and Google Pay) in Elements or Checkout's embeddable payment form.
For certain payment methods, you must register every web domain that shows the payment method if your integration uses Elements or Checkout’s embeddable payment form. This includes registering top-level domains and subdomains. For example, if you have the domain yourdomain.com and subdomains like shop.yourdomain.com and www.yourdomain.com, this guide explains how to register them.
After you register a domain, that domain is ready for use with other payment methods that you might enable in the future.
The following payment methods require registration:
- Google Pay
- Link
- PayPal
- Amazon Pay
- Apple Pay (additional verification step required)
Apple Pay and merchant validation
The Apple Pay documentation describes their process of “merchant validation," which Stripe handles for you behind the scenes. You don’t need to create an Apple Merchant ID or CSR. Instead, follow the steps in this guide.
Testing
You also need to register domains for testing. When testing locally, you can use a tool such as ngrok to get an HTTPS domain. You can either register in test mode, or register in live mode and the domain will also be registered in test mode automatically. Remember to register your domains in live mode before going live.
Register your domain
To register a domain, do the following:
Repeat for all domains that you need to register.
Using an iframe
- When using an iframe, its origin must match the top-level origin, except in Safari 17+. Two pages have the same origin if the protocol, host (full domain name), and port (if specified) are the same for both pages.
- When using a cross-origin iframe in Safari 17+ you must specify the
allow=“payment”attribute. To enable Apple Pay, you must also register the source domain that the iframe loads.
Verify ownership of your domain with Apple Pay
During registration, Stripe automatically attempts to verify ownership of your domain with Apple. If the domain isn’t already verified, register your domain and then follow these steps to verify your registered domain with Apple Pay.
- Download the domain association file.
- Host it at
/.on your site. For example, if you registerwell-known/apple-developer-merchantid-domain-association https://yourdomain., make that file available atcom https://yourdomain..com/. well-known/apple-developer-merchantid-domain-association
Stripe performs an initial domain verification, with requests originating from one of our webhook IPs.
Manage your domain
Using the PaymentMethodDomain API you can do the following:
- Retrieve a domain.
- See a list of all of your domains.
- Enable or disable a domain. If a domain is disabled, the payment methods no longer appear in Elements or Checkout’s embeddable payment form on that domain.
This sample shows how to disable a domain:
Register your domain while using Connect
Connect platforms must register all domains where Elements or Checkout’s embeddable payment form displays the payment methods listed above. The domain where the charge is being run needs to be registered for the user running the charge.
If the platform creates direct charges, use your platform’s secret key to authenticate the request and set the Stripe-Account header to your connected account’s Stripe ID.
If the platform creates destination charges or separate charges and transfers, use your platform’s secret key to authenticate the request and omit the Stripe-Account header.
Learn more about Making API calls for connected accounts.