Introduction

Payrails enables you to integrate Apple Pay as a payment method in your app using our SDK, or natively with a direct API integration. Our platform simplifies the process of accepting Apple Pay transactions, and we can route the payment to any Payment Service Provider (PSP) of your choice. By offering Apple Pay as a payment option, you can enhance the customer experience and drive higher conversions in your app.

The below diagram illustrates at a high level how Payrails processes Apple Pay transactions on your behalf. Note that there are different approaches to implementing Apple Pay using Payrails, see pre-requisites below for more details.

Pre-requisites

The below pre-requisites and other steps required in this document may only be necessary for certain implementation approaches. The below table describes which onboarding steps are necessary for which approaches:

Before integrating Apple Pay with Payrails, ensure you have the following:

• A Payrails account.
• An Apple Developer account.
• A registered domain with an SSL certificate.
• A Merchant ID registered with Apple.
• Access to your server to generate and store certificates.

Generate a Payment Processing Certificate

Step 1: Generate a CSR

Since Payrails will decrypt the Apple Pay payment token, we need to host an Apple Payment Processing Certificate. The first step to generating this certificate is for us to generate a Certificate Signing Request (CSR), which you will then need to upload to Apple.

Please contact your Payrails representative to start the Certificate generation process.

Step 2: Upload the CSR to Apple

1. Go to this link in Apple's development center to upload the CSR
2. Select the Merchant ID you'd like to add this certificate to, then click 'Create Certificate' in the Apple Pay Payment Processing Certificate section.
3. When it prompts you to upload a Certificate Signing Request, choose the .certSigningRequest file you just downloaded.

Step 3: Download the signed payment processing certificate from Apple

Download (and backup) the Apple signed Payment Processing Certificate, apple_pay.cer.

Step 4: Send Payrails the Payment Processing Certificate

1. Contact your Payrails representative to transfer the signed Certificate, which we will store and use for decrypting transactions.
2. Go back to this page on Apple's Developer Center, select the MerchantID, and activate the Apple Pay Payment Processing Certificate you just created.

Apple Pay on the web (Safari)

Generate a Merchant Identity Certificate

An Apple merchant identity certificate is a Transport Layer Security (TLS) certificate associated with your merchant ID, used to authenticate your sessions with the Apple Pay servers. The merchant identity certificate is only required for Apple Pay on the web; it isn’t needed for apps.

Payrails will handle the domain registration process with Apple, so all you need to do is provide us with the domain name, merchant identity certificate, and store a domain verification file on your server.

Step 1: Create a Merchant Identity Certificate and generate a domain verification file.

In the Apple developer portal, select the merchant ID you will use at this link. Under "Apple Pay Merchant Identity Certificate", click "Create Certificate" and follow the instructions to create a Merchant Identity Certificate using the CSR we provided you.

You also need to register your domain name under your Apple Merchant ID. Click "Add Domain" under "Merchant Domains" to do this. Then, you will download a domain verification file and host the verification file at your domain in the following location:

https://example.com/.well-known/apple-developer-merchantid-domain-association.txt

Step 2: Send to Payrails the Merchant Identity Certificate

Contact your Payrails representative to transfer the Merchant Identity Certificate, which we will store and use to start sessions for Apple on the Web. You also need to inform us of the domain you registered where you will host the verification file. From there we will take care of the rest and you are ready to accept Apple Pay payments via Safari.

Payrails integration configurations

Before you start accepting Apple Pay payments with Payrails, there are a few requirements you must meet:

1. Integrate with Payrails using one of our SDKs or our API
2. Configure a new integration account for cards via one of the following Payment Service Providers:
   Stripe, Checkout.com, Adyen or HyperPay
3. Enable Apple Pay as a payment option.
4. Make sure you're sending the provider specific card meta fields (found under Merchant configurations -> Meta fields on your Payrails dashboard and in the examples below) in your requests.

Ways to integrate

Payrails SDK

The simplest way to use Apple Pay with Payrails is to use our drop-in in your checkout flow. With this integration type, no additional development work is required to accept payments with Apple Pay.

For a more flexible implementation using our SDK, you can use our Apple Pay element. See special instructions here for your client-side implementation.

Server-to-server integration

You also have the option to completely manage your own client-side implementation, and use Payrails APIs with a server-to-server integration to process payments with Apple Pay. With this approach, follow the Apple documentation here to build Apple Pay into your applications.

Pass Apple Pay configuration in lookup response to Apple Pay SDK (optional)

With a server-to-server integration, you can call our lookup payment options endpoint to get available payment options and relevant configurations for each payment method. See the below example of paymentCompositionOptions containing an Apple Pay configuration that you can pass to the Apple Pay SDK. Please contact your Payrails representative during the onboarding phase in order to set these configurations before going live.

