JavaScript Library: Configure your solution

  Ensure you have met all requirements before proceeding.
Click here for further information.

Default Process Flow

  1. When the customer presses the Apple Pay button, the customer will be presented with the Apple Pay payment sheet.
  2. When the customer agrees to the payment, an AUTH request is submitted to Trust Payments.
  3. 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.

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: 'pay',
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'
}
},
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","amex"],
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
table-required.png buttonStyle Alphanumeric Used to change the appearance of the Apple Pay button. Click here for further information.
table-required.png buttonText Alphanumeric Used to change the text that appears on the Apple Pay button. Click here for further information.
table-required.png placement Alphanumeric This must be the name of the Apple Pay button div id (always "st-apple-pay").
It is used to render the payment button on the checkout.

  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.

Apple has published guidelines on how to best position the Apple Pay button on your checkout.
Click here to learn more.

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

 

Merchant fields

  Field Format Description
table-required.png merchantId Alphanumeric including symbols (26) You will need to specify your Apple Pay Merchant ID.
table-required.png paymentRequest Object This object contains information about the payment, which will be sent off to Apple in the initial request (our Javascript sends this).
table-required.png   countryCode Alpha (2) The merchant’s country code in ISO2a format.
table-required.png   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.
table-required.png   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","amex"],
},
});

 

Transaction fields

  Field Format Description
table-required.png paymentRequest Object This object contains information about the payment, which will be sent off to Apple in the initial request (our Javascript sends this).
table-conditional.png   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.

table-conditional.png   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.

table-required.png   currencyCode Alpha (3) The transaction currency code in ISO3a format.
table-required.png   total N/A A line item representing the total for the payment.
table-required.png     amount Numeric including decimal place (14) The amount of the transaction in main unitsusing 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.
table-required.png     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.
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”.

jsl-appleconfig-01.png

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”.

jsl-appleconfig-02.jpg

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.

 

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.

jsl-appleconfig-03.jpeg

 

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.

jsl-appleconfig-04.png

 

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/

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.

  1. When the customer presses the Apple Pay button, the customer will be presented with the Apple Pay payment sheet.
  2. The customer approves the payment using Touch ID, Face ID or their passcode.
  3. merchantUrl is sent a request from the JavaScript containing the wallet details.
  4. An AUTH request is sent by the merchantUrl to Trust Payments using our Webservices API.
  5. 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: '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'
  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'
}​​​​​​​​​​​​​​]
}​​​​​​​​​​​​​​
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request