Apple Pay via Proxy

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.

Ways to 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:

Server-to-Server (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.

Server-to-Server (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.

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

Elements SDK (Payrails-decrypted tokens)

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.

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": {
            "softDescriptor": "Subscription"
        },
        "clientContext": {
            "host": "example.merchant.com/store"
        }
    },
    "amount": {
        "value": "12.50",
        "currency": "EUR"
    }
}

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

Render the Apple Pay button

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

const element = payrails.applePayButton({
  showStoreInstrumentCheckbox?: boolean,
  events: {
    onSuccess: (type: 'authorize' | 'tokenize', response: Generic<T>) => {
      console.log('yay!');
    },
    onFailed: () => {
      console.log('nah :(');
    },
    onPaymentButtonClicked: async() => {
      console.log('clicked');
      // If resolved to false authorization will not be triggered
      return Promise.resolve(true);
    },
    onPaymentSessionExpired() {
      console.log('session expired');
      // dropin has to be initialized with new workflow execution, contact your backend
    },
    onApplePayAvailable() {
      console.log('Apple Pay ready');
      // event will fire when Apple Pay Button is initialized 
    },
    styles: {
    	type: 'plain',
      style: 'black'
    }
  }
});

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.

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

1. For network token number, use {{networkTokenNumber}}
2. For cryptogram, use {{networkTokenCryptogram}}
3. For the expiry month of the network token, use {{networkTokenExpiryMonth}}
4. 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.