You wish to accept payments on both iOS devices and Web

1. Register for an Apple Pay Merchant ID
2. Request Certificate Signing Request (CSRs)
3. Upload CSR to your Apple Developer Account
4. Provide your certificates
5. Register your domain

Register for an Apple Pay Merchant ID

Register a new Merchant ID via Apple's Setting up Apple Pay guide.

📘

We recommend creating distinct Apple Merchant IDs for Payrails production and staging environments.

Request Certificate Signing Requests (CSRs)

Contact your Payrails representative to initiate the certificate generation process. Payrails will generate two Certificate Signing Requests (CSRs) for you:

• apple_pay.csr — Payment Processing Certificate Signing Request
• merchant_id.csr — Merchant Identity Certificate Signing Request

You will use these in the next step to generate your certificates in the Apple Developer Center.

Upload CSR to your Apple Developer Account

1. Go to the Merchant ID list in Apple's Developer Center and select the Merchant ID you registered earlier.

2. Under the Apple Pay Payment Processing Certificate section, click Create Certificate and upload the apple_pay.csr file provided by Payrails. Download the generated Payment Processing Certificate.

Create Payment Processing Certificate

3. Go back to the same Merchant ID and under the Apple Pay Merchant Identity Certificate section, click Create Certificate and upload the merchant_id.csr file provided by Payrails. Download the generated Merchant Identity Certificate.

Create Merchant Identity Certificate

Decide on a Config ID

Payrails allows you to set up multiple Apple Pay key configurations, each identified by a unique Config ID. This is useful for splitting traffic across different regions or environments — for example, routing European payments through one set of keys and US payments through another.

Your Config ID can be a UUID or a descriptive string such as region-eu-west or region-us-east. Share your chosen Config ID with your Payrails representative when providing your certificates — it will be used to associate your Apple Pay keys and can be referenced in payment requests to select which configuration should be used for processing.

Provide your Certificates

Send both the Payment Processing Certificate and the Merchant Identity Certificate to your Payrails representative.

Once Payrails confirms receipt, go back to the Merchant ID list, select your Merchant ID, and activate the Payment Processing Certificate you just created.

Register your Domain

To process Apple Pay payments on the web, Apple requires you to verify ownership of your domain.

1. Go to the Merchant ID list and select the Merchant ID for which you configured certificates.

2. Under the Merchant Domains section, click Add Domain and download the domain association file.

Download domain verification file

3. Host the file on your domain at the following path: https://<your-domain>/.well-known/apple-developer-merchantid-domain-association

4. Click Verify in the Apple Developer Center to complete domain registration.

We render the Apple Pay button inside an iframe — which domain should we register?

Apple requires domain registration to be done on the domain visible in the browser address bar, not the iframe's domain. Registering the iframe domain will cause Apple Pay payments to automatically fail.

📘

The domain association file must remain publicly accessible without redirects — Apple regularly re-verifies domains after the initial registration. This step is not required for staging environments.

Accept Apple Pay with the Payrails Drop-in

The Payrails Drop-in is the fastest way to accept Apple Pay. It handles the entire payment UI and flow — no additional client-side development is required beyond mounting the component.

1. Create a session
2. Initialize the SDK
3. Mount the Drop-in
4. Handle payment events

For the full list of Drop-in configuration options, styling, and event handling, refer to the Drop-in integration guide.

Step 1: Create a session (Server-side)

From your server, call the Payrails /client/init endpoint. To enable Apple Pay, pass the applePayConfigId that was agreed upon during your Payrails onboarding.

POST /merchant/client/init
Authorization: Bearer <YOUR_JWT>
x-idempotency-key: <UUID>

{
  "type": "dropIn",
  "holderReference": "customer-123",
  "workflowCode": "payment-acceptance",
  "merchantReference": "order_3573894940903",
  "applePayConfigId": "default",
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  },
  "meta": {
    "order": {
      "reference": "order_3573894940903"
    },
    "customer": {
      "reference": "customer-123",
      "country": {
        "code": "DE"
      }
    },
    "clientContext": {
      "ipAddress": "217.110.239.132",
      "origin": "https://your-domain.com"
    }
  }
}

The response contains a data field — a base64-encoded string — and a version field. Pass both to your client.

{
  "version": "1.2.3",
  "data": "TG9yZW0gaXBzdW0..."
}

📘

The applePayConfigId determines which Apple Pay keys are used for this session. If you have multiple configurations (e.g. per region), pass the appropriate ID here. If omitted, the default config will be used as fallback.

Step 2: Initialize the SDK (Client-side)

Pass the data and version from your server response to Payrails.init():

import Payrails from '@payrails/web-sdk';

const payrailsClient = await Payrails.init(
  { data: '<data_from_server>', version: '<version_from_server>' }
);

Step 3: Mount the Drop-in (Client-side)

Create and mount the Drop-in component into your checkout page. Apple Pay will appear automatically if the customer's device and browser support it.

<div id="dropin-container"></div>

const dropin = payrailsClient.dropin({
  paymentMethodsConfiguration: {
    applePay: {
      showStoreInstrumentCheckbox: false
    }
  },
  events: {
    onSuccess: (event) => {
      console.log('Payment successful', event);
      // redirect to order confirmation page
    },
    onFailed: (event) => {
      console.log('Payment failed', event);
      // show error to customer
    }
  }
});

dropin.mount('#dropin-container');

📘

The Apple Pay button is only shown when the customer is on a supported device (Safari on iOS/macOS) with a card in their Apple Wallet. No additional checks are needed on your end.

Step 4: Handle payment events

The Drop-in emits the following events relevant to Apple Pay:

const dropin = payrailsClient.dropin({
  events: {
    onApplePayAvailable: () => {
      console.log('Apple Pay is available');
    },
    onRequestStart: () => {
      // customer approved in Apple Pay sheet
      // good place to show a loading state
    },
    onSuccess: (action, event) => {
      // action will be 'AUTHORIZE'
      // redirect to confirmation
    },
    onFailed: (action, event) => {
      // action will be 'AUTHORIZE'
      // show error message to customer
    },
    onPending: (action, event) => {
      // action will be 'AUTHORIZE'
    }
  }
});

📘

If you are on @payrails/web-sdk version 5.36.0 or later, use the generic events (onSuccess, onFailed, onPending, onRequestStart). The older events onAuthorizeSuccess, onAuthorizeFailed, onAuthorizePending, and onAuthorizeRequestStart are deprecated.