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

# Apple Pay Setup

> Generate the required Apple Pay integration data for your eWallet Account.

<Info>
  This page is part of **Merchant Account Setup**. [Back to Library Setup →](/guides/library/setup)
</Info>

<Note>
  Apple Pay collects payment credentials from customers. You'll also need a [payment provider configured](/getting-started/add-payment-provider) in Orchestra to process the transactions.
</Note>

**Requires:** [Apple Developer Program](https://developer.apple.com/programs/) membership (\$99/year)

To generate the required data for an Apple Pay eWallet Account, follow the steps below to create and configure your Merchant ID, certificates, and domain verification.

## 1. Create a Merchant ID

A Merchant ID identifies you as a merchant who is able to accept payments via Apple Pay.

1. Sign in to your [Apple Developer Account](https://developer.apple.com/account/)
2. Go to **Certificates, Identifiers & Profiles** > **Identifiers**
3. Click **+** to add a new identifier
4. Select **Merchant IDs**
5. Enter a **description** and a **unique identifier** for your Merchant ID (e.g., `merchant.com.example.yourbusiness`)
6. Click **Continue**, review the details, and then **Register**

## 2. Verify Merchant Domain

Apple requires your domain to be verified to ensure that only authorized domains can initiate Apple Pay transactions on behalf of your Merchant ID.

1. Go back to the **Merchant ID** page in the developer portal
2. Under your Merchant ID, click **Edit** and then **Verify Your Domain**
3. Enter the domain name you want to use for Apple Pay (e.g., `example.com`)
4. Download the **Apple Pay Verification File** (`apple-developer-merchantid-domain-association`)
5. Upload the file to the `.well-known` directory on your domain. The full URL should be:
   `https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association`
6. Return to the Apple Developer Portal and click **Verify**. If the file is hosted correctly, the domain will be verified.

<Note>
  The file must be served over HTTPS without redirects. Download the file only once. Repeated downloads generate new content.
</Note>

<Warning>
  Domain verification is required for Apple Pay to function. Without it, the Apple Pay button will appear but the payment sheet will close immediately when clicked.
</Warning>

## 3. Create Payment Processing Certificate

This certificate is used by your payment processor to handle payment data securely.

1. Generate a Certificate Signing Request (CSR) on your machine using OpenSSL:

```bash theme={null}
# Generate key pair
openssl ecparam -genkey -name prime256v1 -out ~/mykey.key -noout

# Generate CSR from key pair
openssl req -new -sha256 -key ~/mykey.key -out ~/request.csr -subj /CN=www.mydomain.com
```

2. Go to **Certificates, Identifiers & Profiles** in the Apple Developer Portal
3. Select **Merchant IDs** and click on your Merchant ID
4. Under **Apple Pay Payment Processing Certificate**, click **Create Certificate**
5. In the **Create a New Certificate** page, select **Choose File** under "Upload a Certificate Signing Request" and upload your `~/request.csr`
6. Download the Apple Pay Payment Processing Certificate (`apple_pay.cer`)

<Tip>
  This certificate can also be found and downloaded later under the Apple Pay Payment Processing Certificate section in your Merchant ID.
</Tip>

7. Move the downloaded file to your working directory (`~/`) and convert it to PEM:

```bash theme={null}
openssl x509 -inform DER -in ~/apple_pay.cer -out ~/apple_pay.pem
```

## 4. Create Merchant Identity Certificate

This certificate allows your server to authenticate itself to Apple's servers during payment processing.

1. Generate a CSR and key file using OpenSSL:

```bash theme={null}
# Generate CSR and key files
openssl req -out ~/uploadMe.csr -new -newkey rsa:2048 -nodes -keyout ~/clientCertificate.key
```

<Note>
  In the prompt, enter your details. The **Common Name** should match the one used in the previous step. When asked for a password, leave it blank and press Enter.
</Note>

2. Go to **Certificates, Identifiers & Profiles** in the Apple Developer Portal
3. Select **Merchant IDs** and click on your Merchant ID (the same one as the previous step)
4. Under **Apple Pay Merchant Identity Certificate**, click **Create Certificate**
5. In the **Create a New Certificate** page, select **Choose File** under "Upload a Certificate Signing Request" and upload your `~/uploadMe.csr`
6. Download the Apple Pay Merchant Identity Certificate (`merchant_id.cer`)

<Tip>
  This certificate can also be found and downloaded later under the Apple Pay Merchant Identity Certificate section in your Merchant ID.
</Tip>

7. Move the downloaded file to your working directory (`~/`) and convert it to PEM:

```bash theme={null}
openssl x509 -inform der -in ~/merchant_id.cer -out ~/clientCertificate.pem
```

## 5. Create eWallet Account

After completing the previous steps, you should have the following files in your working directory:

| File                    | Generated In                         |
| ----------------------- | ------------------------------------ |
| `mykey.key`             | Step 3 - Payment Processing key pair |
| `request.csr`           | Step 3 - Payment Processing CSR      |
| `apple_pay.cer`         | Step 3 - Downloaded from Apple       |
| `apple_pay.pem`         | Step 3 - Converted certificate       |
| `uploadMe.csr`          | Step 4 - Merchant Identity CSR       |
| `clientCertificate.key` | Step 4 - Merchant Identity key       |
| `merchant_id.cer`       | Step 4 - Downloaded from Apple       |
| `clientCertificate.pem` | Step 4 - Converted certificate       |

When [setting up an eWallet Account](/guides/library/store-merchant-account), use the content of these files as follows:

| eWallet Account Field                   | Value                                                                                                      |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Name**                                | Desired name of the eWallet Account - you will use this in your requests                                   |
| **eWallet Type**                        | ApplePay                                                                                                   |
| **Merchant Identifier**                 | The identifier from Step 1 (e.g., `merchant.com.example.yourbusiness`)                                     |
| **Merchant Display Name**               | Desired display name shown to payers                                                                       |
| **Domain Name**                         | Domain where the Apple Pay button will be hosted - must match the Common Name (CN) set in the certificates |
| **Client Certificate Pem**              | Contents of `~/clientCertificate.pem`                                                                      |
| **Client Certificate Private Key Pem**  | Contents of `~/clientCertificate.key`                                                                      |
| **Payment Certificate Private Key Pem** | Contents of `~/mykey.key`                                                                                  |
| **Payment Certificate Pem**             | Contents of `~/apple_pay.pem`                                                                              |

## Testing

Use [Apple Pay Sandbox](https://developer.apple.com/apple-pay/sandbox-testing/) with test cards in Safari on macOS or iOS.

## Next Steps

<CardGroup cols={2}>
  <Card title="Store eWallet Account" icon="vault" href="/guides/library/store-merchant-account">
    Save your Apple Pay credentials in Orchestra
  </Card>

  <Card title="Apple Pay Guide" icon="apple" href="/guides/library/supported-payment-methods/apple-pay">
    Implement Apple Pay in your integration
  </Card>
</CardGroup>