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

# Apple Pay

> Accept Apple Pay payments through PayNext.

Apple Pay is available to cardholders at participating banks in supported countries. For more information, refer to [Apple's participating banks](https://support.apple.com/en-us/ht204916) documentation.

## Payment Method Details

|                            |                                                                       |
| :------------------------- | :-------------------------------------------------------------------- |
| **Customer locations**     | Worldwide (varies by bank participation)                              |
| **Supported currencies**   | All currencies                                                        |
| **Recurrent payments**     | ✓                                                                     |
| **Manual capture support** | ✓                                                                     |
| **Refunds**                | ✓                                                                     |
| **Supported processors**   | <Badge>Stripe</Badge> <Badge>Braintree</Badge> <Badge>Unlimit</Badge> |

## Overview

PayNext is registered with Apple as a **Platform Integrator**. We onboard your domains under our Apple Pay Merchant ID — you don't need your own Apple Developer account, Apple Pay Merchant ID, or Apple Pay certificates. Setup happens in the Dashboard — enter your domain, host the verification file we provide, and the domain verifies with Apple automatically.

Apple Pay buttons render automatically in the PayNext Checkout SDK when the customer's device supports Apple Pay and your domain is active.

<Note>
  PayNext supports **Visa** and **Mastercard** through Apple Pay. Other card networks (Amex, Discover) are not supported.
</Note>

## Prerequisites

* A publicly accessible HTTPS domain where the PayNext checkout is hosted
* The ability to host a static file under `/.well-known/` on that domain

## Setup

Setup happens entirely in the PayNext Dashboard. Enter your domain, host one verification file, and PayNext verifies the domain with Apple.

### Step 1: Open the Add domain dialog

<Steps>
  <Step title="Open Apple Pay domain settings">
    In the PayNext Dashboard, go to **Checkout → Apple Pay**, then click **Manage Apple Pay domains**.
  </Step>

  <Step title="Add a domain">
    Click **Add new domain** and enter the bare hostname (e.g., `checkout.example.com`) — no `https://`, no path, no port.
  </Step>
</Steps>

### Step 2: Download and host the verification file

Host the file before you verify the domain — Apple fetches it the moment you add the domain. The file content is identical for every domain you register with us.

<Steps>
  <Step title="Download the verification file">
    In the **Add new domain** dialog, click **Download**. The file is named `apple-developer-merchantid-domain-association`.
  </Step>

  <Step title="Host the file">
    Place the file at this exact URL on each registered domain:

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

    Requirements:

    * Served over HTTPS with a valid TLS certificate
    * Returns `200 OK` with the exact file contents — no redirects
    * Content-Type `text/plain` or `application/octet-stream`

    <AccordionGroup>
      <Accordion title="Nginx">
        ```nginx theme={"system"}
        location /.well-known/apple-developer-merchantid-domain-association {
            default_type application/octet-stream;
            alias /var/www/html/.well-known/apple-developer-merchantid-domain-association;
        }
        ```
      </Accordion>

      <Accordion title="Static hosting (Vercel, Netlify, Cloudflare Pages)">
        Place the file in your project's `public/.well-known/` directory. Most static hosting platforms serve files from `public/` at the site root automatically.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

<Warning>
  Host the same file on every domain you register — the content is identical across all your domains under PayNext, but the URL must be reachable on each domain separately.
</Warning>

### Step 3: Verify the domain

Once the file is live, click **Add** in the dialog. PayNext registers the domain with Apple under our Platform Integrator account, and Apple fetches the verification file from your domain. The status changes from **Pending** to **Active**. Repeat for every domain and subdomain where Apple Pay buttons will appear.

If the domain stays **Pending** or shows an error, verify the file is reachable:

```bash theme={"system"}
curl -i https://checkout.example.com/.well-known/apple-developer-merchantid-domain-association
```

Expected response: `HTTP/2 200` with the file contents. Common issues:

* The URL redirects (Apple does not follow redirects)
* The file is served over HTTP, not HTTPS
* The file path is wrong — it must be exactly `/.well-known/apple-developer-merchantid-domain-association`
* The file content differs from what the Dashboard provided

## Token Processing

When a customer authorizes an Apple Pay payment:

1. The customer authenticates using Face ID, Touch ID, or passcode
2. Apple generates an EC\_v1 encrypted payment token containing a network token and 3DS cryptogram
3. The PayNext SDK sends the encrypted token directly to the PayNext server
4. PayNext decrypts the token server-side and verifies its CMS signature against the Apple Root CA - G3 certificate chain
5. PayNext extracts the network token, expiry, and cryptogram, then routes the payment to your processor

The PayNext SDK handles both transports automatically:

* **Safari** (macOS / iOS / iPadOS): Uses the native `ApplePaySession` API
* **Non-Safari browsers** (Chrome, Firefox, Edge on macOS): Uses the W3C `PaymentRequest` API with iPhone handoff via QR code

Both transports produce identical EC\_v1 payment tokens, so the backend processing is the same regardless of browser.

## Checkout Implementation

The PayNext Checkout SDK handles the entire Apple Pay flow — merchant validation, token acquisition, and browser transport selection. No direct interaction with Apple Pay APIs is required.

Apple Pay buttons render automatically when PayNext detects that:

* The customer's device supports Apple Pay
* Your domain is registered and **Active** in the PayNext Dashboard

You control the checkout experience through configuration passed to the `mount` method — see [Getting Started](/sdk-reference/introduction/getting-started#mount-the-checkout) for the mounting flow and [Customize Checkout Behavior](/sdk-reference/web-sdk/customization/behavior) for available options.

## Testing

### Switch to Sandbox

1. In the Dashboard, switch the environment to **Sandbox** using the environment toggle in the bottom-left corner
2. In the SDK, pass `environment: 'sandbox'` to the `mount` method — see [Getting Started](/sdk-reference/introduction/getting-started#mount-the-checkout) for details

### Test requirements

Apple Pay test mode requires a real Apple device or Mac signed in with a **Sandbox Tester Apple ID** — a regular Apple ID won't accept Apple's test cards.

<Steps>
  <Step title="Create a Sandbox Tester">
    In [App Store Connect → Users and Access → Sandbox Testers](https://appstoreconnect.apple.com/access/users), create a tester account.
  </Step>

  <Step title="Sign in on your test device">
    On a Mac or iOS device, sign out of your regular Apple ID for Wallet and Apple Pay, then sign in with the Sandbox Tester.
  </Step>

  <Step title="Add a sandbox card to Wallet">
    Use one of [Apple's sandbox test cards](https://developer.apple.com/apple-pay/sandbox-testing/) — never real cards in Sandbox mode.
  </Step>

  <Step title="Trigger an Apple Pay checkout">
    Open the PayNext checkout on your test domain, click the Apple Pay button, and complete authentication.
  </Step>
</Steps>

Ensure the test device's region and currency match your processor configuration, otherwise Apple Pay will refuse to render the sheet.

### Verification

* Confirm the PayNext payment history shows the Apple Pay wallet indicator
* Verify that Workflows execute as expected (including 3DS cryptogram handling)
* Test on both Safari and non-Safari browsers (Chrome on macOS) to verify both transports

<Tip>
  For processor-specific Apple Pay testing guides, see [Stripe's Apple Pay testing](https://docs.stripe.com/apple-pay/testing) and [Braintree's Apple Pay sandbox docs](https://developer.paypal.com/braintree/docs/guides/apple-pay/testing-go-live).
</Tip>

## Billing Address

When a customer completes payment with Apple Pay, PayNext captures the billing address from the wallet and submits it to the payment processor.

## 3DS and Authentication

Apple Pay handles 3D Secure differently than standard card payments. Authentication is embedded directly in the wallet experience.

### How it works

1. **First payment (CIT)**: The customer authenticates using Face ID, Touch ID, or passcode. Apple Pay generates a 3DS cryptogram automatically — no challenge screen appears. This initial <Tooltip tip="Customer-Initiated Transaction—customer is present and authorizes the payment.">CIT</Tooltip> establishes the authentication chain for future charges.

2. **Recurring payments (MIT)**: All subsequent charges use <Tooltip tip="Merchant-Initiated Transaction—recurring or off-session payment without customer presence.">MIT</Tooltip> exemptions. The card networks recognize the original CIT authentication and allow off-session payments without additional 3DS.

3. **3RI not supported**: Apple Pay does not support <Tooltip tip="3DS Requester-Initiated—3DS authentication for recurring payments without customer presence.">3RI</Tooltip> flows. The wallet architecture relies on MIT exemptions rather than re-authenticating for each recurring charge.

## Resources

* [Apple Pay on the Web documentation](https://developer.apple.com/documentation/apple_pay_on_the_web)
* [Apple Pay Sandbox Testing](https://developer.apple.com/apple-pay/sandbox-testing/)
* [Apple Pay participating banks](https://support.apple.com/en-us/ht204916)
* [Apple Pay Acceptable Use Guidelines](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/)