Contents

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

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

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

PAYMENT MAESTRO
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.

Info
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:


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

 

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


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


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

 

DCC

DCC is a feature that allows customers to complete the payment in their currency or your local currency.
The amounts are calculated using a third-party conversion rate provider with up-to-date conversion rates.

 

 

Please select a topic:

Additional notes

 

Updating DCC authorisations

It is possible to perform updates on DCC payments prior to settlement, by submitting a TRANSACTIONUPDATE request.

It is not possible to change the currency of the payment after it has been authorised by the acquiring bank.

Warning
It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the dccexpirytimestamp (returned in the CURRENCYRATE response). Failing to do so (e.g. by updating the settlement date) may result in the customer paying the wrong amount and may invalidate your agreement with the conversion rate provider or acquirer.

 

Partial settlement

You can use a TRANSACTIONUPDATE request to update the settle amount of an authorised DCC payment. This can be used to settle a transaction for a lower value than was initially authorised. The remaining funds will be released by the card issuer once the authorisation code has expired (usually approx. 7 days).

The new settle amount is specified in the settlebaseamount field (this represents the amount in the customer’s currency). It must be lower than the total amount authorised in the customer’s currency.

If a partial settlement request has been processed and the customer has made the payment in the customer’s currency, the original conversion rate of the transaction is used to calculate the respective settle amount in the merchant’s currency.


#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
   },
   "updates":{"settlebaseamount":"960"}
}
   
strequest = securetrading.Request()
strequest.update(update)
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(
'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-3'))
),
'updates' => array('settlebaseamount' => '960')
);
 
$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": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlebaseamount":"960"}
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-3"}]},"updates":{"settlebaseamount":"960"}}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <transactionreference>1-2-3</transactionreference>
      <sitereference>test_site12345</sitereference>
    </filter>
    <updates>
      <settlement>
        <settlebaseamount>960</settlebaseamount>
      </settlement>
    </updates>
  </request>
</requestblock>

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

 

Using your own DCC provider

If preferred, you can perform your own currency conversion without performing a CURRENCYRATE request or refer to a pre-existing parent CURRENCYRATE request. To do this, submit an AUTH request (as outlined on this page), while ensuring all the required fields are submitted using valid conversion rate details from your DCC provider.

Warning
It is your responsibility to calculate the amounts based on the conversion rates from your DCC provider, and to ensure the amounts and currencies you submit in the AUTH request are valid.
URL
Receipt text

Select acquirers may require certain information to be displayed to the customer in a receipt, following a transaction, such as the conversion rate used and the name of the conversion rate provider. Please be sure to check with your acquiring bank that you are displaying all the information required.

 

Testing

 

Use the credentials provided on this page to test your solution.

When you sign up, you will be provided with a “live” account and a “test” account (the latter is prefixed with “test_”).
When testing, ensure requests submitted to Trust Payments reference your test sitereference.

Warning
It is important to thoroughly test your integration using your test sitereference before processing live payments.

Info

Before you begin testing…

Please be aware of the following notes:

 

  • Most fields submitted to our test system will be accepted. Any data breaching its defined specification will return an error message.
  • Any test data that generates a successful response when submitted while a merchant is in test mode, will produce a declined response when a merchant is switched into live mode. In some cases, the test data may return an error response.
  • Our test system attempts to simulate responses in a similar fashion to the live system. However, depending on your acquirer you may find some responses differ slightly from those given by the test system.
  • In the interest of security, we recommend against using real payment details when using your test account.
  • We recommend specifying the main amount “10.50” when testing. Other amounts can be used but may return unexpected responses.

 


 

Test card details

The table below lists test card numbers and customer information that can be submitted to our test bank, along with the responses that should be expected in return.

Warning
Do not use these credentials when processing transactions on your live site reference.
Info
While testing, all card types are supported, but when using your live account, you will receive an error if you do not have a valid merchant number for the payment type submitted.

 

 

3-D Secure v2

The following payment credentials can be used for testing 3-D Secure v2 (a form of SCA):

 

Test case Visa Mastercard American Express
Success frictionless 4000000000001026 5200000000001005 340000000001007
Success step-up 4000000000001091 5200000000001096 340000000001098
Failed frictionless 4000000000001018 5200000000001013 340000000001015
Failed step-up 4000000000001109 5200000000001104 340000000001106
Declined 4242424242424242 5100000000000412 300000000000512

 

3-D Secure v1

The following payment credentials can be used for testing 3-D Secure v1 (a form of SCA):

 

Visa-branded cards

