Process Apple Pay transaction using Webservices API

The following documentation explains how to submit an AUTH request using our Webservices API, in order to process an Apple Pay transaction.

Who is this document for?

This document assumes you are not looking to develop a native iOS app that supports Apple Pay (which can be implemented using our iOS SDK), or a web-based solution (using our JavaScript Library).
If you have / plan on having a direct integration with Apple to process Apple Pay on the web and simply need a method of submitting the payment card wallettoken for authorisation to the Trust Payments.

Requirements

Before processing the request outlined below, you will need to develop a solution that retrieves an Apple Pay wallettoken. To learn more, please read Apple’s own documentation (link to external site).

Integration steps

Create a Merchant ID

Follow the steps provided by Apple in this document under the section “Create a merchant identifier“.
Click here to open this page in a new tab (link to external site).

Create a Payment Processing Certificate

This is a certificate associated with your merchant ID, which is used to secure the transaction data. Apple Pay servers use the certificate’s public key to encrypt payment data. Trust Payments use the private key to decrypt payment data in order to process payments.

You will need to contact our Support Team to enable Apple Pay on your Trust Payments site reference(s). Please advise the Support Team that you require a Payment Processing CSR as part of your Apple Pay integration. You will be asked to provide the following information as part of this process:

Your site reference(s).
The domain of your payment page.
Your Apple Pay Merchant ID(s).
Your Webservices Username.

The Support team will return a certificate signing request (PEM file) for each Merchant ID, and you will need to follow the steps below for each Merchant ID to enable Apple Pay on your account.

This process will need to be performed for both your test site reference and also your live site reference when you are ready to start processing payments in our production environment.

(The following steps assume you have already created a merchant ID using your Apple Developer account.)

Sign into the Apple Developer Center:
https://developer.apple.com/account/ (link to external site)
In the Member Center, select “Certificates, Identifiers & Profiles“.
Under Identifiers, select “Merchant IDs“.
Select the merchant ID from the list, and click “Edit“.
In the Payment Processing Certificates section, click “Create Certificate“.
Click “Choose File“, select the Payment Processing CSR file emailed to you by the Support Team earlier, and click “Generate“.
Download the certificate by clicking “Download“, and click “Done“.

You will now need to contact the Support Team with the certificate you have downloaded:

Having followed the steps above, you should be in possession of an Apple Pay certificate (CER file).
Compress this file into a .zip file, attach to an email and send it to support@trustpayments.com.
Once Support have received the certificate and confirmed by email, you can proceed.

You must ensure you send the certificate in a .zip file when emailing Support.

Create a Merchant Identity Certificate

Follow the steps provided by Apple in this document under the section “Create a merchant identity certificate“.
Click here to open this page in a new tab (link to external site).

Register and verify your merchant domain

Follow the steps provided by Apple in this document under the section “Register a merchant domain“.
Click here to open this page in a new tab (link to external site).

Having problems verifying your domain?

If you receive the following error message when validating the domain while on Apple’s Developer Portal:

Verification failed for domain
Unable to establish a secure connection to ‘https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association.txt’
Domain certificate is untrusted.

