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.

 

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.

 

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:

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.

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

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.

 

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.

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)

 

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:

Python PHP cURL Raw JSON Raw XML
#!/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

 

Field specification

  Field Format Description
table-required.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Submit “ECOM” to represent an e-commerce transaction.
table-required.png 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)
table-required.png billingcontactdetailsoverride
XPath: /billing/contactdetailsoverride
Numeric (1) Submit with value “1”. This allows customers to use the billing details stored in their Apple Pay wallet.
table-required.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The currency of the transaction. Click here for a full list of available currencies.
table-required.png customercontactdetailsoverride
XPath: /customer/contactdetailsoverride
Numeric (1) Submit with value “1”. This allows customers to use the delivery details stored in their Apple Pay wallet.
table-optional.png 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.

table-required.png 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.

table-required.png sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.
table-required.png walletsource
XPath: /billing/payment/wallet/source
Alpha (8) Must be submitted with value “APPLEPAY”.
table-required.png 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
table-returned.png 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.
table-returned.png tokenisedpayment
XPath: /billing/payment/pan/@tokenised
Numeric (1) This is returned with value 1 to indicate the transaction was processed using a token.
table-returned.png tokentype
XPath: /billing/payment/pan/@tokentype
Alphanumeric (50) Used to identify the type of token used for this payment (in this case “APPLEPAY”).
table-returned.png 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”).
table-returned.png walletsource
XPath: /billing/payment/wallet/source
Alphanumeric (20) Used to identify the type of wallet used for this payment (in this case “APPLEPAY”).
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request