AUTH – Trust Payments

The following documentation explains how to manually submit an AUTH request using our Webservices API.

If you are already processing e-commerce payments using our JavaScript Library (using 3-D Secure v2), you no longer need to manually perform the AUTH request described herein (as the JavaScript Library will automatically perform the authorisation).

Requirements

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.

If you are unsure, please contact our Support Team for assistance.

All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure when processing e-commerce transactions, as part of the PSD2 mandate.

Merchants that process e-commerce transactions MUST support 3DS authentication. Click here to learn more.

The following content should only be utilised by merchants processing Mail Order Telephone Order (MOTO) payments or other workflows that are exempt from the PSD2 mandate.

AUTH request

Example

To successfully process an AUTH request, you must follow the specification below:

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "accounttypedescription": "MOTO",
  "baseamount": "1050",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "currencyiso3a": "GBP",
  "expirydate": "12/2020",
  "orderreference": "My_Order_123",
  "pan": "4111111111111111",
  "requesttypedescriptions": ["AUTH"],
  "securitycode": "123",
  "sitereference": "test_site12345"
}

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' => 'MOTO',
  'baseamount' => '1050',
  'billingfirstname' => 'Joe',
  'billinglastname' => 'Bloggs',
  'currencyiso3a' => 'GBP',
  'expirydate' => '12/2020',
  'orderreference' => 'My_Order_123',
  'pan' => '4111111111111111',
  'requesttypedescriptions' => array('AUTH'),
  'securitycode' => '123',
  'sitereference' => 'test_site12345'
);

$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": "MOTO",
    "baseamount": "1050",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "currencyiso3a": "GBP",
    "expirydate": "12/2020",
    "orderreference": "My_Order_123",
    "pan": "4111111111111111",
    "requesttypedescriptions": ["AUTH"],
    "securitycode": "123",
    "sitereference": "test_site12345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription":"MOTO",
    "baseamount":"1050",
    "billingfirstname":"Joe",
    "billinglastname":"Bloggs",
    "currencyiso3a":"GBP",
    "expirydate":"12/2020",
    "orderreference":"My_Order_123",
    "pan":"4111111111111111",
    "requesttypedescriptions":["AUTH"],
    "securitycode":"123",
    "sitereference":"test_site12345"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <billing>
      <amount currencycode="GBP">1050</amount>
      <name>
        <first>Joe</first>
        <last>Bloggs</last>
      </name>
      <payment>
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
      </payment>
    </billing>
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <operation>
      <accounttypedescription>MOTO</accounttypedescription>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

When testing the AUTH request, ensure you submit your test sitereference. This ensures that transactions are processed to our test bank and no money will change hands. When you go live, you will need to swap out your test site reference for your live site reference.

Click here for test card numbers you can submit in AUTH requests while testing.

AUTH request field specification

	Field	Format	Description
