Contents

Processing using our listener

 

Process overview

Info
You will need to update your server-side payment form to include our “st.js” JavaScript, so the Apple Pay button will be displayed to the customer.
  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, the “st.js” JavaScript will automatically submit an AUTH request to Secure Trading.
  3. Secure Trading contacts the acquiring bank to request authorisation for the transaction.

 

Requirements

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

 


 

Secure your data

When processing Apple Pay transactions, you are required to calculate a site security hash, which must be included in a field called sitesecurity on your server-side payment form. The hash is generated from a selection of designated fields, including a password that will be agreed upon with our Support team. When constructing the hash, you must ensure that you use the values present in your own server session and not the POSTed values.

 

Here’s how it works

 


 

We will read the fields in your request prior to processing an authorisation and re-generate the hash on our servers. For valid requests, the site security hash that we generate must match the value submitted in your request. This indicates the request has not been modified by the customer or third party.

 

 

 

 

 

If someone tries to modify the value of one of your designated fields, the hash we calculate on our servers will not match the hash submitted in the request. In this case, the payment will not be completed and an error message is shown in the Apple Pay payment sheet (“Payment not completed”) and also on your checkout.

 

 

 

 

 

 

Before proceeding, please contact our Support team

 


 

  • Our Support team will enable site security on your site reference and will advise you on how to best configure your account.
  • As part of this process, you will need to agree on the designated fields to be included in the hash generated.
  • We recommend including as many unique fields in your site security hash as possible.
  • All fields that need to be protected against unauthorised modification must be included in your site security hash.
  • We support the inclusion of custom fields in your list of designated fields.
  • You will also need to agree on a password with our Support team, to also be included when generating the hash.

 

The following are the default designated site security fields, in the order required for generating the hash (we provide a walkthrough example below this table). When enabling site security with our Support team, it is possible to specify additional fields to this list:

 Order Field name Type Length Description
1 currencyiso3a Alpha 3 The currency that the transaction will be processed in.
Click here for a full list of available currencies.
2 mainamount Numeric 14 The amount of the transaction in main unitsusing a decimal point to denote decimal values, so £10 is returned as 10.00.

Take care not to confuse this field with baseamount, which we use extensively in our documentation, which is formatted in base units instead, forgoing the decimal point.

3 sitereference Alphanumeric including
underscore
50 The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.
4 settlestatus Numeric 3 A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.

Click here for a full list of settlestatus values.

5 settleduedate Date YYYY-MM-DD 10 You can submit this field in the request to specify the date you would like your transaction to settle. This must be within 7 days of the authorisation date. This date is returned in the response.
6 authmethod Alpha 5 Either “PRE” or “FINAL”.
Click here for further information.
7 strequiredfields Alphanumeric Not defined Specify fields required to be entered by the customer. Multiple fields supported.

If the customer fails to provide information in all the required fields or enters invalid information, the payment will not be completed.

8 ruleidentifier Alphanumeric including hyphens Not defined You can submit unique identifiers for rules to be applied to this request (e.g. STR-1).
Click here for further information.
9 successfulurlnotification URL Not defined This is the URL the notification is sent to following a successful transaction, when STR-8 is enabled.
10 declinedurlnotification URL Not defined This is the URL the notification is sent to following a declined transaction, when STR-9 is enabled.
11 merchantemail Email address 255 This is the email address to which any merchant email notifications are sent to, when STR-4 and/or STR-5 are enabled.

Maximum length of 255 (maximum of 64 characters before the ”@” symbol).

12 allurlnotification URL Not defined This is the URL the notification is sent to following any request, when STR-10 is enabled.
13 stextraurlnotifyfields Alphanumeric Not defined This is used to include additional fields in URL notifications.
14 password Alphanumeric including symbols 255 This is the site security password, as agreed with our Support team.

Valid characters:

  • Uppercase and lowercase letters
  • Numbers 0-9
  • Spaces
  • ~ ! # $ % ^ & * ( _ { [ } ] < , > ?

 

 

Example

The following is a walkthrough with an example sitereference and example site security preferences.

