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

# Apple Pay via Paysight Widget

> Enable Apple Pay payments in the Paysight Widget including setup requirements, configuration, and implementation examples.

<Warning>
  Apple Pay is currently in closed beta testing. If you would like to use Apple Pay, please contact your account manager.
</Warning>

## Overview

Apple Pay runs on the **host page** (parent-hosted), not inside the iframe. The button renders in `applePayContainerId` (default `apple-pay-slot`) to avoid cross-origin wallet restrictions.

Apple Pay integration allows customers to pay using their Apple devices (iPhone, iPad, Mac) with Touch ID, Face ID, or passcode authentication.

### How Apple Pay Beta Works on Paysight

Apple Pay is enabled on Paysight through a guided setup process managed by our team during the beta phase.

* **Merchant Enrollment**

  Paysight handles Apple Pay merchant enrollment on your behalf. Apple Pay is currently enabled per merchant account, one MID at a time. To complete enrollment, we require your company name, registered address, and MCC code.

* **Merchant Identifier**

  Once enrollment is complete, we provide you with a unique Apple Pay merchant identifier. This identifier must be included in your widget configuration to enable Apple Pay for the selected merchant account.

* **Domain Certificate Upload**

  You need to provide us with the domain where you will be placing the Paysight Widget. Once we provide you with the `apple-developer-merchantid-domain-association` file, you must upload it to your domain. The file must be placed in a `.well-known` directory at the root of your domain (e.g., `https://yourstore.com/.well-known/apple-developer-merchantid-domain-association`). This certificate file is required by Apple for domain verification.

<Info>
  This setup process will be fully automated within the Paysight UI in an upcoming release. During the beta period, enrollment is handled manually per MID upon request.
</Info>

## Prerequisites

<Steps>
  <Step title="Contact Your Account Manager">
    Apple Pay is currently in closed beta. Contact your Paysight account manager to request access.
  </Step>

  <Step title="Install and load the Widget">
    Ensure you have the Paysight Widget installed or loaded on your page. See <a href="/widget-sdk/guides/installation">Installation</a>.
  </Step>

  <Step title="Complete Company Information">
    Make sure you have filled in all details in the Companies section of Paysight for the relevant MIDs.
  </Step>
</Steps>

## Steps to Get Started

<Steps>
  <Step title="Select Your MIDs">
    Select a MID or MIDs you would like to enable Apple Pay on.
  </Step>

  <Step title="Verify Company Details">
    Make sure you have filled in all details in the Companies section of Paysight for the relevant MIDs.
  </Step>

  <Step title="Provide Your Domain">
    Provide us with the domain where you will be placing the Paysight Widget (e.g., `mystore.com` or `checkout.mystore.com`). This is the domain where you will advertise your products and host the widget.
  </Step>

  <Step title="Open Support Ticket">
    Open a Support Ticket on Paysight with title **Apple Pay - MID ID** and provide us with all of the above information, including your domain.
  </Step>

  <Step title="Upload Apple Certificate">
    Once we provide you with the `apple-developer-merchantid-domain-association` file, upload it to your domain. The file must be accessible at `https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association`. We will verify the certificate is properly configured before enabling Apple Pay.
  </Step>
</Steps>

## Apple Pay Configuration

Once you receive approval for your MIDs, you can initialize your widget with the additional `applePay` property:

### Configuration Properties

* <strong>applePayEnabled</strong> (boolean, optional): Enable or disable Apple Pay for the widget
* <strong>applePayOptions</strong> (object, optional): Apple Pay configuration options
  * <strong>applePayMerchantId</strong> (string, required when applePayEnabled is true): Apple Pay merchant identifier provided by Paysight (per merchant account). Currently required, will be optional in v2.
  * <strong>style</strong> (object, optional): Optional styling for the Apple Pay button
    * <strong>buttonStyle</strong> ('black' | 'white' | 'white-outline', optional): Button style
    * <strong>buttonType</strong> (string, optional): Button type: 'pay', 'buy', 'donate', etc.
    * <strong>borderRadius</strong> (number, optional): Border radius in pixels
    * <strong>size</strong> (object, optional): Button width and height
      * <strong>width</strong> (number | string, optional): Button width in pixels or '100%'
      * <strong>height</strong> (number | string, optional): Button height in pixels