Required	accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The type of account to be used: “ECOM” – E-commerce “MOTO” – Mail Order Telephone Order “RECUR” – Recurring transactions
Required	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)
Required	currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency of the transaction. Click here for a full list of available currencies. If the currency is submitted in a child request, it must be the same value as the parent transaction.
Required	expirydate XPath: /billing/payment/expirydate	Date MM/YYYY	The expiry date printed on the card.
Required	pan XPath: /billing/payment/pan	Numeric (12-19)	This is the long number printed on the front of the customer’s card.
Required	requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “AUTH”, as shown in the request example.
Required	sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	Identifies your site on the Trust Payments system. If you do not know your site reference, please contact our Support Team.
Conditional	billingfirstname XPath: /billing/name/first	Alphanumeric including symbols (127)	The customer’s billing first name. Required for gaming merchants.
Conditional	billinglastname XPath: /billing/name/last	Alphanumeric including symbols (127)	The customer’s billing last name. Required for gaming merchants.
Conditional	credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	The allowed values for this field are 0, 1 and 2. “0” – Not eligible for CoF, or no intention of re-using credentials at a later time. “1” – Cardholder credentials flagged as available for future use. “2” – Payment using previously-stored credentials. This is required for transactions where the merchant is utilising Credentials on File (CoF). If the transaction is not eligible for CoF, or you do not wish to use credentials for future transactions, you can omit this field.
Conditional	customeraccountnumber XPath: /customer/accountnumber	Numeric (20)	If account number type is “ACCOUNT”, the account number of the primary recipient. If account number type is “CARD”, the card number of the primary recipient. The returned value in the response is in a masked format, e.g. “411111#######1111”. Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.
Conditional	customeraccountnumbertype XPath: /customer/accountnumber/@type	Alpha (7)	Either “CARD” or “ACCOUNT”. Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.
Conditional	customerdob XPath: /customer/dob	Date YYYY-MM-DD	The date of birth of the primary recipient. Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.
Conditional	customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The customer’s last name. Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.
Conditional	customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The 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	initiationreason XPath: /operation/initiationreason	Char (1)	This is required when processing a Merchant Initiated Transaction (MIT). Allows you to assign a reason for a Merchant Initiated Transaction (MIT). Do not submit when processing a Customer Initiated Transaction (CIT). The allowed values for this field are “A”, “C”, “D”, “S” and “X”. “A” – Reauthorisation “C” – Unscheduled payment “D” – Delayed Charges “S” – Resubmission “X” – No-show (for a hotel booking) Click here for further information on the different initiationreason values. Note: You must ensure the initiationreason submitted in the request correctly represents the reason for the new payment.
Conditional	scaexemptionindicator XPath: /operation/scaexemptionindicator	Numeric (1)	Required if flagging a transaction as exempt from EMV 3DS. Click here to learn more. Submit one of the following values: 1 – Low value 2 – Transaction Risk Analysis 3 – Trusted Merchant 4 – Secure Corporate payment 5 – Delegated authentication The scaexemptionindicator field must only ever be submitted in an AUTH request. Submission of the scaexemptionindicator field is not supported when a parent transaction is being referenced. Failure to meet these conditions will prevent the exemption from being applied.
Optional	authmethod XPath: /operation/authmethod	Alpha (11)	Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click the following links to learn more: PRE - Pre-authorisation FINAL - Final authorisation INCREMENTAL - Incremental authorisation SPLIT - Split shipment The contents of authmethod do not affect the settlement status of the transaction. Settlement status can be controlled using settlestatus and settleduedate. Click here to learn more about the settlement process.
Optional	billingcountryiso2a XPath: /billing/country	Alpha (2)	The country for the customer’s billing address. This will need to be in ISO2A format. Click here for a full list of country codes.
Optional	billingcounty XPath: /billing/county	Alphanumeric including symbols (127)	The county entered for the customer’s billing address. For US addresses, the state would be entered in this field. Valid formats: Preferred: Two character state code, e.g. “NY”. Full state name, e.g. “New York”.
Optional	billingemail XPath: /billing/email	Email (255)	The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
Optional	billingmiddlename XPath: /billing/name/middle	Alphanumeric including symbols (127)	The customer’s billing middle name(s).
Optional	billingpostcode XPath: /billing/postcode	Alphanumeric (25)	The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.
Optional	billingprefixname XPath: /billing/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
Optional	billingpremise XPath: /billing/premise	Alphanumeric including symbols (25)	The house number or first line of the customer’s billing address.
Optional	billingstreet XPath: /billing/street	Alphanumeric including symbols (127)	The street entered for the customer’s billing address.
Optional	billingsuffixname XPath: /billing/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s billing name (e.g. Bsc).
Optional	billingtelephone XPath: /billing/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
Optional	billingtelephonetype XPath: /billing/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work
Optional	billingtown XPath: /billing/town	Alphanumeric including symbols (127)	The town entered for the customer’s billing address.
Optional	chargedescription XPath: /merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the payment that appears on the customer’s bank statement. This is supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. Specification of this field will depend on your acquiring bank. Click here for further information. Valid characters: Uppercase/lowercase A-Z Numbers 0-9 Spaces Punctuation: + – _ . @ ( )
Optional	cryptocurrencyindicator XPath: /operation/cryptocurrencyindicator	Numeric (1)	Indicates if transaction is flagged as a purchase of cryptocurrency: 1 – Transaction is flagged as cryptocurrency purchase. 0 – Transaction is not flagged as cryptocurrency purchase. The use of this functionality is subject to requirements. Click here to learn more.
Optional	customercountryiso2a XPath: /customer/country	Alpha (2)	The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes.
Optional	customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The customer’s county. For US addresses, the state would be entered in this field. Valid formats: Preferred: 2-character state code, e.g. “NY”. Full state name, e.g. “New York”.
Optional	customeremail XPath: /customer/email	Email (255)	The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
Optional	customerfirstname XPath: /customer/name/first	Alphanumeric including symbols (127)	The customer’s first name.
Optional	customerforwardedip XPath: /customer/forwardedip	IP address (39)	Customer forwarded IP address, as provided by a proxy server if available.
Optional	customerip XPath: /customer/ip	IP address (39)	The IP of the customer.
Optional	customermiddlename XPath: /customer/name/middle	Alphanumeric including symbols (127)	The customer’s middle name(s).
Optional	customerprefixname XPath: /customer/name/prefix	Alphanumeric including symbols (25)	The customer’s prefix name (e.g. Mr, Miss, Dr).
Optional	customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The customer’s house name or number.
Optional	customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The customer’s street name.
Optional	customersuffixname XPath: /customer/name/suffix	Alphanumeric including symbols (25)	The customer’s suffix name (e.g. Bsc).
Optional	customertelephone XPath: /customer/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
Optional	customertelephonetype XPath: /customer/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work
Optional	customertown XPath: /customer/town	Alphanumeric including symbols (127)	The customer’s town.
Optional	merchantemail XPath: /merchant/email	Email (255)	The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
Optional	operatorname XPath: /merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request. By default, this is the Web Services username included in the request. This can be overridden with a custom value by passing through this field in the request (optional).
Optional	orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25)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.	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).
Optional	parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
Optional	paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	Payment method (e.g. “VISA” or “MASTERCARD”).
Optional	securitycode XPath: /billing/payment/securitycode	Numeric (3-4)	This is the 3-digit security code printed on the back of the card. (For AMEX cards, this is a 4-digit code found on the front of the card) This field is not strictly required by Trust Payments, but it is highly recommended for the processing of security code checks. Additionally, some banks may decline the payment if the security code is not present.
Optional	settleduedate XPath: /settlement/settleduedate	Date YYYY-MM-DD	You can submit this field in the request to specify the date you would like your transaction to settle. This must be within 7 days of the authorisation date.
Optional	settlestatus XPath: /settlement/settlestatus	Numeric (3)	A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”. Click to learn more about the settlement process.