Visa
Credit Debit V Pay Electron Purchasing
Enrolled (Y) 4111110000000211 4006260000002473 4370000000000111 4245190000000311 4484000000000411
Not enrolled (N) 4111110000000021 4006260000002481 4370000000000921 4245190000000121 4484000000000221
Unknown enrollment (U) 4111110000000401 4006260000002408 4370000000002307 4245190000000501 4484000000000601

 

Mastercard-branded cards

Test case Mastercard
Credit Debit Maestro (Intl.) Maestro (UK)
Enrolled (Y) 5100000000000511

2221000000000611

5124990000000911 5000000000000611 6759000000000711
Not enrolled (N) 5100000000000321

2221000000000991

5124990000000721 5000000000000421 6759000000000521
Unknown enrollment (U) 5100000000000701

2221000000000801

5124990000000101 5000000000000801 6759000000000901

 

3-D Secure status testing

To test for different 3-D Secure status values, follow the instructions displayed in the authentication prompt shown on the page (an example is shown below). In the textbox provided, you can enter different PIN values to test for different cases.

URL
Displaying the test ACS page

 

For Payment Pages:

With 3-D Secure enabled on your site reference, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions.

 

For JavaScript library implementations:

After your payment form has been updated to reference our JavaScript library, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions.

 

The authentication prompt will only be displayed for non-frictionless test card details.

Frictionless cards will bypass authentication. In this case, the payment will be processed immediately (without being prompted by the browser for information).

 


 

Follow the instructions displayed within the authentication prompt to complete the payment:

 

 

 

Non 3-D Secure

The following card types are not currently processed using 3-D Secure (a form of SCA):

 

Card type Authorisation Decline Expiry date Security code
DINERS 3000000000000111 3000000000000012 12/2030 123
DISCOVER 6011000000000301 6011000000000202 12/2030 123
JCB 3528000000000411 3528000000000312 12/2030 123

 

After the payment has been processed, the error code and status values stored with the processed AUTH are used to convey the final outcome.

Info
When the status is “N”, indicating the customer failed authentication, the errorcode “60022” will be returned.

 


 

Testing AVS and security code checks

If you haven’t already, please read our AVS and Security code documentation before testing:
Link to Payment Pages docs / Link to API docs

The following tables list test details that can be submitted to obtain different responses from the AVS and Security Code Checks. These details can be used with most major payment types.

Info
Only the billing premise, billing postcode and security code field values dictate the outcome of the AVS and security code checks performed. As such, entering any details into the other address fields will not affect the outcome of these checks.

 

Premise

Billing premise Security response Security response caption
No 789 2 Matched
No 123 4 Not Matched
No 333 1 Not Checked
Leave blank 0 Not Given

 

Postcode / ZIP code

Billing postcode Security response Security response caption
UK US
TE45 6ST 55555 2 Matched
TE12 3ST 12345 4 Not Matched
TE33 3ST 33333 1 Not Checked
Leave blank Leave blank 0 Not Given

 

Security code

Security code AMEX security code Security response Security response
123 1234 2 Matched
214 2144 4 Not Matched
333 3333 1 Not Checked
Leave blank Leave blank 0 Not Given

 

 


 

Testing non-card payment methods

URL
The procedure to follow when testing non-card payment methods will vary. For the most relevant testing information, please refer to the documentation provided for the specific payment method:
Link to Payment Pages docs / Link to API docs

 


 

Testing recurring payments

Testing for the acquirer advice code

When processing recurring payments, some acquirers may return an acquirer advice code in the response. The acquirer advice code is a numeric value used to indicate if further recurring payments can be processed for the given card.

Code Description Action
0 N/A No action required
1 New account information available (Mastercard only) Query customer for updated payment details
2 Cannot approve at this time Try again later. If you are continuing to have difficulties, please contact your acquiring bank
4 Do not try again Do not process further recurring transactions
8 Payment blocked by card scheme

 

Where to find the acquirer advice code

 

How to test for different acquirer advice codes

You can test that your system responds appropriately to different acquirer advice codes by processing transactions with the following attributes:

Visa
Acquirer advice code returned Card number Base amount
0 4111111111111111 1050
2 4000000000000671 1002
4 4000000000000671 1004
8 4000000000000671 1008

 

PAYMENT MASTERCARD
Acquirer advice code ‘1’ can only be returned for recurring Mastercard transactions.
Mastercard
Acquirer advice code returned Card number Base amount
0 5100000000000511 1050
1 5100000000000271 1001
2 5100000000000271 1002
4 5100000000000271 1004
8 5100000000000271 1008

 


 

Testing Protect Plus

If you haven’t already, please read our Protect Plus document before testing:
Link to Payment Pages docs / Link to API docs

Use the following baseamount values in RISKDEC requests to simulate the different possible responses from the Protect Plus checks:

