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

This page is written for those processing Mail or Telephone Order (MOTO) payments, Merchant Initiated Transactions (MIT), or other advanced workflows that do not warrant 3-D Secure v2 being enabled.

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) will soon be mandated to use 3-D Secure when processing e-commerce transactions, as part of the PSD2 mandate.

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

ECOM (e-Commerce) Maestro transactions require the implementation of 3-D Secure in order to be processed successfully.

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

In order to reduce fraud, Visa has mandated that all UK-based merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in AUTH and ACCOUNTCHECK requests.

Failure to submit these fields may prevent the transaction from being processed successfully, with a “60025” errorcode being returned in the response.

Click here for further information.

AUTH request

Example

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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.

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 sitereference for your live sitereference.

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:

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The type of account to be used: “ECOM” – E-commerce “MOTO” – Mail or Telephone Order “RECUR” – Recurring transactions
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 here for further information.
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.
initiationreason XPath: /operation/initiationreason	Char (1)	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. Visa may introduce new values to this list in the future. Please refer to Visa’s own documentation for further information.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “AUTH”, as shown in the request example.
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.

Payment

The following fields contain the customer’s payment details:

Field	Format	Description
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)
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.
expirydate XPath: /billing/payment/expirydate	Date 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/@type	Alpha (20)	Payment method (e.g. “VISA” or “MASTERCARD”). Click here for a full list of different card-based payment types.
securitycode XPath: /billing/payment/securitycode	Numeric (3-4)	This is the three 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.

Merchant

The following fields relate to your account configuration and allow you to configure custom unique references for your request:

Field	Format	Description
chargedescription XPath: /merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the payment that appears on the customer’s bank statement. Only supported by certain acquiring banks. 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: + – _ . @ ( )
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/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).
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	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).

Billing

The following fields contain the customer’s billing details:

Field	Format	Description
billingpremise XPath: /billing/premise	Alphanumeric including symbols (25)	The house number or first line of the customer’s billing address.
billingstreet XPath: /billing/street	Alphanumeric including symbols (127)	The street entered for the customer’s billing address.
billingtown XPath: /billing/town	Alphanumeric including symbols (127)	The town entered for the customer’s billing address.
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”.
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.
billingpostcode XPath: /billing/postcode	Alphanumeric (25)	The postcode entered for the customer’s billing address. If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.
billingemail XPath: /billing/email	Email (255)	The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingtelephonetype XPath: /billing/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work
billingtelephone XPath: /billing/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
billingprefixname XPath: /billing/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname XPath: /billing/name/first	Alphanumeric including symbols (127)	The customer’s billing first name.
billingmiddlename XPath: /billing/name/middle	Alphanumeric including symbols (127)	The customer’s billing middle name(s).
billinglastname XPath: /billing/name/last	Alphanumeric including symbols (127)	The customer’s billing last name.
billingsuffixname XPath: /billing/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s billing name (e.g. Bsc).

Customer and delivery

The following fields contain the customer’s delivery details:

Field	Format	Description
customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The customer’s house name or number.
customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The customer’s street name.
customertown XPath: /customer/town	Alphanumeric including symbols (127)	The customer’s town.
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: Two character state code, e.g. “NY”. Full state name, e.g. “New York”.
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.
customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The customer’s postcode or ZIP code. If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.
customeremail XPath: /customer/email	Email (255)	The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
customertelephonetype XPath: /customer/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work
customertelephone XPath: /customer/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
customerprefixname XPath: /customer/name/prefix	Alphanumeric including symbols (25)	The customer’s prefix name (e.g. Mr, Miss, Dr).
customerfirstname XPath: /customer/name/first	Alphanumeric including symbols (127)	The customer’s first name.
customermiddlename XPath: /customer/name/middle	Alphanumeric including symbols (127)	The customer’s middle name(s).
customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The customer’s last name.
customersuffixname XPath: /customer/name/suffix	Alphanumeric including symbols (25)	The customer’s suffix name (e.g. Bsc).
customerforwardedip XPath: /customer/forwardedip	IP address (39)	Customer forwarded IP address, as provided by a proxy server if available.
customerip XPath: /customer/ip	IP address (39)	The IP of the customer.

Settlement

The following fields contain the Settlement details:

Field

Format

Description

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.

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 here for a full list of settlestatus values.

AUTH response

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

Python
PHP
Raw JSON
Raw XML

{
  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>

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.

Field specification

Operation

The following fields relate to the type of request submitted:

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The type of account to be used: “ECOM” – E-commerce. “MOTO” – Mail or Telephone Order “RECUR” – Recurring transactions
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 here for further information.
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.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & 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.

Billing

The following fields contain the customer’s billing details:

Field	Format	Description
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)
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (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/@type	Alpha (20)	Payment method (e.g. “VISA” or “MASTERCARD”). Click here for a full list of different card-based payment types.

Merchant

The following fields relate to your account configuration:

Field	Format	Description
chargedescription XPath: /merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the payment that appears on the customer’s bank statement. Only supported by certain acquiring banks. 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: + – _ . @ ( )
merchantnumber XPath: /merchant/merchantnumber	Alphanumeric (32)	The merchant number that was used to process the transaction. Provided by the acquiring bank.
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.
merchantcity XPath: /merchant/merchantcity	Alphanumeric (127)
merchantcountryiso2a XPath: /merchant/merchantcountryiso2a	Alpha (2)
merchantname XPath: /merchant/merchantname	Alphanumeric (255)
merchantstatecode XPath: /merchant/merchantstatecode	Alphanumeric (127)
merchantzipcode XPath: /merchant/merchantzipcode	Alphanumeric (10)
operatorname XPath: /merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	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).
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.

Settlement

The following fields contain the Settlement details:

Field

Format

Description

settleduedate
XPath: /settlement/settleduedate

Date YYYY-MM-DD

The date on which the transaction will be settled.

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.

Transaction status

The following fields returned in the response indicate the outcome of the request:

Field	Format	Description
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. (Help) 2 – Cannot approve at this time. (Help) 4 – Do not process further recurring transactions. 8 – Payment blocked by card scheme. (Help)
acquirerresponsecode XPath: /acquirerresponsecode	Alphanumeric (255)	Used by your acquirer to indicate the outcome of the request.
acquirerresponsemessage XPath: /acquirerresponsemessage	Alphanumeric (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/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.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error.
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.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
retrievalreferencenumber XPath: /other/retrievalreferencenumber	Alphanumeric (255)	An ISO term. This is used to reference the source transaction.
securityresponseaddress XPath: /security/address	Numeric (1)	The result of AVS and Security Code Checks. Click here to learn more.
securityresponsepostcode XPath: /security/postcode	Numeric (1)
securityresponsesecuritycode XPath: /security/securitycode	Numeric (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: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the transaction was processed.

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

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.

Tokenisation from previous request

To submit subsequent transactions with the same details, your system can process another AUTH request, and reference the previously-completed payment’s transactionreference, which is returned in the response. Submit this reference in the parenttransactionreference field of the new AUTH request, and the majority of fields (card details, billing address, delivery address, order reference, etc.) will be re-used when proceeding with the new payment. Please refer to the following example request:

Python
PHP
cURL
Raw JSON
Raw XML

#!/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",
  "parenttransactionreference": "23-9-80006"
}

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',
  'parenttransactionreference' => '23-9-80006'
);

$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",
  "parenttransactionreference": "23-9-80006"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","baseamount":"1050","orderreference":"My_Order_123","accounttypedescription":"ECOM","parenttransactionreference":"23-9-80006"}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>12-23-34</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

Account checks (API)Configuring your own library