Contents

Processing using your own 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 submit an AJAX request to a URL hosted on your server. This contains a JSON object.
  3. Use the information received in the object to construct an AUTH request and submit this to Secure Trading.
  4. Secure Trading contacts the acquiring bank to request authorisation for the transaction. Your system will be returned an AUTH response. You will need to parse this response.
  5. Respond to the AJAX request from earlier with a JSON object, containing the outcome of the authorisation request. The customer will be redirected to an appropriate results page hosted on your server.

 

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.

 


 

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",
        "merchantUrl":"https://example.com/listener.cgi",
      });

 

 

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",
        "merchantUrl":"https://example.com/listener.cgi",
      });
    </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",
        "merchantUrl":"https://example.com/listener.cgi",
      });
    </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”.
merchantUrl URL Not defined The URL of a page hosted on your system that will receive the initial response from Apple (prior to your system submitting the AUTH).
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.

 

Optional fields

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

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”

 

SQUARE Phone
The customer taps the Apple Pay button on your checkout page.

Our JavaScript submits a request to check the customer’s wallet is verified with Apple, and if successful, the customer’s device displays the Apple Pay payment sheet.

 

 


 

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.

 


 

Receiving AJAX request from st.js

SQUARE Apple
The customer reviews their order and confirms payment using the Touch ID sensor.

The st.js submits a request to Apple to obtain a payment request wallettoken.

Apple returns the token to st.js.

SQUARE Response
st.js submits an AJAX request (containing a JSON object) to the merchantUrl page specified in your server-side payment form. Your page will need to deserialize this object in order to extract the relevant fields when sending the AUTH to Secure Trading. When constructing your AUTH, you must ensure that you use the values present in your own server session and not the posted values.

 

Request example

The following is an example of a typical Apple Pay request submitted to your server by st.js:


{
u'version': u'1.00', 
u'request':[{
	u'walletsource': u'APPLEPAY',
	u'currencyiso3a': u'GBP',
	u'wallettoken':u'{
		"billingContact":{
			"addressLines":["Flat 7","123 Test Street"],
			"administrativeArea":"Gwynedd",
			"country":"United Kingdom",
			"countryCode":"GB",
			"familyName":"Bloggs",
			"givenName":"Fred",
			"locality":"Bangor",
			"postalCode":"TE45 6ST"
		},
		"shippingContact":{
			"addressLines":["Flat 7","123 Test Street"],
			"administrativeArea":"Gwynedd",
			"country":"United Kingdom",
			"countryCode":"GB",
			"emailAddress":"[email protected]",
			"familyName":"Bloggs",
			"givenName":"Fred",
			"locality":"Bangor",
			"phoneNumber":"01234 567890",
			"postalCode":"TE45 6ST"
		},
		"token":{
			"paymentData":{
				"version":"EC_v1",
				"data":"a39nc5624",
				"header":{
					"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEq87ANu1P5Nfptej90Yx4JrojfrTbX7Usu0c0/f/nnW8jLgeqzZsyqOhq4HDKTqZpqEBhnrYMHu3JiinVRo4uLw==",
					"publicKeyHash":"3WtGAmg27eT85au37/gsX5P1ykLwdVabcpMpXHaRAc0=",
					"transactionId":"7d362191c39f5899a4a1b80d53270f288a4d460cc3cb74832c2c14065f6a9dfa"
				}
			},
			"paymentMethod":{
				"displayName":"Visa 0465",
				"network":"Visa",
				"type":"credit"
			},
			"transactionIdentifier":"7D362191C39F5899A4A1B80D53270F288A4D460CC3CB74832C2C14065F6A9DFA"
		}	
	}',
	u'sitereference': u'test_site12345',
	u'mainamount': u'2.00',
	u'requestid': u'J-n8op990r'
	}],
	u'versioninfo': u'STJS::N/A::1.0.6::N/A'
}

 

Field specification

The response will contain the fields listed below:

Field name Type Length Description
currencyiso3a Alpha 3 The currency that the transaction will be processed in.Click here for a full list of available currencies.
errorcode Numeric 1-5 The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

errormessage Alphanumeric 255 This is the corresponding message to the above code.

Click here for a full list of errorcode and message values.

mainamount Numeric including
decimal point
14 The amount of the transaction in main units, using 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.

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.
transactionstartedtimestamp Date time YYYY-MM-DD hh:mm:ss 19 The time the transaction was processed.
walletsession Alphanumeric including
symbols
Not defined Session object returned from Apple.
walletsource Alpha Not defined Must be “APPLEPAY”.

 


 

Submit AUTH request

SQUARE ST
Submit an AUTH request to us by following the specification below.

Your merchantUrl page will receive an AUTH response.

Info
If you are submitting multiple values in the requesttypedescriptions field. the response will be divided into multiple parts, each corresponding with every request type processed. You will need to decide which of the requests should be used to decide whether or not the transaction was successful before printing this to the page.

 

AUTH request


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "mainamount": "2.00",
  "orderreference": "My_Order_123",
  "billingcontactdetailsoverride": "1",
  "customercontactdetailsoverride": "1",
  "walletsource": "APPLEPAY",
  "wallettoken": "token_from_apple"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => '[email protected]',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'mainamount' => '2.00',
  'orderreference' => 'My_Order_123',
  'billingcontactdetailsoverride' => '0',
  'customercontactdetailsoverride' => '0',
  'walletsource' => 'APPLEPAY',
  'wallettoken' => 'token_from_apple'
);

