Apple Pay for JavaScript Library

What is Apple Pay?

Apple Pay is a wallet-based mobile payment service by Apple Inc. that lets users process payments using an iPhone, iPad or Mac. Customers benefit from a familiar and streamlined checkout experience, where their billing information can be pre-filled, ready for purchase. Customers are authenticated quickly by placing their finger on the built-in reader or through facial-recognition. Apple Pay uses tokens to ensure no sensitive payment information is stored with Apple, on the customer’s device or on your own servers.

This article explains how to integrate Apple Pay into your payment solution using our JavaScript Library.

Only eligible customers can complete transactions using Apple Pay. For instance, customers must use a supported Apple device and be located within a country where Apple Pay operates. Please refer to Apple’s documentation (link to external site) for the full list of requirements.

In May 2024, we simplified the process of integrating with Apple Pay

If you integrated Apple Pay with Trust Payments before this change:

You can find our older documentation by clicking here.
But we recommend reviewing the process below when next renewing your certificates.

Requirements

Ensure you have met the following requirements before integrating Apple Pay into your checkout solution:

Your acquiring bank must support
Apple Pay with Trust Payments.

Contact Support Team if unsure

Your server must meet the following requirements:

Must support the Transport Layer Security (TLS) 1.2 protocol or higher.
Must support one of the cipher suites listed in Apple’s documentation (link to external site).
Must meet high security standards (e.g. If using SSL Labs (link to external site) to check certificate, an A grade would be required).

In order to test your solution, you need to have access to a device that supports Apple’s sandbox testing for Apple Pay.

Supported devices

You will need to have a sandbox tester account in order to add test cards to your wallet, in order to process Apple Pay test transactions.

Learn about sandboxes

Setting up and verifying your domains

Begin by downloading the domain-verification file below and placing it on your domains where Apple Pay is to be displayed:

Click here to download

You must prepare each domain by hosting the received domain-verification file in this location, as this will be publicly queried to complete the domain registration process:
```
https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association
```
Ensure the file and the hidden .well-known directory are given read and execute permissions. (For Unix, this is typically done by using the command chmod 755 <filename or folder>).

As part of the Apple Pay validation process, Apple requires that the validation file returns an HTTP 200 OK response. Any other HTTP response code, such as a 301 Moved Permanently, will be treated as a failure. To ensure Apple Pay works properly, the validation file must be configured to always return an HTTP 200 OK response.
Have your authorised contact reach out to our Support Team and request to have Apple Pay enabled on your site reference(s). In your email, we require you to attach a CSV file that contains a list of all of the site references you intend to register and their associated domain(s).

The format of the CSV file must be as follows:
```
Site reference, Domain name
```
For example:
```
site10001, example.com
site10002, trustpayments.com
test_site10003, trustpayments.com
```
Please include all relevant test and live site references and domains in the file.
Our Support Team will update you once the registration process for the specified domains is complete and that you can begin processing Apple Pay transactions.

If you have previously integrated Apple Pay using our JavaScript Library but have since adopted the new registration process described above, you must ensure that the property merchantId in the configuration passed to the st.js ApplePay method has been updated to specify your site reference instead of the Apple Pay Merchant Id. This is because the domains are now linked to your site reference rather than your Apple Pay Merchant Id.

Configure Apple Pay solution

Once you have set up and verified your domains for Apple Pay, you will need to integrate using one of the following flows described below:

Flow 1 - JavaScript determines when the AUTH is submitted

When the customer presses the Apple Pay button, the customer will be presented with the Apple Pay payment sheet.
The customer approves the payment using Touch ID, Face ID or their passcode.
When the customer agrees to the payment, an AUTH request is submitted to Trust Payments.
Trust Payments contacts the acquiring bank to request authorisation for the transaction.

Instructions for Flow 1

Configure your JWT

JSON Web Tokens (JWT) are an open, industry standard RFC 7519 method for securely transmitting data between two parties. It protects against the modification of critical transaction data (e.g. the amount to be debited) by unauthorised parties during the payment session.

For this reason, this field is required in order to process payments with Trust Payments.

Click here to learn how to generate the JWT

Depending on your preferred configuration, you may need to include an extra field in the payload when generating the JWT for your checkout form.

To allow the customer to choose a billing or delivery address stored on their Apple account from the payment sheet (instead of an address entered on your checkout), you must include the optional fields billingcontactdetailsoverride and customercontactdetailsoverride respectively, with the value “1”.

