Apple Pay on the Web: merchant-hosted payment page, Register Merchant API, eligibility checks, and who decrypts the token

App & System Services Apple Pay
Sahil_T OP
Created
Replies 1
Boosts 0
Views 23
Participants 2

We are an acquirer and PSP with our own payment gateway. Merchants can either:

  1. Use an Apple Pay payment page hosted by us, or
  2. Host their own payment page and submit payment data to us via server-to-server APIs.

We are currently implementing Apple Pay on the Web using the Platform Integrator model. The acquirer-hosted payment page flow is clear to us, but we have a few questions regarding merchant-hosted payment pages.

Our current understanding (please correct us if any of this is incorrect)

  1. We register each merchant using the Web Merchant Registration API as a Platform Integrator, with a unique partnerInternalMerchantIdentifier. Merchants do not have their own Apple Developer accounts.
  2. For merchant-hosted payment pages, the merchant's checkout domain is provided in domainNames.
  3. The domain verification file is downloaded from our Apple Developer account (Platform Integrator account), and the merchant hosts that file under the /.well-known/ path on their domain.
  4. The merchant registration created through the Web Merchant Registration API is then used for Apple Pay eligibility checks and merchant validation.

Questions:

  1. Domain registration
    For a merchant-hosted payment page, is it correct to register the merchant's domain against that merchant's partnerInternalMerchantIdentifier registration?
  2. Verification file
    When onboarding multiple merchants:
    Is the same domain association file used across all merchant domains?
    Or is a unique verification file generated per merchant registration?
  3. Eligibility checks and Apple Pay button
    The "Supporting Apple Pay on Third-Party Browsers" documentation (Scenario 3) suggests that a payment service provider may provide a JavaScript library that loads apple-pay-sdk.js for merchants.
    For merchant-hosted pages, is it supported and recommended for the PSP/platform integrator to provide a thin wrapper library around:
    canMakePayments()
    applePayCapabilities()
    Apple Pay button rendering
    Session creation
    Or is Apple’s preferred approach that the merchant's checkout page interacts directly with Apple Pay JS APIs?
  4. PSP/acquirer decrypts the payment token
    If the PSP/acquirer is responsible for token decryption, we understand that encryptTo should be set to the Platform Integrator identifier.
    For merchant-hosted payment pages, are there any additional requirements beyond domain registration and merchant validation?
  5. Merchant decrypts the payment token
    We would also like to support a model where the merchant decrypts Apple Pay tokens directly.
    In that case, our understanding is that encryptTo must reference the merchant's identifier rather than the Platform Integrator identifier.
    Is that understanding correct, and are there any additional onboarding or registration requirements for that model?
  6. Merchant validation
    For merchant-hosted checkout pages, what is the expected implementation pattern for onvalidatemerchant?
    Specifically:
    Should the merchant's frontend send the validationURL to the PSP/platform integrator backend, which then performs merchant validation with Apple and returns the merchant session?
    Or is a different flow expected when using the Platform Integrator model?

Any clarification or guidance would be greatly appreciated. Thank you.

Replies  1
Boosts 0
Views  23
Participants  2
Pokpong OP

A few parts of your flow match Apple's docs, with one important detail on validation.

The Registration API is intended for platform integrators, and the integrator manages the merchants' Apple Pay setup. Each registered merchant has its own internal identifier and domain list. The verification file is associated with your platform integrator ID; Apple says to distribute that file to each merchant and host it at the required .well-known path on every domain before calling Register Merchant.

For encryptTo, Apple's request reference says to use the platform integrator ID by default. If another party decrypts the payment data, use that party's platform integrator ID or merchant ID instead.

For onvalidatemerchant, the browser sends the validationURL to your server. Your server requests a session from Apple and returns the one-use merchant session to the page. Apple explicitly says not to request the merchant session from the client.

I don't see Apple's public docs specify whether a single wrapper library is preferred for canMakePayments() or applePayCapabilities(). I'd treat that as an integration design choice, provided the merchant page uses the Apple Pay JS flow for its registered domain and checks eligibility with the appropriate merchant identifier. For token ownership or shared-domain edge cases, confirm with Apple through your Registration API support channel before going live.

References: Web Merchant Registration API, domain verification, RegisterMerchantRequest, and Providing Merchant Validation.