Contents

Apple Pay

 

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?

 


 

Requirements

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

 


 

Integration steps

 

Create a Merchant ID

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

 


 

Create a Payment Processing Certificate

Info
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.
Envelope
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 CSR 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.

 

Note: 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.)

 

  1. Sign into the Apple Developer Center: https://developer.apple.com/account/
  2. In the Member Center, select “Certificates, Identifiers & Profiles“.

  3. Under Identifiers, select “Merchant IDs“.

  4. Select the merchant ID from the list, and click “Edit“.

  5. In the Payment Processing Certificates section, click “Create Certificate“.

  6. Click “Choose File“, select the Payment Processing CSR file emailed to you by the Support Team earlier, and click “Generate“.

  7. Download the certificate by clicking “Download“, and click “Done“.

Envelope
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 [email protected].
  • Once Support have received the certificate and confirmed by email, you can proceed.

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

 


 

Create a Merchant Identity Certificate

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

 


 

Register and verify your merchant domain

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

Having problems validating 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)

 


 

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 = "[email protected]"
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' => '[email protected]',
  '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 [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"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":"[email protected]","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>[email protected]</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>

 

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 (255)
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).

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