Contents

API Configuration

 

Process overview

Warning
Ensure you have met all requirements before proceeding.

Click here for further information.

 

  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

External
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 >>>

Warning
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"],
      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/v2/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.

 

External
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
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:

  • “supportsCredit” – To enable credit card payments.
  • “supportsDebit” – To enable debit card payments.

For a full specification, please refer to Apple’s own documentation.

requestTypes List Allows you to specify additional request types.
Click here to learn more
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:

  • “postalAddress”
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”
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 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.

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

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

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.

 


 

 

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 (click here for further info). 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” and “Token source type” fields 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/

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

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.