<Info>
  Apple Pay automatically collects customer information (name, email, billing address) from the Apple Pay sheet, so you don't need to provide these fields when using Apple Pay.
</Info>

## Wallet-only checkout

To **hide the card form** and show **only** Apple Pay and/or Google Pay (with the host **“OR”** divider hidden when the wallet-only layout is active), set **`showOnlyWalletMethods: true`** in your widget config together with a fully configured wallet. If no wallet is available, readiness times out, or a **wallet payment fails**, the widget **falls back** to the full card UI.

<CardGroup cols={2}>
  <Card title="Wallet-only checkout guide" icon="wallet" href="/widget-sdk/guides/wallet-only-checkout">
    Full overview, requirements, fallback rules, and a code example (Apple + Google).
  </Card>
</CardGroup>

See also the [Configuration Guide](/widget-sdk/guides/configuration) for the `showOnlyWalletMethods` field and [Google Pay via Widget](/widget-sdk/guides/google-pay-via-widget) if you offer both wallets.

## Implementation example

```html theme={null}
<div id="apple-pay-slot"></div>
<div id="payment-container"></div>

<script src="https://payment.paysight.io/widget-sdk.js"></script>
<script>
  PaySightSDK.createWidget({
    targetId: 'payment-container',
    applePayContainerId: 'apple-pay-slot',
    config: {
      productId: YOUR_PRODUCT_ID,
      sessionId: 'YOUR_SESSION_ID',
      environment: 'production',
      amount: 29.99,
      applePayEnabled: true,
      applePayOptions: {
        applePayMerchantId: 'merchant_xxxxxxxx',
        style: {
          buttonStyle: 'black',
          buttonType: 'pay',
          borderRadius: 8,
          size: { width: '100%', height: 48 },
        },
      },
      customer: { email: 'customer@example.com', country: 'US' },
    },
    onMessage: (message) => {
      if (message.type === 'PAYMENT_SUCCESS') console.log(message.payload);
    },
  });
</script>
```

## Customer Information

<Info>
  Apple Pay automatically collects customer information (name, email, billing address) directly from the Apple Pay sheet. You don't need to configure Name and Email fields or provide them in the customer object when using Apple Pay - the widget will automatically retrieve this information from Apple Pay.
</Info>

If you're also supporting standard card payments (non-Apple Pay), you may still want to include Name and Email fields or customer object for those payment methods.

## 3D Secure

<Warning>
  Apple Pay in the widget **does not** support the same in-widget 3DS challenge flow as card payments or Google Pay. Apple Pay requests are sent **without** <code>threeDSecure</code> configuration; if the backend requires 3DS and returns a <code>threeDSecureId</code>, the Apple Pay attempt fails. Keep <code>threeDSRequired: false</code> for typical Apple Pay integrations unless your Paysight contact confirms otherwise.
</Warning>

## Limitations and Caveats

<Warning>
  The following limitations apply to the current Apple Pay beta implementation. These will be addressed in upcoming updates.
</Warning>

### Configuration Management

Currently, you must pass `applePayEnabled: true` and `applePayOptions` with `applePayMerchantId` in your widget initialization:

```javascript theme={null}
applePayEnabled: true,
applePayOptions: {
  applePayMerchantId: 'merchant_xxxxxxxx',
  style: {
    buttonStyle: 'black',
    buttonType: 'pay',
    borderRadius: 8,
        size: {
          width: '100%',
          height: 48
        }
  }
}
```

**Upcoming changes:**

* Apple Pay configuration will be controlled from your merchant accounts in Paysight
* The `applePayMerchantId` field in `applePayOptions` will become optional in v2
* Domain and support URL configuration will no longer be required

### MID Selection

Currently, only one MID per widget initialization can be used with Apple Pay.

**Upcoming changes:**

* We will be rolling out an update that automatically selects an Apple Pay compatible MID from your MID router
* This will allow seamless Apple Pay support across multiple merchant accounts

### Platform Support

Currently, Apple Pay is limited to the Paysight Widget implementation.

**Current limitations:**

* Shopify checkout is not supported
* Only available through the Paysight Widget SDK

