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:
#!/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
<?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(
'accounttypedescription' => 'ECOM',
'baseamount' => '2000',
'currencyiso3a' => 'GBP',
'eci' => '2',
'expirydate' => '07/2023',
'orderreference' => 'My_Order_123',
'pan' => '5100000000000511',
'requesttypedescriptions' => array('AUTH'),
'sitereference' => 'test_site12345',
'tavv' => 'ALFoEd4DhmGzAIj3dUo4AoABFA==',
'walletdisplayname' => 'MasterCard 0511',
'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": [{
"accounttypedescription":"ECOM",
"baseamount":"2000",
"currencyiso3a":"GBP",
"eci":"2",
"expirydate":"07/2023",
"orderreference": "My_Order_123",
"pan":"5100000000000511",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"tavv":"ALFoEd4DhmGzAIj3dUo4AoABFA==",
"walletdisplayname":"MasterCard 0511",
"walletsource":"APPLEPAY"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"ECOM",
"baseamount":"2000",
"currencyiso3a":"GBP",
"eci":"2",
"expirydate":"07/2023",
"orderreference": "My_Order_123",
"pan":"5100000000000511",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"tavv":"ALFoEd4DhmGzAIj3dUo4AoABFA==",
"walletdisplayname":"MasterCard 0511",
"walletsource":"APPLEPAY"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<billing>
<payment>
<expirydate>07/2023</expirydate>
<pan>5100000000000511</pan>
<wallet>
<displayname>MasterCard 0511</displayname>
<source>APPLEPAY</source>
</wallet>
</payment>
<amount currencycode="GBP">2000</amount>
</billing>
<merchant>
<orderreference>My_Order_123</orderreference>
</merchant>
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<threedsecure>
<eci>2</eci>
<tavv>ALFoEd4DhmGzAIj3dUo4AoABFA==</tavv>
</threedsecure>
</request>
</requestblock>
Field specification
| Field | Mapping to fields from decrypted token | Format | Description | |
| Required |
accounttypedescription XPath: /operation/accounttypedescription |
N/A | Alpha (20) | Submit “ECOM” to represent an e-commerce transaction. |
| Required |
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. |
| Required |
currencyiso3a XPath: /billing/amount/@currencycode |
N/A | Alpha (3) | The currency of the transaction. Click here for a full list of available currencies. |
| Required |
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. |
| Required |
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. |
| Required |
pan XPath: /billing/payment/pan |
paymentData ≫ applicationPrimaryAccountNumber | Numeric (12-19) | This is the long number printed on the front of the customer’s card. |
| Required |
requesttypedescriptions XPath: /@type |
N/A | Alpha (20) |
Supported request type combinations:
|
| Required |
sitereference XPath: /operation/sitereference |
N/A |
Alphanumeric & underscore (50) |
Identifies your site on the Trust Payments system. |
| Required |
tavv XPath: /threedsecure/tavv |
paymentData ≫ onlinePaymentCryptogram | Alphanumeric & special characters (32) | Token Authentication Verification Value |
| Required |
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. |
| Required |
walletsource XPath: /billing/payment/wallet/source |
N/A | Alpha (8) | Must be submitted with value “APPLEPAY”. |
| Conditional |
billingfirstname XPath: /billing/name/first |
billingContact ≫ givenName |
Alphanumeric including symbols (127) |
The customer’s billing first name. Required for gaming merchants. |
| Conditional |
billinglastname XPath: /billing/name/last |
billingContact ≫ familyName |
Alphanumeric including symbols (127) |
The customer’s billing last name. Required for gaming merchants. |
| Conditional |
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. |
| Conditional |
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. |
| Optional |
billingcountryiso2a XPath: /billing/country |
billingContact ≫ countryCode | Alpha (2) |
The country on the customer's billing address. This will need to be in ISO2A format. |
| Optional |
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). |
| Optional |
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. |
| Optional |
billingpremise XPath: /billing/premise |
billingContact ≫ addressLines |
Alphanumeric including symbols (25) |
The house name/number on the customer's billing address. |
| Optional |
billingtelephone XPath: /billing/telephone |
billingContact ≫ phoneNumber |
Alphanumeric including symbols (20) |
The customer’s billing telephone number. Valid characters:
|
| Optional |
billingtown XPath: /billing/town |
billingContact ≫ locality |
Alphanumeric including symbols (127) |
The town entered for the customer’s billing address. |
| Optional |
customercountryiso2a XPath: /customer/country |
shippingContact ≫ countryCode | Alpha (2) |
The country on the customer's delivery address. This will need to be in ISO2A format. |
| Optional |
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). |
| Optional |
customerfirstname XPath: /customer/name/first |
shippingContact ≫ givenName |
Alphanumeric including symbols (127) |
The first name on the customer's delivery address. |
| Optional |
customerpremise XPath: /customer/premise |
shippingContact ≫ addressLines |
Alphanumeric including symbols (25) |
The house name/number on the customer's delivery address. |
| Optional |
customertelephone XPath: /customer/telephone |
shippingContact ≫ phoneNumber |
Alphanumeric including symbols (20) |
The customer’s delivery telephone number. Valid characters:
|
| Optional |
customertown XPath: /customer/town |
shippingContact ≫ locality |
Alphanumeric including symbols (127) |
The town on the customer's delivery address. |
| Optional |
orderreference XPath: /merchant/orderreference |
N/A |
Alphanumeric including symbols (25) |
Your unique order reference that can be stored on the Trust Payments system. |
| Optional |
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:
{
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'
}]
}
array(3) {
["requestreference"] => string(9) "A3579dkvx"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(36) {
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["authcode"] => string(6) "TEST09"
["authmethod"] => string(4) "FINAL"
["baseamount"] => string(4) "2000"
["currencyiso3a"] => string(3) "GBP"
["dccenabled"] => string(1) "0"
["debtrepayment"] => string(1) "0"
["eci"] => string(2) "02"
["errorcode"] => string(1) "0"
["errormessage"] => string(2) "Ok"
["issuercountryiso2a"] => string(2) "JP"
["livestatus"] => string(1) "0"
["maskedpan"] => string(16) "510000######0511"
["merchantcategorycode"] => string(4) "1234',
["merchantcountryiso2a"] => string(2) "GB"
["merchantname"] => string(13) "Test Merchant"
["merchantnumber"] => string(8) "00000000"
["operatorname"] => string(13) "webservices@example.com"
["orderreference"] => string(12) "My_Order_123',
["paymenttypedescription"] => string(10) "MASTERCARD"
["requesttypedescription"] => string(4) "AUTH"
["securityresponseaddress"] => string(1) "0"
["securityresponsepostcode"] => string(1) "0"
["securityresponsesecuritycode"] => string(1) "0"
["settleduedate"] => string(10) "2023-03-22"
["settlestatus"] => string(1) "0"
["splitfinalnumber"] => string(1) "1"
["tavv"] => string(28) "ALFoEd4DhmGzAIj3dUo4AoABFA=="
["tid"] => string(8) "27882788"
["tokenisedpayment"] => string(1) "1"
["tokentype"] => string(8) "APPLEPAY"
["transactionreference"] => string(11) "36-9-286248"
["transactionstartedtimestamp"] => string(19) "2023-03-22 09:34:31"
["walletdisplayname"] => string(19) "MasterCard 0511"
["walletsource"] => string(8) "APPLEPAY"
}
}
}
{
"requestreference":"W23-fjgvn3d8",
"version":"1.00",
"response":[{
"accounttypedescription": "ECOM",
"acquirerresponsecode": "00",
"authcode": "TEST09",
"authmethod": "FINAL",
"baseamount": "2000",
"currencyiso3a": "GBP",
"dccenabled": "0",
"debtrepayment": "0",
"eci": "02",
"errorcode": "0",
"errormessage": "Ok",
"issuercountryiso2a": "JP",
"livestatus": "0",
"maskedpan": "510000######0511",
"merchantcategorycode": "1234",
"orderreference": "My_Order_123",
"merchantcountryiso2a": "GB",
"merchantname": "Test Merchant",
"merchantnumber": "00000000",
"operatorname": "webservices@example.com",
"paymenttypedescription": "MASTERCARD",
"requesttypedescription": "AUTH",
"securityresponseaddress": "0",
"securityresponsepostcode": "0",
"securityresponsesecuritycode": "0",
"settleduedate": "2023-03-22",
"settlestatus": "0",
"splitfinalnumber": "1",
"tavv": "ALFoEd4DhmGzAIj3dUo4AoABFA==",
"tid": "27882788",
"tokenisedpayment": "1",
"tokentype": "APPLEPAY",
"transactionreference": "36-9-286248",
"transactionstartedtimestamp": "2023-03-22 09:34:31",
"walletdisplayname": "MasterCard 0511",
"walletsource": "APPLEPAY"
}],
"secrand":"zO9"
}
<responseblock version="3.67">
<requestreference>A3579dkvx</requestreference>
<response type="AUTH">
<acquirerresponsecode>00</acquirerresponsecode>
<authcode>TEST09</authcode>
<billing>
<amount currencycode="GBP">2000</amount>
<dcc enabled="0"/>
<payment type="MASTERCARD">
<issuercountry>JP</issuercountry>
<pan tokenised="1" tokentype="APPLEPAY">510000######0511</pan>
<wallet>
<displayname>MasterCard 0511</displayname>
<source>APPLEPAY</source>
</wallet>
</payment>
</billing>
<error>
<code>0</code>
<message>Ok</message>
</error>
<live>0</live>
<merchant>
<debtrepayment>0</debtrepayment>
<merchantcategorycode>1234</merchantcategorycode>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<merchantnumber>00000000</merchantnumber>
<operatorname>webservices@example.com</operatorname>
<orderreference>My_Order_123</orderreference>
<tid>27882788</tid>
</merchant>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<authmethod>FINAL</authmethod>
<splitfinalnumber>1</splitfinalnumber>
</operation>
<security>
<address>0</address>
<postcode>0</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2023-03-22</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<threedsecure>
<eci>02</tavv>
<tavv>ALFoEd4DhmGzAIj3dUo4AoABFA==</tavv>
</threedsecure>
<timestamp>2023-03-22 09:34:31</timestamp>
<transactionreference>36-9-286248</transactionreference>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>
Field specification
| Field | Format | Description | |
| Returned | accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | “ECOM” is returned in the response to represent an e-commerce transaction. |
| Returned | 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. |
| Returned | 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. |
| Returned | currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The currency of the transaction. |
| Returned | 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. |
| Returned | debtrepayment XPath: /merchant/debtrepayment |
Numeric (1) |
Indicates if transaction is flagged as debt repayment. Click here to learn more. |
| Returned | 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. |
| Returned | errorcode XPath: /error/code |
Numeric (1-5) |
The error code should be used to determine if the request was successful or not.
|
| Returned | 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”. |
| Returned | issuercountryiso2a XPath: /billing/payment/issuercountry |
Alpha (2) |
The country of the customer’s card issuer. |
| Returned | livestatus XPath: /live |
Numeric (1) |
|
| Returned | 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. |
| Returned | operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
| Returned | paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | Payment method (e.g. “VISA” or “MASTERCARD”). |
| Returned | requesttypedescription XPath: /@type |
Alpha (20) | “AUTH” is returned in the response. |
| Returned | securityresponseaddress XPath: /security/address |
Numeric (1) | The result of AVS and Security Code Checks. |
| Returned | securityresponsepostcode XPath: /security/postcode |
Numeric (1) | |
| Returned | securityresponsesecuritycode XPath: /security/securitycode |
Numeric (1) | |
| Returned | settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. |
| Returned | settlestatus XPath: /settlement/settlestatus |
Numeric (3) |
A numeric value used to indicate the progress of settlement regarding this transaction. |
| Returned | 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. |
| Returned | tavv XPath: /threedsecure/tavv |
Alphanumeric & special characters (32) | Token Authentication Verification Value |
| Returned | 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. |
| Returned | tokenisedpayment XPath: /billing/payment/pan/@tokenised |
Numeric (1) | This is returned with value 1 to indicate the transaction was processed using a token. |
| Returned | tokentype XPath: /billing/payment/pan/@tokentype |
Alphanumeric (50) | Used to identify the type of token used for this payment (in this case “APPLEPAY”). |
| Returned | 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. |
| Returned | transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the transaction was processed. |
| Returned | 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”). |
| Returned | walletsource XPath: /billing/payment/wallet/source |
Alphanumeric (20) | Used to identify the type of wallet used for this payment (in this case “APPLEPAY”). |
| Conditional | 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. |
| Conditional | 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. |
| Conditional | errordata XPath: /error/data |
Alphanumeric (255) |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
| Conditional | 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. |
| Conditional | merchantcity XPath: /merchant/merchantcity |
Alphanumeric (127) | |
| Conditional | merchantcountryiso2a XPath: /merchant/merchantcountryiso2a |
Alpha (2) | |
| Conditional | merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | |
| Conditional | merchantstatecode XPath: /merchant/merchantstatecode |
Alphanumeric (127) | |
| Conditional | merchantzipcode XPath: /merchant/merchantzipcode |
Alphanumeric (10) | |
| Conditional | 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. |
