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

# Apple Pay

> What is specific to Apple Pay on top of the shared wallet flow, registering your domains, its errors, and how to test it in sandbox.

Apple Pay needs an `https` page and a browser that can pay. Elements loads Apple's SDK from
`applepay.cdn-apple.com`. In Safari on an Apple device the customer pays on that device. In other browsers they
scan a code with an iPhone on iOS 18 or later. Elements asks only whether the device can pay, not whether the
customer has a card set up. On your own page the domain must be registered first.

## Register your domains

Apple verifies the page's domain every time the sheet opens. Elements asks Payra for a merchant session, Apple's
signed proof that the page belongs to a registered merchant, for `window.location.hostname`. Payra's processor
signs one only for the domains registered to your workspace. On any other host, tapping the button answers
`error` with `wallet_domain_not_allowed` and the sheet closes without taking a payment.

To register, send your Payra contact the exact hostnames that will show the button, such as
`checkout.example.com` and `www.example.com`. Wildcards are not accepted, so list each subdomain.

> [!NOTE]
>
> Registering a new merchant with Apple takes 3 to 4 weeks, even if you have accepted Apple Pay before.
> Send your hostnames well ahead of launch.

Then host the domain association file Payra gives you at

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

served with `200`, as `text/plain`, without a login, a proxy or a redirect. Apple reads it at registration and
again later, so keep it in place. `localhost` cannot be registered, so try Apple Pay on a real hostname.

## Apple Pay errors

Apple closes its sheet after a failure. When Payra refused the token, `cancel` follows `error`. When the merchant
session failed, `error` comes alone. Besides the [shared codes](https://docs.payra.com/wallets.md#events-and-errors), the merchant session can
answer:

| `type` | `code` | When |
| - | - | - |
| `invalid_request_error` | `wallet_domain_not_allowed` | The page's host is not [registered](#register-your-domains) for Apple Pay. |
| `invalid_request_error` | `apple_pay_merchant_session_rejected` | The processor refused the merchant session. |
| `invalid_request_error` | `payment_provider_not_configured` | Your workspace stopped offering Apple Pay after the session was created. |
| `api_error` | `apple_pay_merchant_session_failed` | The merchant session could not be started this time. Worth one retry. |

## Test Apple Pay

Payments in sandbox run in Apple's sandbox. Sign the test device in with an Apple sandbox tester account and add
one of [Apple's test cards](https://developer.apple.com/apple-pay/sandbox-testing/) to its Wallet. A real card
does not pay there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.