Apple Pay direct AUTH integration

  Last updated: 

 

  The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
Read this article to learn more.

 

This document assumes you have configured your own integration with Apple Pay and require a gateway to process the payment. Once you have followed   Apple’s guidance on how to verify the token signature and decrypt the token (link to external site), your system will need to parse key values from the paymentData, billingContact and shippingContact objects returned and submit them in an AUTH request to Trust Payments. The full mappings from the fields returned by Apple Pay to fields submitted in the AUTH request can be found below.

 

AUTH request

The following is an example of an AUTH request with the requirements described above:

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 = {
"accounttypedescription":"ECOM",
"baseamount":"2000",
"currencyiso3a":"GBP",
"eci":"2",
"expirydate":"07/2023",
"pan":"5100000000000511",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"tavv":"ALFoEd4DhmGzAIj3dUo4AoABFA==",
"walletdisplayname":"MasterCard 0511",
"walletsource":"APPLEPAY"
}

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

 

Field specification

  Field Mapping to fields from decrypted token Format Description
X1-EN.png accounttypedescription
XPath: /operation/accounttypedescription
N/A Alpha (20) Submit “ECOM” to represent an e-commerce transaction.
X1-EN.png baseamount
XPath: /billing/amount
N/A 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.

X1-EN.png currencyiso3a
XPath: /billing/amount/@currencycode
N/A Alpha (3) The currency of the transaction. Click here for a full list of available currencies.
X1-EN.png eci
XPath: /threedsecure/eci
paymentData ≫ eciIndicator Alphanumeric (2) The ECI (E-Commerce Indicator) security level associated with the transaction. Click here to learn more about possible ECI values.
X1-EN.png expirydate
XPath: /billing/payment/expirydate
paymentData ≫ applicationExpirationDate Date MM/YYYY

The expiry date printed on the card.

The format accepted by Trust Payments differs from the format returned by Apple. While Apple returns this in the format "YYMMDD", you will need to submit this in the format "MM/YYYY" in the AUTH request.

X1-EN.png pan
XPath: /billing/payment/pan
paymentData ≫ applicationPrimaryAccountNumber Numeric (12-19) This is the long number printed on the front of the customer’s card.
X1-EN.png requesttypedescriptions
XPath: /@type
N/A 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.

X1-EN.png sitereference
XPath: /operation/sitereference
N/A Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.
X1-EN.png tavv
XPath: /threedsecure/tavv
paymentData ≫ onlinePaymentCryptogram Alphanumeric & special characters (32) Token Authentication Verification Value
X1-EN.png walletdisplayname
XPath:/billing/payment/wallet/displayname

paymentData ≫ displayName

Numeric (4) This is information provided by the card issuer that can be displayed to the customer in order to identify the payment method. This typically includes the last 4 digits of their card number.
X1-EN.png walletsource
XPath: /billing/payment/wallet/source
N/A Alpha (8) Must be submitted with value “APPLEPAY”.
X2-EN.png billingfirstname
XPath: /billing/name/first
billingContact ≫ givenName Alphanumeric including
symbols (127)

The customer’s billing first name.

Required for gaming merchants.

X2-EN.png billinglastname
XPath: /billing/name/last
billingContact ≫ familyName Alphanumeric including
symbols (127)

The customer’s billing last name.

Required for gaming merchants.

X2-EN.png customerpostcode
XPath: /customer/postcode
shippingContact ≫ postalCode Alphanumeric (25)

The customer's delivery postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted.

Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.

X2-EN.png customerlastname
XPath: /customer/name/last
shippingContact ≫ familyName Alphanumeric including
symbols (127)

The last name on the customer's delivery address.

Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.

X3-EN.png billingcountryiso2a
XPath: /billing/country
billingContact ≫ countryCode Alpha (2)

The country on the customer's billing address. This will need to be in ISO2A format.

Click here for a full list of country codes.

