Contents

Authorisations

To process a payment with us, you will need to process an AUTH request.

 

Process overview

 

 

Requirements

Warning
Most acquiring banks mandate that 3-D Secure is performed prior to AUTH requests.

Click here for further information.

 

Please note that if 3-D Secure is not implemented, you could be liable for fines from the card schemes.

Info
In order to reduce fraud, Visa has mandated that all merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in AUTH and ACCOUNTCHECK requests, if provided by the customer making the payment.

 

Failure to submit these fields will result in a “60025” errorcode being returned in the response.

Click here for further information.

 

AUTH request

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",
  "cachetoken": "token_posted_by_st.js"
}

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',
  'cachetoken' => 'token_posted_by_st.js'
);

$api = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/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",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

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.

 

AUTH response

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


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'responses': [{
      u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        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"
  ["responses"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 09:52:19"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["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": "SecureTrading Test Issuer1",
    "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"
}

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

 

Field specification

Info
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

Key

 

Operation fields

The following fields relate to the type of request submitted:

Field name Type Length Request Response Description
requesttypedescriptions Alpha 20  * You must submit “AUTH”, as shown in the request example.

*In the response, the field ‘requesttypedescription’ is returned instead e.g. “requesttypedescription”:”AUTH”

sitereference Alphanumeric including
underscore
50 The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.
accounttypedescription Alpha 20 The source of the transaction.

  • For an e-commerce AUTH Request, the value should be “ECOM”.
  • For Mail Order or Telephone Order (MOTO) requests, the value should be “MOTO”.
  • For a recurring transaction, the value should be “RECUR”.
parenttransactionreference Alphanumeric including hyphens 25 Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
authmethod Alpha 5 Either “PRE” or “FINAL”.
Click here for further information.
livestatus Numeric 1
  • “0” – Transaction processed on test site.
  • “1” – Transaction processed on live site.
secrand Alphanumeric 16 Random string of characters, returned in the response of non-API-based libraries developed by Secure Trading.

 

Payment details

The following fields contain the customer’s payment details:

Field name Type Length Request Response Description
currencyiso3a Alpha 3 The currency that the transaction will be processed in.

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.

baseamount 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)
cachetoken Alphanumeric including hyphen Variable This contains a reference to the customer’s payment details. This is the value posted to your servers after the customer has entered their payment details into your HTML form and clicked “Submit”.
paymenttypedescription Alpha 20 Payment method (e.g. “VISA” or “MASTERCARD”). Click here for a full list of payment types.
maskedpan 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.
dccenabled Numeric 1 Indicates if your account is configured for DCC:
1= Yes
0 = No
issuer Alphanumeric 255 The customer’s card issuer.
issuercountryiso2a 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.

 

Merchant details

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

Field name Type Length Request Response Description
merchantemail Email 255 The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
orderreference Alphanumeric including
symbols
255 Your unique order reference that can be stored on Secure Trading’s system.

Note: This can be updated at a later time (only if transaction is pending settlement).

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 Alphanumeric 32 The merchant number that was used to process the transaction. Provided by the acquiring bank.
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.
merchantcategorycode Alphanumeric 255 These are details associated with the account used to process the transaction.

To amend these fields, please contact our Support team.

merchantname Alphanumeric 255
merchantcity Alphanumeric 127
merchantstatecode Alphanumeric 127
merchantzipcode Alphanumeric 10
merchantcountryiso2a Alpha 2
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).

 

Billing address and contact

The following fields contain the customer’s billing details:

Field name Type Length Request Response Description
billingpremise Alphanumeric including
symbols
25 The house number or first line of the customer’s billing address.
billingstreet Alphanumeric including
symbols
127 The street entered for the customer’s billing address.
billingtown Alphanumeric including
symbols
127 The town entered for the customer’s billing address.
billingcounty 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 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 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 Email 255 The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingtelephonetype Char 1 The type of telephone number. The options available are:

  • H = Home
  • M = Mobile
  • W = Work
billingtelephone Alphanumeric including
symbols
20 The customer’s telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
billingprefixname Alphanumeric including
symbols
25 The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname 127 The customer’s billing first name.
billingmiddlename 127 The customer’s billing middle name(s).
billinglastname 127 The customer’s billing last name.
billingsuffixname 25 The suffix of the customer’s billing name (e.g. Bsc).

 

 

Customer and delivery details

The following fields contain the customer’s delivery details:

Field name Type Length Request Response Description
customerpremise Alphanumeric including
symbols
25 The customer’s house name or number.
customerstreet Alphanumeric including
symbols
127 The customer’s street name.
customertown Alphanumeric including
symbols
127 The customer’s town.
customercounty 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 Alpha 2 The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerpostcode 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 Email 255 The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
customertelephonetype Char 1 The type of telephone number. The options available are:

  • H = Home
  • M = Mobile
  • W = Work
customertelephone Alphanumeric including
symbols
 20   The customer’s telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
customerprefixname Alphanumeric including
symbols
25 The customer’s prefix name (e.g. Mr, Miss, Dr).
customerfirstname 127 The customer’s first name.
customermiddlename 127 The customer’s middle name(s).
customerlastname 127 The customer’s last name.
customersuffixname 25 The customer’s suffix name (e.g. Bsc).
customerforwardedip IP address 39 Customer forwarded IP address, as provided by a proxy server if available.
customerip 39 The IP of the customer.

 

Settlement fields

The following fields contain the Settlement details:

Field name Type Length Request Response Description
settleduedate Date YYYY-MM-DD 10 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. This date is returned in the response.
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.

 

Transaction status fields

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

Field name Type Length Request Response Description
errorcode 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.

errormessage Alphanumeric 255 This is the corresponding message to the above code.

Click here for a full list of errorcode and message values.

errordata Alphanumeric 255 Additional information to help troubleshoot the error.
securityresponseaddress Numeric  1 The result of AVS and Security Code Checks.

Click here to learn more.

securityresponsepostcode Numeric  1
securityresponsesecuritycode Numeric  1
authcode Alphanumeric 255 The authorisation code provided by the issuing bank. This will differ depending on which bank you use.
transactionstartedtimestamp Date time YYYY-MM-DD hh:mm:ss 19 The time the transaction was processed.
live Numeric 1
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
transactionreference Alphanumeric including
hyphens
25 A unique reference for the transaction assigned by Secure Trading. You will need this reference to perform a refund or update the transaction.
acquirerresponsecode Alphanumeric 255 Used by your acquirer to indicate the outcome of the request.
acquirerresponsemessage Alphanumeric 255
retrievalreferencenumber Alphanumeric 255 An ISO term. This is used to reference the source transaction.

 

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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/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"
}]}'