Ensure you have met all requirements before proceeding.
Click here for further information.
Default Process Flow
- When the customer presses the Apple Pay button, the customer will be presented with the Apple Pay payment sheet.
- 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.
Update your server-side payment form
Configure your JWT
About the 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.
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: 'your.merchant.id',
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: 'your.merchant.id',
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. 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 including symbols (26) | You will need to specify your Apple Pay Merchant ID. | ||
| 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:
|
||
| 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: 'your.merchant.id',
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:
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:
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'
}
},
});
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
After the customer has submitted the form to the “st.js”, authentication will be performed, followed by the payment. The response will be posted directly to your webserver in the form of a new JWT. If the payment is successful, the customer’s browser will be redirected to the URL specified in the form action attribute.
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.
Alternative Process flow
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
First, we add the merchantUrl property to the ApplePay method config:
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'plain',
merchantId: 'your.merchant.id',
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'
}]
}
