Skip to main content
In the modal, the paymove payment page runs in an iframe embedded on your page. Apple lets the Apple Pay sheet start only on a domain that is registered and verified with Apple. By default only paymove domains are registered, so Apple Pay in the widget requires a one-time onboarding of your domain. BLIK and Google Pay work in the widget right away - this page is about Apple Pay only.
1

Set the domain in the product

Set metadata.merchantDomain of the product you embed in the widget.
2

Write to us

Send the domain to integration@paymove.io. We will register it with Apple and send you a verification file.
3

Publish the verification file

Serve the file at a fixed URL on your domain.
4

Wait for confirmation

Once Apple verifies the domain, we will confirm the registration - from then on Apple Pay works in the modal.

​
1. merchantDomain in the product

merchantDomain is the domain of the page where you paste the widget script - the one the customer sees in the address bar. Not the paymove domain from the script URL. The most convenient way is to set it when creating the product:
You add it to an existing product with an update. Mind two differences compared to creating a product:
  • In the update the field is called productMetadata, not metadata. A body with metadata returns 200 but changes nothing - unknown fields are ignored.
  • productMetadata replaces all metadata of the product. Include every field you have already set (locale, logoUrl and the rest) - omitted ones will be cleared.
If you don’t manage the product through the API, include the domain in your step-2 message - we’ll set merchantDomain on our side.
Rules:
  • Domain only - without https://, port, path or trailing slash: foundation.example.com. If you send a full URL, the API keeps only the domain and converts it to lowercase. A value from which no valid domain can be extracted results in 400.
  • Exactly the domain the page runs on. example.com and www.example.com are two different domains for Apple - use the one under which the customer actually sees the page (and ideally redirect the other one to it).
  • One domain per product. If the same product should work in the widget on several domains, write to us - each domain has to be registered with Apple separately.
  • localhost and domains without public HTTPS won’t pass Apple’s verification. Test Apple Pay on a domain reachable from the internet.

​
2. Domain registration request

Write to integration@paymove.io and provide:
  • the domain (or domains) where you embed the widget,
  • the product IDs (productId) that will run there,
  • the environment - sandbox, production or both.
We will register the domain with Apple for paymove’s merchant identifier and send you a verification file generated for your domain.
You can’t generate the file yourself in your Apple Developer account - it is tied to the Apple merchant identifier owned by paymove. You don’t need your own Apple Developer account.

​
3. Verification file

Serve the file you received at exactly this URL:
Apple checks it automatically, so it must be:
  • available publicly over HTTPS, without login, geo-blocking or bot protection (Cloudflare challenge, WAF),
  • at exactly this path - the .well-known directory in the domain root, file name without an extension,
  • served without a redirect (status 200, not 301/302),
  • unmodified - don’t edit it or change its encoding.
Check it before reporting that it’s ready:
The expected result is HTTP/2 200 and the file contents from the first byte. Example configurations:
Don’t remove the file after verification. Apple may check the domain again, and a missing file will disable Apple Pay in the widget.

​
4. Confirmation and testing

Once the file is in place, let us know - we will ask Apple for verification and confirm the result. Then test a payment:
  • in Safari on an iPhone, iPad or Mac with a card added to Apple Wallet - Apple Pay does not show in other browsers,
  • on a page under the registered domain - a test version under another domain (e.g. staging.example.com) needs a separate registration.

​
What happens without registration

Until the domain is registered, Apple rejects the payment session: the customer chooses Apple Pay, but the payment sheet doesn’t open or closes with an error. Other methods work normally. If you don’t plan to register, disable Apple Pay for the product embedded in the widget - write to us and we will do it for you. Registration is not needed when the customer pays outside the widget - on the payment page opened from a link or a QR code, the Apple Pay sheet shows on the paymove domain.
The same procedure applies to the checkout widget. If you embed both widgets on one domain, report it in a single message - list all products that should work there.