Payrails allows the use of tokenized Apple Pay instruments via the Instant Proxy integration. This allows merchants to forward sensitive Apple Pay data to supported payment providers without decrypting or storing the Apple Pay network token on their end.

Tokenize Apple Pay instruments

Before an Apple Pay token can be used in Instant proxy, we need to tokenize it and create an Instrument for it. Check our Apple Pay guide for detailed information on how to set up a new integration by storing the keys and certificates of your Apple Pay account to be able to decrypt Apple Pay tokens on your behalf.

Payrails offers multiple ways to tokenize the card information, depending on the PCI DSS scope you are willing to own, the requirements about the level of control you need on your checkout page, and ease of implementation.

Here's a table comparing your options from a high-level perspective:

Tokenization Type	Integration Effort	PCI Scope
Apple Button Element SDK with Payrails decryption	Low	Low (SAQ and AOC)
Server-to-Server with Payrails decryption	Medium	Low (SAQ and AOC)
Server-to-Server with Merchant decryption	High	High (Level 1 ROC and AOC)

1. Apple Pay Button Element SDK with Payrails-decrypted tokens

This feature is in beta mode right now, and soon will be available.

Payrails Elements are payment UI components you can assemble together to build a payment form, giving better flexibility than Drop-in with the ability to manage each element separately. Check our Elements guide for more detailed information.

Elements provides merchants with easy integration to Apple Pay tokenization without having the need to set up any integration with the Apple Pay SDK directly. Payrails manages all the keys needed for completing the Apple Pay session and detokenization, reducing all merchant overhead. Check out the Apple Pay Button Element for a detailed guide.

For details of how to integrate this option, move to this section .

2. Server-to-Server with Payrails-decrypted tokens

In this integration method, the merchant maintains control over their Apple Pay integration, but they do not maintain the keys needed to decrypt the Apple Pay tokens. This provides merchants flexibility to keep their own Apple Pay SDK integration while not touching sensitive data in their servers.

For this flow, once you obtain the encrypted Apple Pay token object from your direct integration with Apple, use Create Instrument API endpoint to pass it to Payrails. You will use encyrptedData object to pass the Apple Pay token, alongside encryptedDataType passed as 'networkToken', since Apple Pay digital wallet uses network tokens technology. Once you create the instrument, you are returned an instrumentId in the API response, and you can start passing this instrumentId in the Proxy API requests.

For details of how to integrate this option, move to this section.

3. Server-to-Server with merchant-decrypted tokens

This integration method allows merchant to maintain control over their Apple Pay integration. Merchants implement the Apple Pay SDK integration and decryption of the Apple Pay token, and directly provide the decrypted network token to Payrails. This requires the necessary level of PCI compliance to be able to store and process PCI-sensitive data on your servers.

For details of how to integrate this option, move to this section.

You can jump to this section to learn how to pass an Apple Pay instrument in a proxy API.

1. Apple Pay Button Element SDK with Payrails-decrypted tokens

This feature is in beta mode right now, and soon will be available.

Setting up the Apple Pay button element for tokenization

Perform Client init with Intent "tokenization"

Perform a Client init with intent "tokenization`

{
    "type": "tokenization",
    "meta": {
        "order": {
            "softDescription": "Subscription"
        },
        "clientContext": {
            "host": "example.merchant.com/store"
        }
    },
    "amount": {
        "value": "0.00",
        "currency": "EUR"
    }
}

Provide the display name for the Apple Pay payment sheet in meta.order.softDescription
Provide the merchant store page initiative context in meta.clientContext.host
Provide the amount in amount

Render the Apple Pay button

import { Payrails } from '@payrails/web-sdk';
// Call the backend to get the init response
const initResponse = giveMeInitResponseFromBackend();
// Initialize client
const Payrails = Payrails.init(initResponse);

const element = payrails.applePayButton({
  events: {
    onSuccess: (type: 'TOKENIZE', instrument?: any) => {
      console.log('yay!');
    },
    onFailed: (type: 'TOKENIZE', error?: any) => {
      console.log('nah :(');
    },
    onButtonClicked: async () => {
      console.log('button clicked');
      // If resolved to false, process will STOP before applePay session creation
      return Promise.resolve(true);
    },
    onRequestStart: async () => {
      console.log('Requesting...');
			// If resolved to false, process will STOP before instrument creation
		},
    onApplePayAvailable() => {
      console.log('Apple Pay ready');
      // event will fire when Apple Pay Button is initialized 
    },
    styles: {
    	type: 'plain',
      style: 'black'
    }
  },
  translations: {
    labels: {
      paymentScreenLabel: "Checkout with applePay" 
		}
  }
});

element.mount('#apple-pay-button-container');

Listen to the onSuccess callback for the event of type TOKENIZE to get the details for the newly created Apple Pay Instrument