Suppose you have the following site security fields configured on your site reference, as agreed beforehand with our Support team:

Warning
In your own solution, we recommend including as many unique fields in your site security hash as possible. Fields included in your hash cannot be modified by the customer or an unauthorised third party. We support the inclusion of custom fields in your list of designated fields.

 


 

Step 1

You will need to retrieve and concatenate the values of your previously-agreed site security fields from your session, into a single string:


GBP2.00test_site12345PASSWORD

Warning
When generating the hash, the fields must be in the same order agreed with the Support team

If the fields are not in the correct order, the request will fail. The order in which fields are hashed can be changed if required. Please contact the Support team for assistance.

 


 

Step 2

You will need to set up your system to generate the hash from your concatenated field values, using the SHA-256 algorithm. The following is an example of the above string hashed using the SHA-256 algorithm:


12FAE567783CA81D2CB222CBA02D188E24C101470A5191056C22D349CC1D1FC7

 

You can use the following code examples as a reference when generating your hash:


#!/usr/bin/python

import hashlib
stringToHash= "USD100.00test_site123452defaultPASSWORD"
print hashlib.sha256(stringToHash).hexdigest()
<?php
echo hash("sha256", "USD100.00test_site123452defaultPASSWORD");
?>

 

 

Step 3

Now you’ve generated your hash, you will need to precede the hash with a “g”. This will be the final value that would need to be submitted in the sitesecurity field for this example transaction:


g12FAE567783CA81D2CB222CBA02D188E24C101470A5191056C22D349CC1D1FC7

 

Warning
It is important that the generated hash is prefixed with the letter “g”. This is to ensure the latest version of the site security feature is used. Failure to do so could invalidate the hash and stop legitimate transactions.
Padlock
You must ensure that you never POST the raw site security password (not hashed), as this is a shared secret between you and Secure Trading.

 


 

Update your server-side payment form

You will need to update your server-side payment form as follows:

 

st.js

You will need to update your server-side payment form to include our “st.js” JavaScript. This works in conjunction with our Apple Pay library in order to process requests and handle responses returned.


<script src="https://webservices.securetrading.net/js/st.js"></script>

 

 

Payment form

You must ensure that your payment form has been assigned the id “st-payment”.

A “div” element with attribute id=”st-message” is also required, in order for invalid field and connection errors to be displayed to the customer.

You will need to ensure the Apple Pay button is displayed on your page by supported Apple devices. This is achieved by adding the following markup to your existing payment form:


<div id="st-message"></div>
<form id="st-payment" action="https://www.example.com">
    <div class="st-applepay-button" id="testing"></div>
</form>

 

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 the following markup on your payment form:


new SecureTrading.ApplePay({
        sitereference: "test_site12345",
        paymentRequest:{
          "total":{
            "label":"Pay now",
            "amount":"2.00"
          },
          "countryCode":"GB",
          "currencyCode":"GBP",
          "merchantCapabilities":["supports3DS", "supportsCredit", "supportsDebit"],
          requiredBillingContactFields: ["postalAddress"],
          requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],
          supportedNetworks:["visa", "masterCard"]
        },
      "merchantId":"merchant.net.securetrading",
      "sitesecurity":"g12FAE567783CA81D2CB222CBA02D188E24C101470A5191056C22D349CC1D1FC7"
      });

 

 

Your finished markup will look something like this:

Info
If you need to change the names of the identifiers “st-message” and “st-payment”, because your application doesn’t support the naming convention used (e.g. no hyphen support), you can use the markup found in the second tab to override them.

