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.

Pre-requisites

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

Go to this link in Apple's development center to upload the CSR
Select the Merchant ID you'd like to add this certificate to, then click 'Create Certificate' in the Apple Pay Payment Processing Certificate section.
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

Contact your Payrails representative to transfer the signed Certificate, which we will store and use for decrypting transactions.
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.

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

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\":\"4IMocV/n1YoHpJhz9N59tqIHo9JCkWpUxrGnjEXaUulk2wYnKcI5s5onAydrVvqGAOD+X0aN95dsDj8t0v+9FwMX+llKQLHouEILbSX+1aj5Y75wOnmwumzh6hRqmLoNjbBvjs5wcy/cliggbrY+J6NQpBBZ17BruiYPGJwHr2Myt/zdOhYdwHhOPpAAHDJICWi0GSXaB5GL1f/vcBgfk4WB3nCmM6DZwgpbintIxDh48EdS1GasXm81Frc997bHr4RT5oIErn3sfVMFrUoeqiyvAey61WYwsWiW6zZP3sIjVFvWQXoGaKGZZUgHyGog1VS5oPaJbkWyhkA46F6U9AQecltvoq5oy8oCDfD1W196kY7PQrBdggmmNupPO+XiRAJzaQtBZxBbtTawj2YGG9GRMUsYHyyhZz1W3NulQg==\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIzMTAyNjA5MTMwOVowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIHvyM12VH7pVvqi6wP9dC0ig2v1j3yKEfgj+LBh4lbrfMAoGCCqGSM49BAMCBEgwRgIhAKC0uV/Ff+dNSjP6Z7GVbni+3dA77ZXBxc0dN4lc98HUAiEA8Cz7OmJsXeJeFJcCJnpxTGUcr8dVxKE0sOmSDXzw9AkAAAAAAAA=\",\"header\":{\"publicKeyHash\":\"4hgujwrBOqkgH+GY8ySQYfOcp2mT/b3foYD296PLL7M=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaTAFmRof5B6d9btkMWToGIcW8woVIOf1XdhsdRFwh1iix5N0RLZ/efG9BiRz6pUL9dB5zKdzxEOD3QaRei7WGA==\",\"transactionId\":\"3fc8dc048b9e6d3e67607f09acb4e7c64a57bd2cdb396e0b8d18961ff8fac173\"},\"version\":\"EC_v1\"},\"transactionIdentifier\":\"3fc8dc048b9e6d3e67607f09acb4e7c64a57bd2cdb396e0b8d18961ff8fac173\",\"paymentNetwork\":\"Visa\",\"paymentInstrumentName\":\"Visa 0253\"}",
            "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"
   }
]