AUTH response

The following is an example of an AUTH response indicating the request was processed successfully.

{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'MOTO',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST36',
u 'baseamount': u '1050',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuer': u 'Test Issuer',
u 'issuercountryiso2a': u 'US',
u 'livestatus': u '0',
u 'maskedpan': u '411111######1111',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'operatorname': u 'webservices@example.com',
u 'orderreference': u 'My_Order_123',
u 'paymenttypedescription': u 'VISA',
u 'requesttypedescription': u 'AUTH',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '2',
u 'settleduedate': u '2016-12-07',
u 'settlestatus': u '0',
u 'splitfinalnumber': u '1',
u 'tid': u '27882788',
u 'transactionreference': u '23-9-80001',
u 'transactionstartedtimestamp': u '2016-12-07 11:32:44'
}]
}

array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(28) {
      ["accounttypedescription"] => string(4) "MOTO"
      ["acquirerresponsecode"] => string(2) "00"
      ["authcode"] => string(6) "TEST31"
      ["baseamount"] => string(4) "1050"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["currencyiso3a"] => string(3) "GBP"
      ["dccenabled"] => string(1) "0"
      ["issuer"] => string(26) "Test Issuer"
      ["issuercountryiso2a"] => string(2) "US"
      ["livestatus"] => string(1) "0"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["merchantname"] => string(13) "Test Merchant"
      ["merchantnumber"] => string(8) "00000000"
      ["operatorname"] => string(23) "webservices@example.com"
      ["orderreference"] => string(12) "My_Order_123"
      ["paymenttypedescription"] => string(4) "VISA"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponseaddress"] => string(1) "0"
      ["securityresponsepostcode"] => string(1) "0"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["settleduedate"] => string(10) "2016-12-09"
      ["settlestatus"] => string(1) "0"
      ["splitfinalnumber"] => string(1) "1"
      ["tid"] => string(8) "27882788"
      ["transactionreference"] => string(10) "72-9-80003"
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 09:52:19"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"MOTO",
    "acquirerresponsecode":"00",
    "authcode":"TEST96",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "dccenabled":"0",
    "errorcode":"0",
    "errormessage":"Ok",
    "issuer":"Test Issuer",
    "issuercountryiso2a":"US",
    "livestatus":"0",
    "maskedpan":"411111######1111",
    "merchantcountryiso2a":"GB",
    "merchantname":"Test Merchant",
    "merchantnumber":"00000000",
    "operatorname":"webservices@example.com",
    "orderreference":"My_Order_123",
    "paymenttypedescription":"VISA",
    "requesttypedescription":"AUTH",
    "securityresponseaddress":"0",
    "securityresponsepostcode":"0",
    "securityresponsesecuritycode":"2",
    "settleduedate":"2016-12-07",
    "settlestatus":"0",
    "splitfinalnumber":"1",
    "tid":"27882788",
    "transactionreference":"23-9-80006",
    "transactionstartedtimestamp":"2016-12-07 15:08:47"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>A3579dkvx</requestreference>
  <response type="AUTH">
    <acquirerresponsecode>00</acquirerresponsecode>
    <authcode>TEST96</authcode>
    <billing>
      <amount currencycode="GBP">1050</amount>
      <dcc enabled="0"/>
      <payment type="VISA">
        <issuer>Test Issuer</issuer>
        <issuercountry>ZZ</issuercountry>
        <pan>411111######1111</pan>
      </payment>
    </billing>
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <live>0</live>
    <merchant>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <merchantname>Test Merchant</merchantname>
      <merchantnumber>00000000</merchantnumber>
      <operatorname>webservices@example.com</operatorname>
      <orderreference>MyOrder123</orderreference>
      <tid>27882788</tid>
    </merchant>
    <operation>
      <accounttypedescription>MOTO</accounttypedescription>
      <authmethod>PRE</authmethod>
      <splitfinalnumber>1</splitfinalnumber>
    </operation>
    <security>
      <address>2</address>
      <postcode>2</postcode>
      <securitycode>2</securitycode>
    </security>
    <settlement>
      <settleduedate>2012-10-08</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2012-10-08 12:46:02</timestamp>
    <transactionreference>23-9-80006</transactionreference>
  </response>
  <secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>

When you receive an AUTH response, you must check the field values, to ensure the request was processed successfully.

Click here for recommended checks to perform.

AUTH response field specification

	Field	Format	Description
Returned	accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The type of account to be used: “ECOM” – E-commerce. “MOTO” – Mail Order Telephone Order “RECUR” – Recurring transactions
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. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
Returned	currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency of the transaction. Click here for a full list of available currencies.
Returned	dccenabled XPath: /billing/dcc/@enabled	Numeric (1)	Indicates if your account is configured for DCC: 1= Yes 0 = No
Returned	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.
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”. Click here for a full list of errorcode and message values.
Returned	issuercountryiso2a XPath: /billing/payment/issuercountry	Alpha (2)	The country for the customer’s card issuer. This will be in ISO2A format. Click here for a full list of country codes.
Returned	livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
Returned	maskedpan XPath: /billing/payment/pan	Alphanumeric including “#” (12-19)	If tokenisedpayment is not returned: The maskedpan field represents the customer’s card number. If tokenisedpayment is returned with value 1: The maskedpan field represents the customer’s unique token number used to perform the transaction. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
Returned	merchantnumber XPath: /merchant/merchantnumber	Alphanumeric (32)	The merchant number that was used to process the transaction. Provided by the acquiring bank.
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. Click here to learn more.
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. Click here for a full list of settlestatus values.
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	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.
Conditional	acquireradvicecode XPath: /acquireradvicecode	Numeric (1)	A numeric value returned following a repeat payment request, indicating if further payments can be processed. Mapping: 0 – No action required. 1 – New account information available. 2 – Cannot approve at this time. 4 – Do not process further recurring transactions. 8 – Payment blocked by card scheme. This will vary depending on your acquiring bank. Please contact your bank for further information.
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	acquirerresponsemessage XPath: /acquirerresponsemessage	Alphanumeric (255)
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	authmethod XPath: /operation/authmethod	Alpha (11)	Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click the following links to learn more: PRE - Pre-authorisation FINAL - Final authorisation INCREMENTAL - Incremental authorisation SPLIT - Split shipment This field is returned if submitted in the request.
Conditional	chargedescription XPath: /merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the payment that appears on the customer’s bank statement. This is supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. Specification of this field will depend on your acquiring bank. Click here for further information. Valid characters: Uppercase/lowercase A-Z Numbers 0-9 Spaces Punctuation: + – _ . @ ( ) This field is returned if sent to the acquiring bank.
Conditional	credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	The allowed values for this field are 0, 1 and 2. “0” – Not eligible for CoF, or no intention of re-using credentials at a later time. “1” – Transaction credentials flagged as available for future use. “2” – Payment using previously-stored credentials. This field is returned if submitted in the request.
Conditional	cryptocurrencyindicator XPath: /operation/cryptocurrencyindicator	Numeric (1)	Indicates if transaction is flagged as a purchase of cryptocurrency: 1 – Transaction is flagged as cryptocurrency purchase. 0 – Transaction is not flagged as cryptocurrency purchase. This field is returned if provided by the acquiring bank, otherwise not returned.
Conditional	errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
Conditional	issuer XPath: /billing/payment/issuer	Alphanumeric (255)	The customer’s card issuer. This information is returned if available.
Conditional	merchantcategorycode XPath: /merchant/merchantcategorycode	Alphanumeric (255)	Merchant Category Code (MCC) held in our records. These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
Conditional	merchantcity XPath: /merchant/merchantcity	Alphanumeric (127)	City on the merchant's address held in our records. These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
Conditional	merchantcountryiso2a XPath: /merchant/merchantcountryiso2a	Alpha (2)	Country on the merchant's address held in our records. These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
Conditional	merchantname XPath: /merchant/merchantname	Alphanumeric (255)	Merchant name held in our records. These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
Conditional	merchantstatecode XPath: /merchant/merchantstatecode	Alphanumeric (127)	State code on the merchant's address held in our records. These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
Conditional	merchantzipcode XPath: /merchant/merchantzipcode	Alphanumeric (10)	Zip code on the merchant's address held in our records. These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
Conditional	orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25)	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). This field is returned if submitted in the request.
Conditional	parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference of a previous request, from which key details have been inherited. This field is returned if submitted in the request.
Conditional	retrievalreferencenumber XPath: /other/retrievalreferencenumber	Alphanumeric (255)	An ISO term. This is used to reference the source transaction. This will vary depending on your acquiring bank. Please contact your bank for further information.
Conditional	scaexemptionindicator XPath: /operation/scaexemptionindicator	Numeric (1)	Returned if transaction has been flagged as exempt from EMV 3DS. Click here to learn more. The following values can be returned: 1 – Low value 2 – Transaction Risk Analysis 3 – Trusted Merchant 4 – Secure Corporate payment 5 – Delegated authentication
Conditional	tokenisedpayment XPath: /billing/payment/pan/@tokenised	Numeric (1)	If this field is returned with value 1, this indicates the transaction was processed using a token. This field is returned if payment was performed using a token.
Conditional	tokentype XPath: /billing/payment/pan/@tokentype	Alphanumeric (50)	Used to identify the type of token used for this payment (e.g. “VISATOKEN”). This field is returned if payment was performed using a token.
Conditional	walletdisplayname XPath: /billing/payment/wallet/displayname	Alphanumeric (255)	This normally contains the last four digits of the customer’s card number (e.g. “1111”). This field is returned if payment was performed using a wallet.
Conditional	walletsource XPath: /billing/payment/wallet/source	Alphanumeric (20)	Used to identify the type of wallet used for this payment (e.g. “APPLEPAY”). This field is returned if payment was performed using a wallet.

In addition to the response object, two additional fields are also returned in the response:

	Field	Format	Description
Returned	requestreference	Alphanumeric (25)	This is an internal field generated by Trust Payments. It must not be validated. If problems are experienced with the request this field may be requested by Trust Payments support to aid in determining the cause.
Returned	secrand	Alphanumeric (16)	Random string of characters, returned in the response of non-API-based libraries developed by Trust Payments.