<html>
<head>
</head>
<body>
    <div id="st-message"></div>
    <form id="st-payment" action="https://www.example.com">
        <div class="st-applepay-button" id="testing"></div>
    </form>
    <script src="https://webservices.securetrading.net/js/st.js"></script>
    <script>
        new SecureTrading.ApplePay({
        sitereference: "test_site12345",
        paymentRequest:{
          "total":{
            "label":"Pay now",
            "amount":"2.00"
          },
          "countryCode":"GB",
          "currencyCode":"GBP",
          "merchantCapabilities":["supports3DS", "supportsCredit", "supportsDebit"],
          requiredBillingContactFields: ["postalAddress"],
          requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],
          supportedNetworks:["visa", "masterCard"]
        },
        "merchantId":"merchant.net.securetrading",
        "sitesecurity":"g12FAE567783CA81D2CB222CBA02D188E24C101470A5191056C22D349CC1D1FC7"
      });
    </script>
</body>
</html>
<html>
<head>
</head>
<body>
    <div id="stmessage"></div>
    <form id="stpayment" action="https://www.example.com">
        <div class="st-applepay-button" id="testing"></div>
    </form>
    <script src="https://webservices.securetrading.net/js/st.js"></script>
    <script>
        new SecureTrading.ApplePay({
        sitereference: "test_site12345",
        messageId: "stmessage",
        formId: "stpayment",
        paymentRequest:{
          "total":{
            "label":"Pay now",
            "amount":"2.00"
          },
          "countryCode":"GB",
          "currencyCode":"GBP",
          "merchantCapabilities":["supports3DS", "supportsCredit", "supportsDebit"],
          requiredBillingContactFields: ["postalAddress"],
          requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],
          supportedNetworks:["visa", "masterCard"]
        },
        "merchantId":"merchant.net.securetrading",
        "sitesecurity":"g12FAE567783CA81D2CB222CBA02D188E24C101470A5191056C22D349CC1D1FC7"
      });
    </script>
</body>
</html>

 

Required fields

The following fields are all required when calling the Apple Pay library:

Field name Type Length Description
merchantId Alphanumeric including symbols 26 You will need to specify Secure Trading’s unique identifier for Apple Pay: “merchant.net.securetrading”.
paymentRequest N/A 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.
currencyCode Alpha 3 The transaction currency code in ISO3a format.
merchantCapabilities Alphanumeric N/A 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.

supportedNetworks Alphanumeric N/A The payment networks supported by the merchant. The value must be one or more of “amex“, “masterCard” or “visa“.
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.

Take care not to confuse this field with billingamount, which we use extensively in our documentation, which is formatted in base units instead, forgoing the decimal point.

label Alphanumeric including symbols (do not include white space or symbols at the end of the string) Not defined 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.
sitereference Alphanumeric including underscore 50 The site reference relates to your individual account which you received on setup.
sitesecurity Alphanumeric 65 The hash value calculated by following the instructions above.

 

Optional fields

ST optional fields

You can optionally submit the following additional fields in your POST:

Field name Type Length Description
authmethod Alpha 5 Either “PRE” or “FINAL”.
Click here for further information.
billingcontactdetailsoverride Numeric 1 0 = Uses billing address submitted in the POST.
1 = Uses billing address specified by customer from their Apple wallet.
When not submitted, this field defaults to “0”.
billingpremise Alphanumeric including
symbols
25 The house number or first line of the customer’s billing address.
billingstreet 127 The street entered for the customer’s billing address.
billingtown 127 The town entered for the customer’s billing address.
billingcounty Alphanumeric including
symbols
127 The county entered for the customer’s billing address. For US addresses, the state would be entered in this field. Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
billingcountryiso2a Alpha 2 The country for the customer’s billing address. This will need to be in ISO2A format. Click here for a full list of country codes.
billingpostcode Alphanumeric 25 The postcode entered for the customer’s billing address.If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.
billingemail Email 255 The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingtelephonetype Char 1 The type of telephone number. The options available are:

  • H = Home
  • M = Mobile
  • W = Work