Solution
Apple requires that the server receives a high security rating in order to successfully validate a domain.
(For example, if using SSL Labs to check your certificate, an A grade would be required as a minimum: https://www.ssllabs.com/ssltest/index.html (link to external site)

AUTH request

After you have completed the integration as explained above, you can now update your checkout to process Apple Pay transactions, by submitting an AUTH request to the Trust Payments gateway that meets the specifications outlined below:

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "billingcontactdetailsoverride": "1",
  "customercontactdetailsoverride": "1",
  "wallettoken": "{\"token\":{\"paymentData\":{\"version\":\"EC_v1\",\"signature\":\"SIGNATURE HERE",\"data\":\"DATA HERE",\"header\":{\"publicKeyHash\":\"PUBLIC KEY HASH HERE",\"ephemeralPublicKey\":\"PUBLIC KEY",\"transactionId\":\"TXN ID"}},\"paymentMethod\":{\"displayName\":\"CARD TYPE AND LAST 4",\"network\":\"SCHEME\",\"type\":\"CREDIT / DEBIT\"},\"transactionIdentifier\":\"TXN IDENTIFIER\"}}",
  "walletsource": "APPLEPAY"
}

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' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'billingcontactdetailsoverride' => '1',
  'customercontactdetailsoverride' => '1',
  'wallettoken' => '{\"token\":{\"paymentData\":{\"version\":\"EC_v1\",\"signature\":\"SIGNATURE HERE",\"data\":\"DATA HERE",\"header\":{\"publicKeyHash\":\"PUBLIC KEY HASH HERE",\"ephemeralPublicKey\":\"PUBLIC KEY",\"transactionId\":\"TXN ID"}},\"paymentMethod\":{\"displayName\":\"CARD TYPE AND LAST 4",\"network\":\"SCHEME\",\"type\":\"CREDIT / DEBIT\"},\"transactionIdentifier\":\"TXN IDENTIFIER\"}}',
  'walletsource' => 'APPLEPAY'
);

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

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias":"webservices@example.com",
  "version": "1.00",
  "request": [{
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "orderreference": "My_Order_123",
    "billingcontactdetailsoverride": "1",
    "customercontactdetailsoverride": "1",
    "wallettoken": "{\"token\":{\"paymentData\":{\"version\":\"EC_v1\",\"signature\":\"SIGNATURE HERE",\"data\":\"DATA HERE",\"header\":{\"publicKeyHash\":\"PUBLIC KEY HASH HERE",\"ephemeralPublicKey\":\"PUBLIC KEY",\"transactionId\":\"TXN ID"}},\"paymentMethod\":{\"displayName\":\"CARD TYPE AND LAST 4",\"network\":\"SCHEME\",\"type\":\"CREDIT / DEBIT\"},\"transactionIdentifier\":\"TXN IDENTIFIER\"}}",
    "walletsource": "APPLEPAY"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "baseamount":"1050",
    "orderreference":"My_Order_123",
    "accounttypedescription":"ECOM",
    "billingcontactdetailsoverride": "1",
    "customercontactdetailsoverride": "1",
    "wallettoken": "{\"token\":{\"paymentData\":{\"version\":\"EC_v1\",\"signature\":\"SIGNATURE HERE",\"data\":\"DATA HERE",\"header\":{\"publicKeyHash\":\"PUBLIC KEY HASH HERE",\"ephemeralPublicKey\":\"PUBLIC KEY",\"transactionId\":\"TXN ID"}},\"paymentMethod\":{\"displayName\":\"CARD TYPE AND LAST 4",\"network\":\"SCHEME\",\"type\":\"CREDIT / DEBIT\"},\"transactionIdentifier\":\"TXN IDENTIFIER\"}}",
    "walletsource": "APPLEPAY"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <payment>
        <wallet>
          <token>{\"token\":{\"paymentData\":{\"version\":\"EC_v1\",\"signature\":\"SIGNATURE HERE",\"data\":\"DATA HERE",\"header\":{\"publicKeyHash\":\"PUBLIC KEY HASH HERE",\"ephemeralPublicKey\":\"PUBLIC KEY",\"transactionId\":\"TXN ID"}},\"paymentMethod\":{\"displayName\":\"CARD TYPE AND LAST 4",\"network\":\"SCHEME\",\"type\":\"CREDIT / DEBIT\"},\"transactionIdentifier\":\"TXN IDENTIFIER\"}}</token>
          <source>APPLEPAY</source>
        </wallet>
      </payment>
      <contactdetailsoverride>1</contactdetailsoverride>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <customer>
      <contactdetailsoverride>1</contactdetailsoverride>
    </customer>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

The example request described here is to process a standalone Apple Pay e-commerce transaction via the Webservices API. Once this has been processed and settled, and providing you have a Merchant Id (MID) that supports this, we also support the processing of subsequent recurring transactions - these are used to facilitate repeat payments with the customer not present. Click here to learn more.

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	Submit “ECOM” to represent an e-commerce transaction.
baseamount XPath: /billing/amount	Numeric (13)	The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
billingcontactdetailsoverride XPath: /billing/contactdetailsoverride	Numeric (1)	Submit with value “1”. This allows customers to use the billing details stored in their Apple Pay wallet.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency of the transaction. Click here for a full list of available currencies.
customercontactdetailsoverride XPath: /customer/contactdetailsoverride	Numeric (1)	Submit with value “1”. This allows customers to use the delivery details stored in their Apple Pay wallet.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25) See description on right for further details.	Your unique order reference that can be stored on the Trust Payments system. Note: This can be updated at a later time (only if transaction is pending settlement). Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.
requesttypedescriptions XPath: /@type	Alpha (20)	Supported request type combinations: [“AUTH”] [“AUTH”, “RISKDEC”] [“AUTH”, “SUBSCRIPTION”] [“ACCOUNTCHECK”, “AUTH”] [“ACCOUNTCHECK”, “SUBSCRIPTION”] [“RISKDEC”, “AUTH”] [“RISKDEC”, “AUTH”, “SUBSCRIPTION”] [“RISKDEC”, “ACCOUNTCHECK”, “AUTH”] [“RISKDEC”, “ACCOUNTCHECK”, “AUTH”, “SUBSCRIPTION”] Click here to learn more about request types.
sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	Identifies your site on the Trust Payments system.
walletsource XPath: /billing/payment/wallet/source	Alpha (8)	Must be submitted with value “APPLEPAY”.
wallettoken XPath: /billing/payment/wallet/token	JSON-encoded string	Unique token provided by Apple to represent the customer’s card details. This should not be modified.

AUTH response

After submitting the AUTH request, you will be returned an AUTH response.

This response follows a similar structure to a standard AUTH response for a card payment, as documented on this page, but pay specific attention to these additional fields / differences in specification:

Field	Format	Description
maskedpan XPath: /billing/payment/pan	Alphanumeric including “#” (12-19)	The customer’s Apple Pay token number (NOT the card number). This is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
tokenisedpayment XPath: /billing/payment/pan/@tokenised	Numeric (1)	This is returned with value 1 to indicate the transaction was processed using a token.
tokentype XPath: /billing/payment/pan/@tokentype	Alphanumeric (50)	Used to identify the type of token used for this payment (in this case “APPLEPAY”).
walletdisplayname XPath: /billing/payment/wallet/displayname	Alphanumeric (255)	The card type used by the customer and the last four digits of their card number (e.g. “Visa 1111”).
walletsource XPath: /billing/payment/wallet/source	Alphanumeric (20)	Used to identify the type of wallet used for this payment (in this case “APPLEPAY”).

Further reading on this topic