Otherwise, the JWT does not need to be modified to process Apple Pay transactions.

Apple Pay library

When the customer taps the Apple Pay button, our st.js contacts Apple to initiate the payment session and display the payment sheet. To enable this behaviour, you will need to reference the Apple Pay library by including additional markup on your payment form, as shown in the tabs below.

First of all, you will need to add a div placeholder into the payment form, like so:

<div id="st-apple-pay"></div>

Then you will need to update your Javascript to also call our Apple Pay library:

st.ApplePay({
  buttonStyle: 'white-outline',
  buttonText: 'plain',
  merchantId: 'test_site12345',
  paymentRequest: {
    countryCode: 'US',
    currencyCode: 'USD',
    merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
    supportedNetworks: ["visa","masterCard","amex"],
    requiredBillingContactFields: ["postalAddress"],
    requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
    total: {
      label: 'Trust Payments Merchant',
      amount: '10.00'
    }
  },
  buttonPlacement: 'st-apple-pay'
});

In the example above, the Apple Pay button is configured to process a transaction for $10.00, using a credit or debit card. In addition, required billing and delivery fields are specified. For this transaction, the customer would need to provide these details in order to complete the payment. Required fields can be customised to your preference, or removed entirely if not needed.

Your finished markup will look like this:

<html>
  <head>
  </head>
  <body>
    <div id="st-notification-frame"></div>
    <form id="st-form" action="https://www.example.com"/>
    <div id="st-apple-pay"></div>
    <script src="<CDN_DOMAIN>"></script>
    <script> 
      (function() {
        var st = SecureTrading({ 
          jwt: 'INSERT YOUR JWT HERE', 
        }); 
        st.ApplePay({
          buttonStyle: 'white-outline',
          buttonText: 'plain',
          merchantId: 'test_site12345',
          paymentRequest: {
            countryCode: 'US',
            currencyCode: 'USD',
            merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
            supportedNetworks: ["visa","masterCard","amex"],
            requiredBillingContactFields: ["postalAddress"],
            requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
            total: {
              label: 'Trust Payments Merchant',
              amount: '10.00'
            }
          },
          buttonPlacement: 'st-apple-pay'
        });
      })(); 
    </script>
  </body>
</html>

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.

Field specification

Button fields

Field	Format	Description
buttonStyle	Alphanumeric	Used to change the appearance of the Apple Pay button. Click here for further information (link to external site).
buttonText	Alphanumeric	Used to change the text that appears on the Apple Pay button. Click here for further information (link to external site).
buttonPlacement	Alphanumeric	By default, the library searches for a div id called "st-apple-pay" in order to determine where the Apple Pay button should be placed on the form. If you are not using the default div id, you will need to specify your custom id as the value of the buttonPlacement property. e.g. `buttonPlacement: 'apple-button'` Dev note: Property placement is deprecated and is no longer supported. Please use the replacement buttonPlacement property instead.

Useful resources regarding the Apple Pay button

You can change the colour of the button and the text displayed to better suit the needs of your checkout.
Click here to learn more (link to external site).

Apple has published guidelines on how to best position the Apple Pay button on your checkout.
Click here to learn more (link to external site).

st.ApplePay({
  buttonStyle: 'white-outline',
  buttonText: 'plain',
  buttonPlacement: 'st-apple-pay'
});

Merchant fields

Field		Format	Description
merchantId		Alphanumeric & underscore (50)	The value assigned to merchantId must be the site reference that is associated with the domain that is calling the ApplePay method, as specified in the CSV sent to the Support Team during the domain verification process. The merchantId submitted here must be the same as the sitereference submitted in the JWT.
paymentRequest		Object	This object contains information about the payment, which will be sent off to Apple in the initial request (our Javascript sends this).
	countryCode	Alpha (2)	The merchant’s country code in ISO2a format.
	merchantCapabilities	List	The payment capabilities supported by the merchant. The field must contain “supports3DS” (to enable Touch ID / Face ID verification), and at least one of the following additional values: “supportsCredit” – To enable credit card payments. “supportsDebit” – To enable debit card payments. For a full specification, please refer to Apple’s own documentation (link to external site).
	supportedNetworks	List	The payment networks supported by the merchant. The value must be one or more of the following: “amex“, “masterCard” or “visa“.
	supportedCountries	Array of strings	A list of two-character country codes you provide (in ISO2a format). Apple Pay transactions are limited to cards issued in countries listed in this property. The supportedCountries list does not affect the currency used for the transaction, and it applies to all payment cards in the wallet.

