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 are the necessary steps for your implementation, whether you implement Apple Pay for web or mobile, or both, as well as your integration approach as Payrails SDK or server to server.

• For web only, we can register your domain to our Apple platform to allow you to process Apple Pay payments with Payrails' certificates.
• For mobile (apps) or both mobile and web, you must use your own certificates. For this, you must maintain an Apple developer account and generate a payment processing and a merchant identity certificates as described below, as well as implementing our SDK or server to server integration which are detailed in the next sections.

Apple Pay on the web (Safari)

For web only, Payrails can register your domain so you can process Apple Pay payments with Payrails' certificates directly. All you are required to do is verify your domain using Payrails' domain association file.

Before integrating, ensure you have the following:

• A registered domain with an SSL certificate.
• Access to your server to expose our merchant domain association file as described below.

Step 1: Download Payrails' domain association file

Download Payrails' domain association file: https://api-pub.payrails.io/.well-known/apple-developer-merchantid-domain-association

Step 2: Configure the domain association file in your own domain

Configure the domain association file in your own domain under: https://<your domain>/.well-known/apple-developer-merchantid-domain-association.txt

• The file must be publicly accessible and without redirection. It must stay accessible even after the initial domain registration because Apple regularly checks the domain again.

Step 3: Request Payrails to register your domain

After exposing our domain association file, Payrails will handle the domain registration process with Apple. Contact your Payrails representative and communicate to them the list of domains to register.

Apple Pay on mobile (apps) or both mobile and web

For mobile (apps) or both mobile and web, it is required to use your own certificates. Payrails requires to use a payment processing certificate to process transactions and a merchant identity certificate to authenticate to Apple servers.

Before integrating, ensure you have the following:

• An Apple Developer account.
• A Merchant ID registered with Apple.
• For web only:
  • A registered domain with an SSL certificate.
  • Access to your server to expose our merchant domain association file as described below.

Step 1: Request your Certificate Signing Requests (CSRs) from Payrails

Please contact your Payrails representative to start the Certificate generation process: Payrails will generate 2 certificate signing requests that will then be used to retrieve the payment processing and merchant identity certificates:

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

Step 2: Download the Certificates from Apple Pay develop center

ℹ️

Note: we recommend creating distinct Apple merchant IDs for Payrails production and staging environments.

1. Go to the merchant ID list in Apple's development center to upload the CSR.
2. Select the Merchant ID you'd like to add this certificate to or register a new one if needed.
3. Look for the Apple Pay Payment Processing Certificate section and click on Create Certificate.

3. When prompted to upload a Certificate Signing Request, choose the apple_pay.csr file given by Payrails.

4. In the next page, click on Download to download the Payment Processing Certificate. You will need to send this certificate to Payrails later.
5. Go back to the merchant ID list and select again the same merchant ID.
6. Look for the Apple Pay Merchant Identity Certificate section and click on Create Certificate.

7. When prompted to upload a Certificate Signing Request, choose the merchant_id.csr file given by Payrails.

8. In the next page, click on Download to download the Merchant Identity Certificate. You will need to send this certificate to Payrails later.

Step 3: Send the Certificates to Payrails

1. Contact your Payrails representative to and send them both Payment Processing and Merchant Identify Certificates.
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.

Step 4: Register your domain (for web)

In order to process Apple Pay payments on the web, Apple needs to be able to verify that you own the domain that is used to process payments. For this, you need to register your domain in Apple developer center.

📘

Note that this step is not required for staging as Apple doesn't verify domains for payments made with test Apple accounts.

1. Go to the merchant ID list and select the merchant ID for which you previously configured certificates.
2. Look for the Merchant Domains section and click on Add domain
3. In the next page, click on Download to download the domain association file .

4. Configure the domain association file in your own domain under: https://<your domain>/.well-known/apple-developer-merchantid-domain-association.txt
   1. The file must be publicly accessible and without redirection. It must stay accessible even after the initial domain registration because Apple regularly checks the domain again.
5. Click on Verify in the Apple developer center page to veirfy the domain.

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.

If you are going with this approach, it is also important to clarify if you would like to decrypt the sensitive data inside the Apple Pay tokens or if you would like Payrails to handle that. If you want to decrypt the data on your side, note that this requires a certain PCI DSS compliance level, as well as managing the keys and certificates to decrypt the tokens on your system.