X3-EN.png billingemail
XPath: /billing/email
billingContact ≫ emailAddress Email (255) The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
X3-EN.png billingpostcode
XPath: /billing/postcode
billingContact ≫ postalCode Alphanumeric (25)

The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.

X3-EN.png billingpremise
XPath: /billing/premise
billingContact ≫ addressLines Alphanumeric including
symbols (25)
The house name/number on the customer's billing address.
X3-EN.png billingtelephone
XPath: /billing/telephone
billingContact ≫ phoneNumber Alphanumeric including
symbols (20)
The customer’s billing telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
X3-EN.png billingtown
XPath: /billing/town
billingContact ≫ locality Alphanumeric including
symbols (127)
The town entered for the customer’s billing address.
X3-EN.png customercountryiso2a
XPath: /customer/country
shippingContact ≫ countryCode Alpha (2)

The country on the customer's delivery address. This will need to be in ISO2A format.

Click here for a full list of country codes.

X3-EN.png customeremail
XPath: /customer/email
shippingContact ≫ emailAddress Email (255) The customer’s delivery email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
X3-EN.png customerfirstname
XPath: /customer/name/first
shippingContact ≫ givenName Alphanumeric including
symbols (127)

The first name on the customer's delivery address.

X3-EN.png customerpremise
XPath: /customer/premise
shippingContact ≫ addressLines Alphanumeric including
symbols (25)
The house name/number on the customer's delivery address.
X3-EN.png customertelephone
XPath: /customer/telephone
shippingContact ≫ phoneNumber Alphanumeric including
symbols (20)
The customer’s delivery telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
X3-EN.png customertown
XPath: /customer/town
shippingContact ≫ locality Alphanumeric including
symbols (127)
The town on the customer's delivery address.
X3-EN.png orderreference
XPath: /merchant/orderreference
N/A Alphanumeric including
symbols (25)

Your unique order reference that can be stored on the Trust Payments system.

X3-EN.png paymenttypedescription
XPath: /billing/payment/@type
N/A Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).

 

AUTH response

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

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST09',
u 'authmethod': u 'FINAL',
u 'baseamount': u '2000',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'debtrepayment': u '0',
u 'eci': u '02',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'JP',
u 'livestatus': u '0',
u 'maskedpan': u '510000######0511',
u 'merchantcategorycode': u '1234',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'orderreference': u 'My_Order_123',
u 'operatorname': u 'webservices@example.com',
u 'paymenttypedescription': u 'MASTERCARD',
u 'requesttypedescription': u 'AUTH',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '0',
u 'settleduedate': u '2023-03-22',
u 'settlestatus': u '0',
u 'splitfinalnumber': u '1',
u 'tavv': u 'ALFoEd4DhmGzAIj3dUo4AoABFA==',
u 'tid': u '27882788',
u 'tokenisedpayment': u '1',
u 'tokentype': u 'APPLEPAY',
u 'transactionreference': u '36-9-286248',
u 'transactionstartedtimestamp': u '2023-03-22 09:34:31',
u 'walletdisplayname': u 'MasterCard 0511',
u 'walletsource': u 'APPLEPAY'
}]
}

 

Field specification

  Field Format Description
X4-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) “ECOM” is returned in the response to represent an e-commerce transaction.
X4-EN.png authmethod
XPath: /operation/authmethod
Alpha (11)

The authmethod specifies how a transaction is to be processed by the card issuer. You should expect one of the following values to be returned to indicate the authmethod employed. Click the following links to learn more:

This field is returned if submitted in the request.

X4-EN.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.
X4-EN.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The currency of the transaction.

Click here for a full list of available currencies.

X4-EN.png dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) Because Apple Pay does not support DCC, "0" will be returned to indicate DCC is disabled for this transaction.
X4-EN.png debtrepayment
XPath: /merchant/debtrepayment
Numeric (1)

Indicates if transaction is flagged as debt repayment. Click here to learn more.

