Configure your solution
Process overview
- 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
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.
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: 'pay',
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'
}
},
placement: '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=<DOMAIN>/js/v3/st.js></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
});
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'pay',
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'
}
},
placement: 'st-apple-pay'
});
})();
</script>
</body>
</html>
Replace <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. |
|
buttonText | Alphanumeric | Used to change the text that appears on the Apple Pay button. Click here for further information. |
|
placement | Alphanumeric | This must be the name of the Apple Pay button div id. It is used to render the payment button on the checkout. |
You can change the colour of the button and the text displayed to better suit the needs of your checkout.
Apple has published guidelines on how to best position the Apple Pay button on your checkout.
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'pay',
placement: '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:
For a full specification, please refer to Apple’s own documentation. |
|
|
supportedNetworks | List | The payment networks supported by the merchant. The value must be one or more of the following: “amex“, “masterCard” or “visa“. | |
st.ApplePay({
merchantId: 'your.merchant.id',
paymentRequest: {
countryCode: 'US',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard"],
},
});
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:
|
||
|
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:
|
||
|
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
More info >>> |
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
The customer will be able to select from the cards saved in their Apple Wallet.
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”.
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.
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/
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.
How do I customise the Apple Pay button?Establish a connection with Apple Pay