Decrypt Apple Pay tokens on Payrails side

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
        }
      ]

Decrypt Apple Pay tokens on the merchant side

Once you are ready with your own client-side implementation, and decryption of Apple Pay tokens, you can use Payrails APIs with a server-to-server integration to process payments with Apple Pay. Note that, with this approach, you will follow the Apple documentation here to build Apple Pay into your applications.

Once you are ready with the Apple integration and can have the decrypted Apple Pay tokens, you will create payment instruments to use them in Payrails orchestration platform.

Preparing the Apple Pay token

1. Apple Pay SDK will provide you with a payment token encrypted by Apple.
2. Decrypt the Apple Pay token with your integration (using your Apple Pay private keys).
3. Populate the token into the Payrails network token format as below.

{
    "cardNumber": "4111111111111111",
    "expiryMonth": "03",
    "expiryYear": "30",
    "securityCode": "ApplePayCryptogram==",
    "holderName": "John Doe",
    "holderReference": "customer123"
}

4. Encrypt the network token with the vault public key.

When you decrypt an Apple Pay token, the data you have is a PCI-sensitive data. Therefore, our API requires this value to be passed as encrypted by a public key by Payrails Vault.

The sensitive details should be encrypted with the RSA public key provided by Payrails SDK or public encryption key API, using JWE with encryption algorithm RSA-OAEP-256 and content encryption A256CBC-HS512.

Creating the Apple Pay instrument

Once you have completed the above steps, the next step will be creating an Apple Pay instrument. To do that, you have 3 options:

1. Use POST/ Create Instrument API endpoint, to create it as a separate action: In this case, send paymentMethod=applePay, pass the decrypted Apple Pay token under data.encryptedData object, with encryptedDataType=networkToken, and by providing fields like billing address and eci details. See below an example and API reference for all details of the object.

{
    "paymentMethod": "applePay",
    "displayName": "Visa 4443"
    "data": {
       "encryptedData": ".......encryptedApplePayNetworkToken.......",
       "encryptedDataType": "networkToken",
       "network": "visa",
       "eci": "07",
        "billingAddress": {
          "street": "Berlin street",
          "doornumber": "345",
          "postalCode": "30103",
          "city": "Berlin",
          "country": "DE",
        },
    }
}

2. Create an instrument as part of an Authorize action in an execution, where Authorize is an initial action during the creation of workflow execution: In this case, pass the decrypted Apple Pay token under paymentComposition.paymentInstrumentData.encryptedData object, encryptedDataType=networkToken, and by providing fields like billing address and eci details. See below an example and API reference for all details of the object.

{
   "initialActions":[
      {
         "action":"authorize",
         "method":"POST",
         "body":{
            "paymentComposition":[
               {
                  "integrationType":"api",
                  "paymentMethodCode":"applePay",
                  "amount":{
                     "value":"1.00",
                     "currency":"USD"
                  },
                  "paymentInstrumentData":{
                     "encryptedData":".......encryptedCard.......",
                     "encryptedDataType":"networkToken",
                     "network":"visa",
                     "eci":"07",
                     "billingAddress":{
                        "street":"Berlin street",
                        "doornumber":"345",
                        "postalCode":"30103",
                        "city":"Berlin",
                        "country":"DE"
                     }
                  }
               }
            ]
         }
      }
   ]
}

3. Create an instrument as part of an Authorize action in an execution, where Authorize is a separate action after the workflow execution is created: In this case, pass the decrypted Apple Pay token under paymentComposition.paymentInstrumentData.encryptedData object, encryptedDataType=networkToken, and by providing fields like billing address and eci details. See below an example and API reference for all details of the object.

{
    "paymentComposition": [
        {
            "integrationType": "api",
            "paymentMethodCode": "applePay",
            "amount": {
                "value": "1.00",
                "currency": "USD"
            },
            "paymentInstrumentData": {
              "encryptedData": ".......encryptedApplePayNetworkToken.......",
              "encryptedDataType": "networkToken",
              "network": "visa",
              "eci": "07",
                "billingAddress": {
                  "street": "Berlin street",
                  "doornumber": "345",
                  "postalCode": "30103",
                  "city": "Berlin",
                  "country": "DE",
                },
            }
        }
    ]
}

Note that to achieve full interoperability of Apple Pay instruments for all providers, it's essential to pass the ECI, Billing Address, Network, and Display name fields.

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