st.ApplePay({
  merchantId: 'test_site12345',
  paymentRequest: {
    countryCode: 'US',
    merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
    supportedNetworks: ["visa","masterCard","amex"],
  },
});

Transaction fields

Field			Format	Description
paymentRequest			Object	This object contains information about the payment, which will be sent off to Apple in the initial request (our Javascript sends this).
	requiredBillingContactFields		List	On the payment sheet, this field is used to prompt the customer to choose their preferred billing address details from their Apple Pay account, prior to purchase. The payment sheet will NOT display any billing address details posted from your checkout. You can submit the following field values: “postalAddress” This is required when the customer is to complete the purchase using billing address fields saved on their Apple Pay account.
	requiredShippingContactFields		List	On the payment sheet, this field is used to prompt the customer to choose their preferred delivery address details from their Apple Pay account, prior to purchase. The payment sheet will NOT display any delivery address details posted from your checkout. You can submit the following field values: “postalAddress” “name” “phone” “email” This is required when the customer is to complete the purchase using delivery address fields saved on their Apple Pay account.
	currencyCode		Alpha (3)	The transaction currency code in ISO3a format.
	total		N/A	A line item representing the total for the payment.
		amount	Numeric including decimal place (14)	The amount of the transaction in main units, using a decimal point to denote decimal values, so £10 is returned as 10.00. This must be the same amount as submitted within the payload of the JWT. It’s critical that the amount submitted in the JWT is correct, as this is the value that determines the amount the customer is to debited.
		label	Alphanumeric including symbols	This is a comment to be displayed on the Apple Pay payment sheet, next to the total amount, prior to the customer agreeing to the payment.

st.ApplePay({
  paymentRequest: {
    currencyCode: 'USD',
    requiredBillingContactFields: ["postalAddress"],
    requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
    total: {
      label: 'Trust Payments Merchant',
      amount: '10.00'
    }
  },
});

Flow 2 - Merchant determines when the AUTH is submitted

For merchants who would rather receive the Apple wallettoken data and send an API request to process the AUTH themselves, the property merchantUrl should be set in the st.js st.ApplePay method config.

When the customer presses the Apple Pay button, the customer will be presented with the Apple Pay payment sheet.
The customer approves the payment using Touch ID, Face ID or their passcode.
merchantUrl is sent a request from the JavaScript containing the wallet details.
An AUTH request is sent by the merchantUrl to Trust Payments using our Webservices API.
Once the payment result is returned by Trust Payments to the merchantUrl, a response JWT should be sent back to the st.js library to update the Apple Payment sheet

Instructions for Flow 2

First, we add the merchantUrl property to the ApplePay method config:

st.ApplePay({
  buttonStyle: 'white-outline',
  buttonText: 'plain',
  merchantId: 'test_site12345',
  paymentRequest: {
    countryCode: 'US',
    currencyCode: 'USD',
    merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
    supportedNetworks: ["visa","masterCard"],
    requiredBillingContactFields: ["postalAddress"],
    requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
    total: {
      label: 'Trust Payments Merchant',
      amount: '10.00'
    }
  },
  buttonPlacement: 'st-apple-pay'
  merchantUrl:'<payment URL endpoint>'
});

The following is an example request sent from the JavaScript to merchantUrl once the customer has authenticated the transaction using Touch ID, Face ID or passcode:

{
  "request": [
    {
      "walletsource": "APPLEPAY",
      "wallettoken": "<json encoded string>",
    }
  ],
  "jwt": "<jwt token>",
  "acceptcustomeroutput": "2.00",
  "version": "1.00",
  "versioninfo": "STJS::N/A::3.2.0::N/A"
}

At this point, it is assumed that the merchantUrl will make an API request to Trust Payments to process the authorisation.

For an example of how to send the AUTH using our webservices API, please refer to the "AUTH request" section on this article.

The merchantUrl response to the st.js should be a JWT response. You will need to parse the AUTH response and include the returned fields in the payload of the response <JWT Token>, as shown below.

{
  jwt:<JWT Token>
}

The payload of the JWT token should be encoded with the following object:

