Guides
Go to payrails.com

Apple Pay

Allow customers to securely make payments using Apple Pay

Introduction

Apple Pay is a mobile payment and digital wallet service that enables customers to pay quickly and securely using their iPhone, iPad, Apple Watch, or Mac — without manually entering payment details.

Payrails supports Apple Pay across both mobile and web, and can route transactions to any supported Payment Service Provider (PSP). This guide walks you through the steps to get Apple Pay set up and accepting payments with Payrails.

The below diagram illustrates at a high level how Payrails processes Apple Pay transactions on your behalf

Choosing your Integration

Payrails offers multiple integration approaches for Apple Pay, each with different tradeoffs between customization and ease of implementation.

ApproachDescription
Drop-inThe fastest way to get started. Payrails renders the Apple Pay button and handles the entire payment flow. No additional frontend code required.
ElementsUse the Payrails Apple Pay Element for more control over button placement and styling while keeping payment processing handled by Payrails.
Server-to-serverFull control over your client-side Apple Pay implementation. You build the Apple Pay flow using Apple's native SDKs and pass the payment token to Payrails via API.

For a full comparison of integration approaches and help choosing the right one for your use case, refer to our integration approach guide.

Setup Apple Pay

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.

    Enable the Apple Pay capability in Xcode

    Create Payment Processing Certificate

    1. 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.
    Enable the Apple Pay capability in Xcode

    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.

    Enable the Apple Pay capability in Xcode

    Download domain verification file

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

    2. 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

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:

EventDescription
onApplePayAvailableFires when Apple Pay is available on the customer's device
onRequestStartFires after the customer approves payment in the Apple Pay sheet, before the authorize request is sent
onSuccessPayment was authorized successfully
onFailedPayment authorization failed
onPendingPayment is pending with no further action required

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.

Recurring payments

As with other payment methods, you can choose to tokenize the payment instrument such that it can be used for future authorizations by setting the storeInstrument parameter to true. In this case, you can expect to receive a Payrails paymentInstrumentId in the authorize notification as in the below example.

{
   "event":"executionActionCompleted",
   "time":"2023-10-26T08:48:50.057448Z",
   "details":{
      "action":"authorize",
      "actionId":"d1d7eec1-6c4d-561b-b924-e05abd1c564c",
      "amount":{...},
      "execution":{...},
      "paymentComposition":[
         {
            "amount":{...},
            "integrationType":"api",
            "operationProviderReference":"pi_3O5PFEG5MqUZQUfk1exfNecz",
            "operationResult":"Success",
            "operationType":"Authorize",
            "paymentId":"f5b277c8-db9b-4521-8625-f9bb8dd07de1",
            "paymentInstrument":{...},
            "paymentInstrumentId":"32749353-263f-4510-9572-c782ab64e599",
            "paymentMethodCode":"applePay",
            "providerConfigId":"d83d0617-784d-4181-8d28-290c948e590a",
            "providerId":"5559a584-0995-4ed4-a4bb-32f9cc2a8c39",
            "storeInstrument":true,
            "success":true
         }
      ],
      "success":true
   }
}

In order to make a subsequent authorization request using the tokenized Apple Pay payment instrument, pass the saved paymentInstrumentId in the paymentComposition as in the below example.

ℹ️

Please note that for Apple Pay payments made with a tokenized payment instrument, you must appropriately set authorization flags with us to indicate that the payment is a merchant-initiated transaction (MIT). If you indicate that the payment is a customer-initiated transaction (CIT), then the payment will be rejected. See our guide here on how to set authorization flags.

"paymentComposition":[
   {
      "amount":{
         "currency":"USD",
         "value":"1.00"
      },
      "integrationType":"api",
      "paymentInstrumentId":"32749353-263f-4510-9572-c782ab64e599",
      "paymentMethodCode":"applePay"
   }
]

Supported regions / countries

Region(s)Countries
Europe🇦🇹 Austria, 🇧🇪 Belgium, 🇧🇬 Bulgaria, 🇭🇷 Croatia, 🇨🇾 Cyprus, 🇨🇿 Czech Republic, 🇩🇰 Denmark, 🇪🇪 Estonia, 🇫🇮 Finland, 🇫🇷 France, 🇩🇪 Germany, 🇬🇮 Gibraltar, 🇬🇷 Greece, 🇭🇺 Hungary, 🇮🇸 Iceland, 🇮🇪 Ireland, 🇮🇹 Italy, 🇱🇻 Latvia, 🇱🇮 Liechtenstein, 🇱🇹 Lithuania, 🇱🇺 Luxembourg, 🇲🇹 Malta, 🇳🇱 Netherlands, 🇵🇱 Poland, 🇵🇹 Portugal, 🇷🇴 Romania, 🇸🇰 Slovakia, 🇸🇮 Slovenia, 🇪🇸 Spain, 🇸🇪 Sweden, 🇨🇭 Switzerland, 🇬🇧 UK, others..
North and Central America🇺🇸 USA, 🇲🇽 Mexico, 🇨🇦 Canada, 🇵🇷 Puerto Rico, others..
South America🇧🇷 Brazil, others..
Africa🇪🇬 Egypt, 🇲🇦 Morocco, 🇿🇦 South Africa
Asia Pacific🇦🇺 Australia, 🇭🇰 Hong Kong, 🇯🇵 Japan, 🇲🇾 Malaysia, 🇳🇿 New Zealand, 🇸🇬 Singapore, 🇹🇭 Thailand, 🇦🇪 UAE, others..

Supported workflows and services

WorkflowSupported
Available via Payrails SDK✔️
Available via Payrails API✔️
Delayed / Manual Capture✔️
Instant Capture✔️
Cancel / Void✔️
Refund / Reverse✔️
Save Instruments✔️
Merchant Initiated Transaction (MIT)✔️
InteroperabilityPSP tokens, Network tokens

Troubleshoot

Payment session fails due to merchant url validation failed for the requested session url

When the payment session fails due to merchant url validation failed for the requested session url, it usually means that the payment was attempted using a real apple pay account in staging and vice versa.

  • In staging, to test apple pay, you must create sandbox tester account and use one of the test cards. If you use a real apple pay account, you'll get this error.
  • In production, you must use a real apple pay account, otherwise you'll get this error.

One way to verify if you used a tester account or real account is to check the session URL:

  • If the session URL is https://apple-pay-gateway.apple.com/paymentservices/startSession(or https://cn-apple-pay-gateway.apple.com/paymentservices/startSession in China), then a real apple pay account was used.
  • If the session URL is https://apple-pay-gateway-cert.apple.com/paymentservices/startSession (https://cn-apple-pay-gateway-cert.apple.com/paymentservices/startSession in China), then a sandbox tester apple pay account was used.

Updated 28 days ago

Did this page help you?