Authorisations
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

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

To process an e-commerce transaction that is authenticated with 3-D Secure, you will need to utilise our JavaScript Library instead of the solution described below. Click here to get started.
The following content should only be utilised by merchants processing Mail or Telephone Order (MOTO) payments, Merchant Initiated Transactions (MIT), or other workflows that are exempt from the PSD2 mandate.

To perform 3-D Secure, you will need to utilise our JavaScript Library. Click here to get started.

Failure to submit these fields may prevent the transaction from being processed successfully, with a “60025” errorcode being returned in the response.
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 = "[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", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123" } 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', 'pan' => '4111111111111111', 'expirydate' => '12/2020', 'securitycode' => '123' ); $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", "accounttypedescription": "ECOM", "pan": "4111111111111111", "expirydate": "12/2020", "securitycode": "123" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","baseamount":"1050","orderreference":"My_Order_123","accounttypedescription":"ECOM","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123"}]}
<requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <payment> <expirydate>12/2020</expirydate> <pan>4111111111111111</pan> <securitycode>123</securitycode> </payment> <amount currencycode="GBP">1050</amount> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.

Click here for test card numbers you can submit in AUTH requests while testing.
Field specification
Operation The following fields relate to the type of request submitted: Do not submit when processing a Customer Initiated Transaction (CIT).The allowed values for this field are “A”, “C”, “D”, “S” and “X”. 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. Visa may introduce new values to this list in the future. Please refer to Visa’s own documentation for further information. If you do not know your site reference, please contact our Support Team. Payment The following fields contain the customer’s payment details: If the currency is submitted in a child request, it must be the same value as the parent transaction. (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. Merchant The following fields relate to your account configuration and allow you to configure custom unique references for your request: Specification of this field will depend on your acquiring bank. Click here for further information. Valid characters: Note: This can be updated at a later time (only if transaction is pending settlement). Billing The following fields contain the customer’s billing details: If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated. Customer and delivery The following fields contain the customer’s delivery details: If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated. Settlement The following fields contain the Settlement details: The following is an example of an AUTH response indicating the request was processed successfully. When you receive an AUTH response, you must check the field values, to ensure the request was processed successfully. Please refer to our “Best practices” for further information. Operation The following fields relate to the type of request submitted: Billing The following fields contain the customer’s billing details: Merchant The following fields relate to your account configuration: Only supported by certain acquiring banks. Specification of this field will depend on your acquiring bank. Click here for further information. Valid characters: Note: This can be updated at a later time (only if transaction is pending settlement). Settlement The following fields contain the Settlement details: Transaction status The following fields returned in the response indicate the outcome of the request: Mapping: For successful transactions, this is returned as “Ok”.
Field
Format
Description
accounttypedescription
XPath: /operation/accounttypedescriptionAlpha (20)
The type of account to be used:
authmethod
XPath: /operation/authmethodAlpha (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 here for further information.
credentialsonfile
XPath: /operation/credentialsonfileNumeric (1)
The allowed values for this field are 0, 1 and 2.
initiationreason
XPath: /operation/initiationreasonChar (1)
Allows you to assign a reason for a Merchant Initiated Transaction (MIT).
parenttransactionreference
XPath: /operation/parenttransactionreferenceAlphanumeric
& hyphens (25)Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
requesttypedescriptions
XPath: /@typeAlpha (20)
You must submit “AUTH”, as shown in the request example.
sitereference
XPath: /operation/sitereferenceAlphanumeric
& underscore (50)Identifies your site on the Trust Payments system.
Field
Format
Description
baseamount
XPath: /billing/amountNumeric (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)
currencyiso3a
XPath: /billing/amount/@currencycodeAlpha (3)
The currency of the transaction. Click here for a full list of available currencies.
expirydate
XPath: /billing/payment/expirydateDate MM/YYYY
The expiry date printed on the card.
pan
XPath: /billing/payment/pan Numeric (12-19)
This is the long number printed on the front of the customer’s card.
paymenttypedescription
XPath: /billing/payment/@typeAlpha (20)
Payment method (e.g. “VISA” or “MASTERCARD”).
securitycode
XPath: /billing/payment/securitycode Numeric (3-4)
This is the three digit security code printed on the back of the card.
Field
Format
Description
chargedescription
XPath: /merchant/chargedescriptionAlphanumeric including
symbols (25)This is a description of the payment that appears on the customer’s bank statement. Only supported by certain acquiring banks.
merchantemail
XPath: /merchant/email Email (255)
The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
operatorname
XPath: /merchant/operatornameAlphanumeric (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).
orderreference
XPath: /merchant/orderreference Alphanumeric including
symbols (255)Your unique order reference that can be stored on the Trust Payments system.
Field
Format
Description
billingpremise
XPath: /billing/premiseAlphanumeric including
symbols (25)The house number or first line of the customer’s billing address.
billingstreet
XPath: /billing/streetAlphanumeric including
symbols (127)The street entered for the customer’s billing address.
billingtown
XPath: /billing/townAlphanumeric including
symbols (127)The town entered for the customer’s billing address.
billingcounty
XPath: /billing/countyAlphanumeric 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:
billingcountryiso2a
XPath: /billing/countryAlpha (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.
billingpostcode
XPath: /billing/postcodeAlphanumeric (25)
The postcode entered for the customer’s billing address.
billingemail
XPath: /billing/emailEmail (255)
The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingtelephonetype
XPath: /billing/telephone/@typeChar (1)
The type of telephone number. The options available are:
billingtelephone
XPath: /billing/telephoneAlphanumeric including
symbols (20)The customer’s telephone number. Valid characters:
billingprefixname
XPath: /billing/name/prefixAlphanumeric including
symbols (25)The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname
XPath: /billing/name/firstAlphanumeric including
symbols (127)The customer’s billing first name.
billingmiddlename
XPath: /billing/name/middleAlphanumeric including
symbols (127)The customer’s billing middle name(s).
billinglastname
XPath: /billing/name/lastAlphanumeric including
symbols (127)The customer’s billing last name.
billingsuffixname
XPath: /billing/name/suffixAlphanumeric including
symbols (25)The suffix of the customer’s billing name (e.g. Bsc).
Field
Format
Description
customerpremise
XPath: /customer/premiseAlphanumeric including
symbols (25)The customer’s house name or number.
customerstreet
XPath: /customer/streetAlphanumeric including
symbols (127)The customer’s street name.
customertown
XPath: /customer/townAlphanumeric including
symbols (127)The customer’s town.
customercounty
XPath: /customer/countyAlphanumeric including
symbols (127)The customer’s county. For US addresses, the state would be entered in this field. Valid formats:
customercountryiso2a
XPath: /customer/countryAlpha (2)
The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerpostcode
XPath: /customer/postcodeAlphanumeric (25)
The customer’s postcode or ZIP code.
customeremail
XPath: /customer/emailEmail (255)
The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
customertelephonetype
XPath: /customer/telephone/@typeChar (1)
The type of telephone number. The options available are:
customertelephone
XPath: /customer/telephoneAlphanumeric including
symbols (20)The customer’s telephone number. Valid characters:
customerprefixname
XPath: /customer/name/prefixAlphanumeric including
symbols (25)The customer’s prefix name (e.g. Mr, Miss, Dr).
customerfirstname
XPath: /customer/name/firstAlphanumeric including
symbols (127)The customer’s first name.
customermiddlename
XPath: /customer/name/middleAlphanumeric including
symbols (127)The customer’s middle name(s).
customerlastname
XPath: /customer/name/lastAlphanumeric including
symbols (127)The customer’s last name.
customersuffixname
XPath: /customer/name/suffixAlphanumeric including
symbols (25)The customer’s suffix name (e.g. Bsc).
customerforwardedip
XPath: /customer/forwardedipIP address (39)
Customer forwarded IP address, as provided by a proxy server if available.
customerip
XPath: /customer/ipIP address (39)
The IP of the customer.
Field
Format
Description
settleduedate
XPath: /settlement/settleduedateDate 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.
settlestatus
XPath: /settlement/settlestatusNumeric (3)
A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.
AUTH response
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'response': [{
u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
u 'livestatus': u '0',
u 'issuer': u 'Test Issuer',
u 'splitfinalnumber': u '1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '23-9-80001',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST36',
u 'errormessage': u 'Ok',
u 'operatorname': u '[email protected]',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A3579dkvx"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(28) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 09:52:19"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "Test Issuer"
["splitfinalnumber"] => string(1) "1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["securityresponsepostcode"] => string(1) "0"
["transactionreference"] => string(10) "72-9-80003"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(4) "1050"
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(4) "AUTH"
["securityresponsesecuritycode"] => string(1) "2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST31"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "[email protected]"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "0"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:08:47","livestatus":"0","issuer":"Test Issuer","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"23-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST96","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"zO9"}
<responseblock version="3.67">
<requestreference>A3579dkvx</requestreference>
<response type="AUTH">
<merchant>
<merchantname>Test Merchant</merchantname>
<orderreference>MyOrder123</orderreference>
<tid>27882788</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>23-9-80006</transactionreference>
<security>
<postcode>2</postcode>
<securitycode>2</securitycode>
<address>2</address>
</security>
<billing>
<amount currencycode="GBP">1050</amount>
<payment type="VISA">
<issuer>Test Issuer</issuer>
<issuercountry>ZZ</issuercountry>
<pan>411111######1111</pan>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST96</authcode>
<timestamp>2012-10-08 12:46:02</timestamp>
<settlement>
<settleduedate>2012-10-08</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<acquirerresponsecode>00</acquirerresponsecode>
<operation>
<splitfinalnumber>1</splitfinalnumber>
<authmethod>PRE</authmethod>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>
Field specification
Field
Format
Description
accounttypedescription
XPath: /operation/accounttypedescriptionAlpha (20)
The type of account to be used:
authmethod
XPath: /operation/authmethodAlpha (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 here for further information.
credentialsonfile
XPath: /operation/credentialsonfileNumeric (1)
The allowed values for this field are 0, 1 and 2.
parenttransactionreference
XPath: /operation/parenttransactionreferenceAlphanumeric
& hyphens (25)The transactionreference of a previous request, from which key details have been inherited.
requesttypedescription
XPath: /@type
Alpha (20)
“AUTH” is returned in the response.
Field
Format
Description
baseamount
XPath: /billing/amountNumeric (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)
currencyiso3a
XPath: /billing/amount/@currencycodeAlpha (3)
The currency of the transaction. Click here for a full list of available currencies.
dccenabled
XPath: /billing/dcc/@enabled Numeric (1)
Indicates if your account is configured for DCC:
1= Yes
0 = No
issuer
XPath: /billing/payment/issuer Alphanumeric (255)
The customer’s card issuer.
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.
maskedpan
XPath: /billing/payment/pan Alphanumeric including “#” (12-19)
The customer’s card number. This is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
paymenttypedescription
XPath: /billing/payment/@typeAlpha (20)
Payment method (e.g. “VISA” or “MASTERCARD”).
Field
Format
Description
chargedescription
XPath: /merchant/chargedescriptionAlphanumeric including
symbols (25)This is a description of the payment that appears on the customer’s bank statement.
merchantnumber
XPath: /merchant/merchantnumber Alphanumeric (32)
The merchant number that was used to process the transaction. Provided by the acquiring bank.
merchantcategorycode
XPath: /merchant/merchantcategorycodeAlphanumeric (255)
These are details associated with the account used to process the transaction.To amend these fields, please contact our Support Team.
merchantcity
XPath: /merchant/merchantcityAlphanumeric (127)
merchantcountryiso2a
XPath: /merchant/merchantcountryiso2aAlpha (2)
merchantname
XPath: /merchant/merchantnameAlphanumeric (255)
merchantstatecode
XPath: /merchant/merchantstatecodeAlphanumeric (127)
merchantzipcode
XPath: /merchant/merchantzipcodeAlphanumeric (10)
operatorname
XPath: /merchant/operatornameAlphanumeric (255)
The value of this field contains the name of the user that processed the request.
orderreference
XPath: /merchant/orderreferenceAlphanumeric including
symbols (255)Your unique order reference that can be stored on the Trust Payments system.
tid
XPath: /merchant/tidAlphanumeric (255)
The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.
Field
Format
Description
settleduedate
XPath: /settlement/settleduedateDate YYYY-MM-DD
The date on which the transaction will be settled.
settlestatus
XPath: /settlement/settlestatusNumeric (3)
A numeric value used to indicate the progress of settlement regarding this transaction.
Field
Format
Description
acquireradvicecode
XPath: /acquireradvicecode Numeric (1)
A numeric value returned following a repeat payment request, indicating if further payments can be processed.
acquirerresponsecode
XPath: /acquirerresponsecode Alphanumeric (255)
Used by your acquirer to indicate the outcome of the request.
acquirerresponsemessage
XPath: /acquirerresponsemessageAlphanumeric (255)
authcode
XPath: /authcode Alphanumeric (255)
The authorisation code provided by the issuing bank. This will differ depending on which bank you use.
errorcode
XPath: /error/codeNumeric (1-5)
The error code should be used to determine if the request was successful or not.
errordata
XPath: /error/dataAlphanumeric (255)
Additional information to help troubleshoot the error.
errormessage
XPath: /error/messageAlphanumeric (255)
This provides a brief explanation as to the cause of the error.
livestatus
XPath: /live Numeric (1)
retrievalreferencenumber
XPath: /other/retrievalreferencenumberAlphanumeric (255)
An ISO term. This is used to reference the source transaction.
securityresponseaddress
XPath: /security/addressNumeric (1)
The result of AVS and Security Code Checks.
securityresponsepostcode
XPath: /security/postcodeNumeric (1)
securityresponsesecuritycode
XPath: /security/securitycodeNumeric (1)
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.
transactionstartedtimestamp
XPath: /timestampDate time YYYY-MM-DD hh:mm:ss
The time the transaction was processed.
Field
Format
Description
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.
secrand
Alphanumeric (16)
Random string of characters, returned in the response of non-API-based libraries developed by Trust Payments.
Transaction queriesStoring payment credentials for tokenization