> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Pay

> Where Apple Pay appears, what each surface requires, and how to test it.

Once Apple Pay is enabled on your account, eligible buyers see an Apple Pay
button above the card form on every Ionic payment surface. What you have to
do depends on whose domain the buyer is on when they pay.

| Surface                                        | Buyer's domain | What you do                                              |
| ---------------------------------------------- | -------------- | -------------------------------------------------------- |
| [Hosted checkout](/guides/checkout)            | Ionic's        | Nothing — works once your account has Apple Pay          |
| [Payment links](/guides/payment-links)         | Ionic's        | Nothing                                                  |
| Hosted invoices                                | Ionic's        | Nothing                                                  |
| [Embedded checkout](/guides/embedded-checkout) | Yours          | Register your domain + host the association file (below) |

When the payment sheet opens, Apple validates the domain of the top-level
page the buyer is on. On hosted surfaces, that's our domain, which we
register and maintain. On embedded checkout, it's yours — so you register
it, and the button renders in your page, above the frame, never inside it.

## Enabling Apple Pay

Apple Pay is enabled per account — request it during onboarding or through
support. On hosted surfaces you're done; buyers on capable devices see the
button immediately.

## Embedded checkout requirements

Pass `applePay: true` to `mountSession` (see the
[embedded checkout guide](/guides/embedded-checkout#apple-pay)). The button
stays hidden until all of these hold:

<Steps>
  <Step title="Register your domain for Apple Pay">
    Apple Pay registration is separate from the web-domain registration that
    allows framing — it happens against Apple's systems, and we run it for
    each domain you tell us. One registration per domain, per mode.
  </Step>

  <Step title="Serve the domain-association file">
    We provide a file that must be reachable at exactly:

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

    It must return `200` directly — no redirect. Apple fetches it during
    registration and re-checks it over time; if your deploy process wipes
    static files, make sure this one survives every deploy.
  </Step>

  <Step title="HTTPS everywhere">
    Your page and every ancestor frame must be HTTPS. Safari refuses
    Apple Pay in any frame tree with an insecure ancestor.
  </Step>
</Steps>

On the buyer's side: Safari 17 or later (earlier versions don't support
Apple Pay in cross-origin iframes) with a card in Wallet. On any other
browser or device the button stays hidden and buyers pay by card — no
fallback handling needed on your side.

## How payment completes

An Apple Pay payment is the same payment: the session completes, your
`onComplete` fires (on embedded), and the same
[`checkout.session.completed` webhook](/webhooks/events) drives fulfillment.
There is no wallet-specific handling to build.

## Testing

A real Apple device is required — there is no simulator path to a completed
payment sheet. `localhost` can never be Apple Pay-registered, so for
embedded checkout, wallet testing needs your page deployed on a registered
HTTPS domain. Card flows test everywhere — see
[test cards](/guides/test-cards).