$api = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "sitereference": "test_site12345",
  "mainamount": "2.00",
  "orderreference": "My_Order_123",
  "billingcontactdetailsoverride": "0",
  "customercontactdetailsoverride": "0",
  "walletsource": "APPLEPAY",
  "wallettoken": "token_from_apple"
}]}'

 

AUTH response


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'responses': [{
        u 'walletsource': u 'APPLEPAY',
        u 'transactionstartedtimestamp': u '2017-11-02 14:24:32',
        u 'livestatus': u '0',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2017-11-02',
        u 'errorcode': u '0',
        u 'baseamount': u '200',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '23-9-141',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'eci': u '07',
        u 'accounttypedescription': u 'ECOM',
        u 'cavv': u 'AqjLSnAAzVXOwsfABfO0MAACAAA=',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '0',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST83',
        u 'errormessage': u 'Ok',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '481852######5473',
        u 'securityresponseaddress': u '0',
        u 'operatorname': u '[email protected]',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(29) {
      ["walletsource"] => string(8) "APPLEPAY"
      ["transactionstartedtimestamp"] => string(19) "2017-11-02 14:24:32"
      ["livestatus"] => string(1) "0"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2017-11-02"
      ["errorcode"] => string(1) "0"
      ["baseamount"] => string(3) "200"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["transactionreference"] => string(8) "23-9-141"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["orderreference"] => string(12) "My_Order_123"
      ["eci"] => string(2) "07"
      ["accounttypedescription"] => string(4) "ECOM"
      ["cavv"] => string(8) "AqjLSnAAzVXOwsfABfO0MAACAAA="
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "0"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST83"
      ["errormessage"] => string(2) "Ok"
      ["securityresponsepostcode"] => string(1) "0'"
      ["maskedpan"] => string(16) "481852######5473"
      ["securityresponseaddress"] => string(1) "0"
      ["operatorname"] => string(23) "[email protected]"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{
  "requestreference": "W23-tw29qere",
  "version": "1.00",
  "response": [{
    "walletsource": "APPLEPAY",
    "transactionstartedtimestamp": "2017-11-02 14:24:32",
    "livestatus": "0",
    "splitfinalnumber": "1",
    "dccenabled": "0",
    "settleduedate": "2017-11-02",
    "errorcode": "0",
    "baseamount": "200",
    "tid": "27882788",
    "merchantnumber": "00000000",
    "merchantcountryiso2a": "GB",
    "transactionreference": "23-9-141",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "VISA",
    "orderreference": "My_Order_123",
    "eci": "07",
    "accounttypedescription": "ECOM",
    "cavv": "AqjLSnAAzVXOwsfABfO0MAACAAA=",
    "acquirerresponsecode": "00",
    "requesttypedescription": "AUTH",
    "securityresponsesecuritycode": "0",
    "currencyiso3a": "GBP",
    "authcode": "TEST83",
    "errormessage": "Ok",
    "securityresponsepostcode": "0",
    "maskedpan": "481852######5473",
    "securityresponseaddress": "0",
    "operatorname": "[email protected]",
    "settlestatus": "0"
  }],
  "secrand": "T"
}

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 Must be “ECOM”, to indicate transaction is processed using an e-commerce account.
authmethod Alpha 5    Either “PRE” or “FINAL”.
Click here for further information.
baseamount Numeric 13 The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000.

Take care not to confuse this field with mainamount, which is described above, which is formatted in main units instead, including a decimal point.

billingcontactdetailsoverride Numeric 1 0 = Uses billing address submitted in the AUTH request.
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).
cavv Alphanumeric 32 The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer.
currencyiso3a Alpha 3 The currency that the transaction will be processed in. Supported currencies are dependent on your acquiring bank.

Click here for a full list of available currencies.

customercontactdetailsoverride Numeric 1   0 = Uses customer address submitted in the AUTH request.
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).
eci Alphanumeric 2 The ECI (E-Commerce Indicator) security level associated with the transaction.
maskedpan Alphanumeric including “#” 16 This is a unique token returned by Apple, used to reference the customer’s device.

Note: Unlike in standard AUTH responses, this is NOT the customer’s card number.

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.
requesttypedescriptions Alpha 20 * You must submit “AUTH”, as shown in the request example.

*In the response, the field ‘requesttypedescription’ is returned instead e.g. “requesttypedescription”:”AUTH”

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.

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.
walletsource Alpha Not defined Must be “APPLEPAY”.
wallettoken Alphanumeric including
symbols
Not defined Unique token provided by Apple to represent the customer’s card details.

 


 

Payment completion

After receiving the AUTH response, your system will need to parse this and respond with a JSON formatted HTTP response to the “st.js”. When returning the response, ensure the header is correctly specified as Content-type: application/json

We recommend following our best practice guidelines, but the following checks are the most important:


{"response":[{"errorcode": "0", "errormessage": "Ok"}]}


{"response":[{"errorcode": "30000", "errormessage": "Invalid field"}]}

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.

 

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.