{'version': '1.00',
  'response': [{
    'walletsource': 'APPLEPAY',
    'errormessage': 'Ok',
    'sitereference': '<test or live sitereference>',
    'errorcode': '0',
    'requesttypedescription': 'AUTH'
  }]
}

Understanding the payment sheet

Prior to completing the purchase, the payment sheet is displayed to the customer. This presents the customer with cards previously-saved on their account, options for delivery, contact information and the full purchase amount (including tax and fees). They can review the order and optionally make adjustments before proceeding.

Card

The customer will be able to select from the cards saved in their Apple Wallet (link to external site).
The cards supported for payment are dependent on the merchantCapabilities field posted on the checkout.
e.g. If “supportsDebit” is not included in the field, the customer will not be able to complete their payment with a debit card.

Address

The billing and shipping address will only be displayed on the payment sheet if the fields requiredBillingContactFields and requiredShippingContactFields have been submitted with valid values. This allows the customer to select from billing and/or shipping addresses saved on their Apple account.

The address selected on the payment sheet will only be included in the AUTH request if the fields billingcontactdetailsoverride and customercontactdetailsoverride have been submitted, with the value “1”.

Label and amount

The mainamount value is displayed on the payment sheet, alongside the label, posted on the checkout. In the example here, the label was submitted with the value “Outstanding balance”.

Authentication

The method of authentication will differ based on the device being used to complete the payment. The customer may be prompted to place their finger on the Touch ID sensor, or look at the Face ID sensor.
Click here for further information on Apple Pay authentication (link to external site).

Payment completion

Once the customer has been successfully authenticated on the payment sheet, the next step is to process the transaction:

If utilising Flow 1, the authorisation will be performed automatically by st.js.
If utilising Flow 2, your configuration will need to process the AUTH request manually using the Webservices API and update the payment sheet with the result.

The Apple Pay payment sheet will update to show either a success or failure message, depending on the outcome of the payment. Following a success case, the payment sheet will close to indicate the payment is complete.

MyST

As with regular card payments, records of all AUTH transactions processed using Apple Pay can be viewed in MyST. When viewing Apple Pay transactions in MyST, the “Wallet source” will be displayed as “APPLEPAY”. Click here to view our MyST documentation.

Testing

Your test site reference will connect to the Apple Pay testing sandbox. Therefore, in order to process payments on your test site reference, you will need to add test card details to the Apple Wallet on your supported device(s).

You will be required to use the test card details provided by Apple. Please refer to the following URL:
https://developer.apple.com/support/apple-pay-sandbox/ (link to external site)

The above assumes you are signed in to your device with an Apple sandbox account.

Please be aware that the test card details we provide in our testing documentation cannot be used when processing Apple Pay test transactions.

If you have enabled User-Defined Rules (UDR) on you site reference(s), you will need to ensure that you understand how they may affect your Apple Pay transactions.
If you require any assistance, please contact our Support Team.

Performing additional requests

When processing e-commerce payments using Apple Pay, you can configure your solution to include additional requests to perform extra tasks. These are as follows:

You will need to update the JWT payload to include the list requesttypedescriptions with the following supported request combinations:

If your app is offering other card payment methods alongside Apple Pay, it is imperative that you include “THREEDQUERY” in the requesttypedescriptions list, because without it 3-D Secure authentication would not be performed for the aforementioned card payment methods. If the customer chooses to process the payment using Apple Pay, the gateway will purposely omit the THREEDQUERY automatically as it would not be needed in that case.

[“ACCOUNTCHECK”, “THREEDQUERY”, “AUTH”]
[“RISKDEC”, “ACCOUNTCHECK”, “THREEDQUERY”, “AUTH”]
[“RISKDEC”, “ACCOUNTCHECK”, “THREEDQUERY”, “AUTH”, “SUBSCRIPTION”]
[“RISKDEC”, “THREEDQUERY”, “AUTH”]
[“RISKDEC”, “THREEDQUERY”, “AUTH”, “SUBSCRIPTION”]
[“THREEDQUERY”, “ACCOUNTCHECK”, “SUBSCRIPTION”]
[“THREEDQUERY”, “AUTH”]
[“THREEDQUERY”, “AUTH”, “RISKDEC”]
[“THREEDQUERY”, “AUTH”, “SUBSCRIPTION”]

Further reading on this topic