<Info>
  Stay tuned for updates as we continue to expand Apple Pay support across more platforms and simplify the configuration process.
</Info>

## Event Handling

Handle widget events to provide feedback to users during the Apple Pay flow:

```javascript theme={null}
onMessage: (message) => {
  switch (message.type) {
    case 'PAYMENT_START':
      // Disable submit button, show "Processing..."
      break;
    case 'PAYMENT_SUCCESS':
      // Show success message, redirect to confirmation page
      console.log('Transaction ID:', message.payload.transactionId);
      break;
    case 'PAYMENT_ERROR':
      // Show error message, allow retry
      console.error('Error:', message.payload.message);
      break;
  }
}
```

<Info>
  Full event details and patterns: <a href="/widget-sdk/guides/events">Event Handling</a> and <a href="/widget-sdk/reference/events">Events Reference</a>.
</Info>

## Testing

<Steps>
  <Step title="Use Production Environment">
    Apple Pay requires a production environment. Make sure you're using `environment: 'production'` in your configuration.
  </Step>

  <Step title="Test on Apple Devices">
    Apple Pay is only available on Apple devices (iPhone, iPad, Mac). Test your integration on these devices.
  </Step>

  <Step title="Verify Certificate Upload">
    Ensure the `apple-developer-merchantid-domain-association` file is properly uploaded to your domain's `.well-known` directory and is accessible via HTTPS.
  </Step>

  <Step title="Check Merchant Enrollment">
    Confirm with your account manager that your merchant account has been enrolled with Apple Pay.
  </Step>
</Steps>

## Best Practices

* <strong>No additional fields needed</strong>: Apple Pay automatically collects customer information (name, email, billing address) from the Apple Pay sheet, so you don't need to configure these fields specifically for Apple Pay.
* <strong>Test on real devices</strong>: Apple Pay functionality is only available on Apple devices, so test on actual hardware.
* <strong>Handle errors gracefully</strong>: Implement proper error handling for cases where Apple Pay may not be available.
* <strong>Provide fallback options</strong>: Ensure your widget still works with standard card payments if Apple Pay is unavailable.
* <strong>Verify certificate upload</strong>: Ensure the `apple-developer-merchantid-domain-association` file is properly uploaded and accessible before going live.

## Troubleshooting

### Apple Pay Button Not Showing

* Verify that you're testing on an Apple device (iPhone, iPad, or Mac)
* Check that your merchant account has been enrolled with Apple Pay
* Ensure the `apple-developer-merchantid-domain-association` file is properly uploaded and accessible at `https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association`
* Confirm that you're using the correct `applePayMerchantId` in `applePayOptions` provided by Paysight
* Verify that `applePayEnabled` is set to `true`

### Payment Fails

* Verify that `applePayEnabled` is set to `true`
* Check that your `applePayMerchantId` in `applePayOptions` is correct
* Ensure the `apple-developer-merchantid-domain-association` file is accessible and properly configured
* Verify that the customer has completed the Apple Pay authentication (Face ID, Touch ID, or passcode)
* Contact support if issues persist

## Live demo

Try Apple Pay in the sandbox playground: [https://payment.paysight.io/demo?preset=apple-pay](https://payment.paysight.io/demo?preset=apple-pay)

## See Also

<CardGroup cols={2}>
  <Card title="Wallet-only checkout" icon="wallet" href="/widget-sdk/guides/wallet-only-checkout">
    Hide the card form and lead with Apple Pay and/or Google Pay.
  </Card>

  <Card title="Configuration Guide" icon="sliders" href="/widget-sdk/guides/configuration">
    Detailed configuration including all Apple Pay options.
  </Card>

  <Card title="Google Pay via Widget" icon="wallet" href="/widget-sdk/guides/google-pay-via-widget">
    Add Google Pay alongside Apple Pay on the host page.
  </Card>

  <Card title="Apple Pay live demo" icon="play" href="https://payment.paysight.io/demo?preset=apple-pay">
    Interactive sandbox preset with host wallet slot.
  </Card>

  <Card title="Basic Integration Example" icon="bolt" href="/widget-sdk/examples/basic-integration">
    Simple widget integration example.
  </Card>
</CardGroup>