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?
- 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.
Integration steps
Create a Merchant ID
Follow the steps provided by Apple in this document under the section “Create a merchant identifier“.
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 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.)
- Sign into the Apple Developer Center: https://developer.apple.com/account/
-
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 [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
Follow the steps provided by Apple in this document under the section “Create a merchant identity certificate“.
Register and verify your merchant domain
Follow the steps provided by Apple in this document under the section “Register a merchant domain“.
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:
|
|
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”). |