baseamount Possible fraudcontrolresponsecode returned fraudcontrolshieldstatuscode returned
1011, 2011, 3011 0100, 0150 “ACCEPT”
1033, 2033, 3033 0300, 0330, 0500 “CHALLENGE”
1044, 2044, 3044 0250, 0400, 0600, 0700, 0800, 1300 “DENY”

 

Info
The fraudcontrolshieldstatuscode and fraudcontrolresponsecode values returned in RISKDEC responses may vary when not using the baseamount values listed in the table, above.

 


 

Testing DCC

If you haven’t already, please read our DCC document before testing:
Link to Payment Pages docs / Link to API docs

The card numbers listed in this test section are associated with specific local currencies. During your integration, you can use the following international test card details in order to test your system for successful and declined DCC transactions.

Successful authorisations

Country code Currency code Visa Credit Mastercard Credit
DE EUR 4500000000000007 5500000000000004
GB GBP 4300000000002211 5311110000001511
JP JPY 4900400000000005 5590410000000006
US USD 4900460000000009 5590470000000018

Declined authorisations

Country code Currency code Visa Credit Mastercard Credit
DE EUR 4500000000002482 5500000000002422
GB GBP 4300000000002492 5311110000002402
JP JPY 4900400000002472 5590410000002432
US USD 4900460000002492 5590470000002402

 

Info
You can also use an amount of 70000 in the final currency to generate a decline response.

 

Settlement

 

Info
The following procedure applies to card-based payment methods. Please be aware that the settlement process for certain APMs (Alternative Payment Methods) may deviate from the below. For this reason it is important that you read the relevant documentation when adding APMs to your solution.

 

Once a transaction has been authorised, the funds are then reserved against the customer’s account for 7 days. The instruction to transfer the funds is scheduled daily when we submit a batch of all pending transactions to your acquirer.

 

This process is called settlement and is outlined below:

1
The initial phase of the settlement process occurs when we submit a file to your acquirer. The file contains all transactions that are in status ‘pending settlement’, and this occurs daily.
2
When your acquirer has received the settlement file, they commence the process of physically settling the money into your nominated bank account. The time frame of this payment differs between banks, and is not determined by Trust Payments. If reserved funds are not settled, they are released back onto the customer’s card. We recommend that you regularly sign in to MyST to check the status of your payments.

 

Deferred settlement

Settlement can be deferred for certain transactions. You can request this by modifying the payment request, or transactions may be deferred by our internal fraud system. You should therefore sign in to MyST on a regular basis, to check the status of your transactions.

 

Settle status

Settle status 0

Settle status 0 – Pending settlement

Transaction that has been authorised by card issuer for payment.

  • Settles automatically.
  • Can be updated or cancelled.
  • Does not currently require action from the merchant.
  • May be suspended by future Fraud checks and Duplicate checks, if enabled.
Settle status 1

Settle status 1 – Pending settlement (manual override)

Transaction that has been authorised by card issuer for payment.

  • Settles automatically.
  • Can be updated or cancelled.
  • Does not require further action from merchant.
  • Bypasses fraud and duplicate checks, if enabled.
Settle status 10

Settle status 10 – Settling

Details of this transaction have been sent to the acquiring bank for settlement.

  • Does not require further action from merchant.
  • Settles automatically.
  • Cannot be updated or cancelled.
Settle status 100

Settle status 100 – Settled

Transaction has been settled into the merchant’s account.

  • Does not require further action from merchant.
  • Cannot be updated or cancelled.
  • Can be refunded (unless all funds have already been refunded).
Settle status 2
Settle status 2 – Suspended

Transaction has been suspended, and will not settle without action from the merchant.

  • Transactions can be suspended by merchants to prevent settlement, allowing for manual investigation.
  • Transactions can be suspended by Trust Payments if fraud or duplicate checks (if enabled) raise an issue.
  • If left in a suspended state for 7 days after the authorisation date, the transaction will be cancelled automatically (updated to settle status ‘3’). This limit is extended to 31 days for pre-authorisations.
  • The merchant can update transactions in settle status ‘2’ to the following states:
    ‘0’ – Allows settlement to occur, providing the transaction passes fraud checks.
    ‘1’ – Allows settlement to occur, bypassing fraud checks.
    ‘3’ – Manually cancels the transaction.
Settle status 3

Settle status 3 – Cancelled

Transaction has been cancelled and will not settle.

  • This can be due to an error or due to the transaction being declined.
  • If a transaction is left in a suspended state (settle status ‘2’) for 7 days after the authorisation date, the transaction will be cancelled automatically. This limit is extended to 31 days for pre-authorisations.
  • Merchants can also manually update transactions to settle status to ‘3’ to cancel them.
  • Cancelled transactions cannot be updated.

 


 

Additional resources

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116