X4-EN.png eci
XPath: /threedsecure/eci
Alphanumeric (2) The ECI (E-Commerce Indicator) security level associated with the transaction. Click here to learn more about possible ECI values.
X4-EN.png errorcode
XPath: /error/code
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.

X4-EN.png errormessage
XPath: /error/message
Alphanumeric (255) This provides a brief explanation as to the cause of the error.

For successful transactions, this is returned as “Ok”.

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

X4-EN.png issuercountryiso2a
XPath: /billing/payment/issuercountry
Alpha (2)

The country of the customer’s card issuer.
This will be in ISO2A format.

Click here for a full list of country codes.

X4-EN.png livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
X4-EN.png maskedpan
XPath: /billing/payment/pan
Alphanumeric including “#” (12-19) The maskedpan field represents the customer’s card number. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
X4-EN.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
X4-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).
X4-EN.png requesttypedescription
XPath: /@type
Alpha (20) “AUTH” is returned in the response.
X4-EN.png securityresponseaddress
XPath: /security/address
Numeric (1) The result of AVS and Security Code Checks.

Click here to learn more.

X4-EN.png securityresponsepostcode
XPath: /security/postcode
Numeric (1)
X4-EN.png securityresponsesecuritycode
XPath: /security/securitycode
Numeric (1)
X4-EN.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
X4-EN.png settlestatus
XPath: /settlement/settlestatus
Numeric (3)

A numeric value used to indicate the progress of settlement regarding this transaction.

Click here for a full list of settlestatus values.

X4-EN.png splitfinalnumber
XPath: /operation/splitfinalnumber
Numeric (2) Because Apple Pay does not support Split Shipment, "1" will be returned to indicate funds will be settled in one passing.
X4-EN.png tavv
XPath: /threedsecure/tavv
Alphanumeric & special characters (32) Token Authentication Verification Value
X4-EN.png tid
XPath: /merchant/tid
Alphanumeric (255) The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.
X4-EN.png tokenisedpayment
XPath: /billing/payment/pan/@tokenised
Numeric (1) This is returned with value 1 to indicate the transaction was processed using a token.
X4-EN.png tokentype
XPath: /billing/payment/pan/@tokentype
Alphanumeric (50) Used to identify the type of token used for this payment (in this case “APPLEPAY”).
X4-EN.png transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
X4-EN.png transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the transaction was processed.
X4-EN.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”).
X4-EN.png walletsource
XPath: /billing/payment/wallet/source
Alphanumeric (20) Used to identify the type of wallet used for this payment (in this case “APPLEPAY”).
X2-EN.png acquirerresponsecode
XPath: /acquirerresponsecode
Alphanumeric (255)

Used by your acquirer to indicate the outcome of the request.

This will vary depending on your acquiring bank. Please contact your bank for further information.

X2-EN.png authcode
XPath: /authcode
Alphanumeric (255)

The authorisation code provided by the issuing bank. This will differ depending on which bank you use.

Only returned if the transaction is authorised.

X2-EN.png errordata
XPath: /error/data
Alphanumeric (255)

Additional information to help troubleshoot the error.

Only returned if there has been an error.

X2-EN.png merchantcategorycode
XPath: /merchant/merchantcategorycode
Alphanumeric (255)

These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team.

Values returned depend on your account configuration.

X2-EN.png merchantcity
XPath: /merchant/merchantcity
Alphanumeric (127)
X2-EN.png merchantcountryiso2a
XPath: /merchant/merchantcountryiso2a
Alpha (2)
X2-EN.png merchantname
XPath: /merchant/merchantname
Alphanumeric (255)
X2-EN.png merchantstatecode
XPath: /merchant/merchantstatecode
Alphanumeric (127)
X2-EN.png merchantzipcode
XPath: /merchant/merchantzipcode
Alphanumeric (10)
X2-EN.png orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (25)

Your unique order reference that can be stored on the Trust Payments system.

This field is returned if submitted in the request.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request