Once the instrument has been created, it can be used in the instant proxy in your backend service. Jump to this section to read more.

2. Server-to-Server with Payrails-decrypted tokens

If you prefer to use your own client-side implementation for Apple Pay button, where you receive the encrypted Apple Pay token, 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.

In this flow, although you receive the Apple Pay token from Apple, you can pass it to Payrails to decrypt it on your behalf, so that you don't have to manage PCI-sensitive data on your servers. In order for Payrails to decyrpt the Apple Pay tokens, follow our guide to share your certificate and key with Payrails.

Once you are ready with the Apple integration and get an Apple Pay token object, you will create payment instruments to use them in Payrails proxy APIs.

Creating the Apple Pay instrument in Payrails

Once you have completed the above steps, Apple Pay SDK will provide you with payment tokens encrypted by Apple.

Use POST/ Create Instrument API endpoint, send paymentMethod=applePay, and 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",
        },
    }
}

Once the instrument has been created, it can be used in the instant proxy in your backend service. Jump to this section to read more.

3. Server-to-Server with merchant-decrypted tokens

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 proxy APIs.

Preparing the Apple Pay token

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

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

Encrypt the network token with the vault public key.

Note that when you decrypt an Apple Pay token, the data you have is 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. Use POST/ Create Instrument API endpoint, send paymentMethod=applePay, and 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",
        },
    }
}

Once the instrument has been created, it can be used in the instant proxy in your backend service. Move to the next section to read more.

Using Apple Pay instrument in Instant Proxy

With the instrument created, you can now forward it to your payment providers via Instant Proxy. Check out the Instant Proxy for a detailed guide.

Prepare the request body you want to pass to the payment provider based on the provider's API contract.

This request will include fields that are non-sensitive (i.e. amount), as well as the card information that is PCI sensitive. You will put {{key}} in the place of the sensitive fields, while forwarding the rest of the payload as it is. Read in the next section what the key variables you will use are in more detail.

This is the body object you will see under Vault Proxy API.

Prepare the request headers that are needed to be passed to the payment provider.

The payment providers typically require certain headers to securely receive a request from the senders, such as authentication or authorization keys. In order for us to send a request to the payment provider, we need to provide those headers when forwarding your request to the provider. You will provide all required header information defined by the provider's API contract.

This is the headers object in Vault Proxy API.

Prepare the URL of the provider that you want Payrails to forward the request.

You have to define a destination URL path for every proxy request that you want to send. This is the URL of the API endpoint of the payment provider. You will pass it to Payrails, so that we can send your request body and headers you prepared in the previous steps to the designated URL.

This is url object in Vault Proxy API.

Below you can find some examples of some well-known providers and how you should map the card data using our instruments.

{
  "paymentInstrumentId":"eeaac45c-f032-49bc-a8c5-ec99d79b74e2",
  "url":"https://api.sandbox.checkout.com/payments",
  "headers":{
    "x-API-key":"YOUR_API_KEY",
    "Content-Type":"application/json"
  },
  "body":{
    "amount":1000,
    "currency":"USD",
    "reference":"some_reference",
    "source":{
      "type":"network_token",
      "token_type": "applepay",
      "token":"{{networkTokenNumber}}",
      "expiry_month":"{{networkTokenExpiryMonth}}",
      "expiry_year":"{{networkTokenExpiryYear}}",
      "cryptogram":"{{networkTokenCryptogram}}",
      "name":"{{cardHolderName}}"
    },
    "payment_type":"Regular",
    "authorization_type":"Final",
    "capture":true,
    "processing_channel_id":"pc_xxxxxxxxxxx",
    "risk":{
      "enabled":false
    },
    "merchant_initiated":true
  }
}

{
  "paymentInstrumentId":"eeaac45c-f032-49bc-a8c5-ec99d79b74e2",
  "url":"https://api.stripe.com/v1/payment_methods",
  "headers":{
    "Authorization":"***",
    "Content-Type":"application/x-www-form-urlencoded"
  },
  "body":"type=card&network_token[exp_month]={{networkTokenExpiryMonth}}&network_token[exp_year]={{networkTokenExpiryYear}}&network_token[number]={{networkTokenNumber}}&network_token[cryptogram]={{networkTokenCryptogram}}"
}

For network token number, use {{networkTokenNumber}}
For cryptogram, use {{networkTokenCryptogram}}
For the expiry month of the network token, use {{networkTokenExpiryMonth}}
For the expiry year of the network token, if:
1. 4-digit expiry year of the network token, use {{networkTokenExpiryYear}}
2. 2-digit expiry year of the network token, use {{networkTokenExpiryYear2Digits}}

❗️
Apple Pay tokens will always contain a network token in them, always use the network token place holders when making a proxy request for an apple pay instrument.