"paymentCompositionOptions":[
   {
      "config":{
         "parameters":{
            "countryCode":"DE",
            "merchantCapabilities":[
               "supports3DS",
               "supportsCredit",
               "supportsDebit"
            ],
            "merchantIdentifier":"merchant.payrails.testing",
            "supportedNetworks":[
               "AMEX",
               "DISCOVER",
               "INTERAC",
               "JCB",
               "VISA",
               "MASTERCARD"
            ]
         },
         "type":"CARD"
      },
      "description":"ApplePay",
      "integrationType":"api",
      "paymentMethodCode":"applePay"
   }
]

Create an Apple Pay payment session via Payrails (optional, web only)

For payments made on Safari, you must create an Apple Pay payment session as part of providing merchant validation. Our Web SDK does this for you, but in case you are not using it, you have two options:

1. Call our Start a session endpoint
2. Implement an API endpoint on your server as described in the Apple documentation

ℹ️

We recommend using our endpoint to start a session, otherwise you must fulfil additional requirements from Apple in setting up your server for validation.

You will then pass the opaque Apple Pay session object in the response to the Apple Pay JS SDK's completion method, completeMerchantValidation. In case you use our endpoint, this can be found in the data object as in the below example:

{
  "name": "startPaymentSession",
  "actionId": "1aa0ef20-36cb-4485-b60e-0526c3699014",
  "executedAt": "2022-02-03T14:38:40.557Z",
  "data": {
    "id": "SSH268E...",
    "data": {
      "displayName": "Test Merchant",
      "domainName": "https://merchantdomain.com",
      "epochTimestamp": 1717486879562,
      "expiresAt": 1717490479562,
      "merchantIdentifier": "E92FBE...",
      "merchantSessionIdentifier": "SSH268E...",
      "nonce": "fd3...",
      "operationalAnalyticsIdentifier": "Test Merchant:E92FBE...",
      "pspId": "E92FBE...",
      "retries": 0,
      "signature": "30800..."
    }
  },
  "links": {
    "execution": "https://payrails-api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016"
  }
}

Pass Apple Pay payment token in request to authorize payment with Payrails

When you initiate a transaction with the Apple Pay SDK, a Payment Token (PKPaymentToken) containing a JSON-formatted paymentData string is sent to the merchant app. Pass the token received from Apple Pay in the paymentComposition in your authorization request as in the below example:

"paymentComposition": [
        {
          "amount": {
            "currency": "USD",
            "value": "1.00"
          },
          "enrollInstrumentToNetworkOffers": false,
          "integrationType": "api",
          "paymentInstrumentData": {
            "card": null,
            "paymentToken": "{\"paymentData\":{\"data\":\"rZ21swGREmmzhBE28M7Mp86lYgLcCH5hg95AcEAtKd71z0A8t3/SLbhoQDLZaCJB8z56idCTEzObJGKZAZFIrWHlPE2Yk4fdSVneHUGS/0uuYiClAmR5Ouq4dY0P/auvePbh/9+OXAIg4sJrsKucShXFpPLbEkTSiKAHBjA3iJNqIVaJt75uKLE/CvxFc73WaVpvimQAX/nvdKQfxpDMDv2dv13cB3zN8CUK6k+epsB4Ih91THraklUuWr3CAI28BvwZ3G9qI8RWYJhws+HONIjJIrtOZ4CE23f5BP2qZOO8yo4MOgIXzHhGjW3+eTVydHjkGrlyLkVyYuCr/vtleSavjM7ynCapzxe6g5jM9a5irjR5BDotf3VdyR9Z4QN9yevg/I0I+gvXuRAWu3ArGRGASOGh1s4T0FMGRc6weQ==\",\"signature\":\"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\",\"header\":{\"publicKeyHash\":\"4hgujwrBOqkgH+GY8ySQYfOcp2mT/b3foYD296PLL7M=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDm4RqDgJ5xlDt0Dqjg1zpyjG+yxeF1F6jXx/xT6m/uFPvhkpd/SzkqInwQzj77B3qDGGjKGQmtTgJVKYo4ebdw==\",\"transactionId\":\"da6123436b370cc24a277e63b4bea66e5e0c1c1d6fc9a77756aa750ac7af762b\"},\"version\":\"EC_v1\"},\"paymentMethod\":{\"displayName\":\"Visa 0121\",\"network\":\"Visa\",\"type\":\"credit\"},\"transactionIdentifier\":\"da6123436b370cc24a277e63b4bea66e5e0c1c1d6fc9a77756aa750ac7af762b\",\"paymentNetwork\":\"Visa\",\"paymentInstrumentName\":\"Visa 0121\"}",
            "providerData": null,
            "vaultToken": ""
          },
          "paymentMethodCode": "applePay",
          "storeInstrument": false
        }
      ]

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

Supported workflows and services