billingtelephone Alphanumeric including
symbols
20 The customer’s telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
billingprefixname Alphanumeric including
symbols
25 The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname 127 The customer’s billing first name.
billingmiddlename 127 The customer’s billing middle name(s).
billinglastname 127 The customer’s billing last name.
billingsuffixname 25 The suffix of the customer’s billing name (e.g. Bsc).
customercontactdetailsoverride Numeric 1 0 = Uses customer address submitted in the POST.
1 = Uses shipping address specified by customer from their Apple wallet.
When not submitted, this field defaults to “0”.
customerpremise Alphanumeric including
symbols
25 The customer’s house name or number.
customerstreet 127 The customer’s street name.
customertown 127 The customer’s town.
customercounty Alphanumeric including
symbols
127 The customer’s county. For US addresses, the state would be entered in this field. Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
customercountryiso2a Alpha 2 The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerpostcode Alphanumeric 25 The customer’s postcode or ZIP code.

If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.

customeremail Email 255 The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
customertelephonetype Char 1 The type of telephone number. The options available are:

  • H = Home
  • M = Mobile
  • W = Work
customertelephone Alphanumeric including
symbols
20 The customer’s telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
customerprefixname Alphanumeric including
symbols
25 The customer’s prefix name (e.g. Mr, Miss, Dr).
customerfirstname 127 The customer’s first name.
customermiddlename 127 The customer’s middle name(s).
customerlastname 127 The customer’s last name.
customersuffixname 25 The customer’s suffix name (e.g. Bsc).
merchantemail Email 255 The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
orderreference Alphanumeric including
symbols
255 Your unique order reference that can be stored on Secure Trading’s system.

Note: This can be updated at a later time (only if transaction is pending settlement).

settleduedate Date YYYY-MM-DD 10 You can submit this field in the request to specify the date you would like your transaction to settle. This must be within 7 days of the authorisation date. This date is returned in the response.
settlestatus Numeric 3 A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.

Click here for a full list of settlestatus values.

 

Apple Pay optional fields

URL
For a full specification, please refer to Apple’s own documentation.
Field name Description
failureUrl Customer’s browser is redirected to this URL if an error has occurred.
successUrl Customer’s browser is redirected to this URL after a successful payment.
requiredBillingContactFields (This is required when the customer is to complete the purchase using billing address fields saved on their Apple Pay account)

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 (This is required when the customer is to complete the purchase using delivery address fields saved on their Apple Pay account)

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”

 


 

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

Padlock
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

The Apple Pay payment sheet will update to show either a success or failure message, depending on the outcome of the payment. Following this, the customer’s browser can be optionally redirected to either the successUrl or failureUrl pages specified on your checkout page. If you have not specified these URLs, the page will not redirect and the payment sheet will close.

 

Configuring notifications (optional)

We recommend configuring URL notifications to inform you of Apple Pay transactions that have been processed on your account. You can do this by including the following additional fields on your server-side checkout form:


<input type="hidden" name="ruleidentifier" value="STR-10"/>
<input type="hidden" name="allurlnotification" value="http://example.com/all"/>
<input type="hidden" name="stextraurlnotifyfields" value="walletsource"/>
<input type="hidden" name="ruleidentifier" value="STR-8"/>
<input type="hidden" name="successfulurlnotification" value="http://example.com/successful"/>
<input type="hidden" name="stextraurlnotifyfields" value="walletsource"/>
<input type="hidden" name="ruleidentifier" value="STR-9"/>
<input type="hidden" name="declinedurlnotification" value="http://example.com/declined"/>
<input type="hidden" name="stextraurlnotifyfields" value="walletsource"/>

Field name Type Description
ruleidentifier Alphanumeric including hyphen
  • “STR-8” – URL notification is submitted to the successfulurlnotification, if the AUTH is successful.
  • “STR-9” – URL notification is submitted to the declinedurlnotification, if the AUTH is declined.
  • “STR-10” – URL notification is submitted to the allurlnotification, regardless of the outcome.
successfulurlnotification URL Destination for URL notification, if the AUTH is successful.
declinedurlnotification URL Destination for URL notification, if the AUTH is declined.
allurlnotification URL Destination for URL notification, regardless of the outcome.
stextraurlnotifyfields Alphanumeric Set this to “walletsource” to be returned the walletsource in the notification, in addition to the fields normally returned. When walletsource=”APPLEPAY”, the transaction was processed using Apple Pay.

 

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 the MyST User Guide.

 


 

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.