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.

 

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

3-D Secure (version 1)

 

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.

 

The following documentation explains how to manually perform 3-D Secure using version 1 through our Webservices API.

The process described below only supports 3-D Secure version 1.
We recommend all merchants utilise 3-D Secure version 2 by using our JavaScript Library.

If you are already processing e-commerce payments using our JavaScript Library, you do not need to follow the process described below, as the JavaScript Library will handle the 3-D Secure process automatically.

 


 

3-D Secure is a protocol designed to reduce fraud and chargebacks during e-commerce transactions. It allows Mastercard and Visa card issuers to provide an extra level of protection, by authenticating the customer’s identity at the point of sale, sometimes by prompting for a previously-agreed PIN and/or password.

Info
For a fully authenticated 3-D Secure transaction, in the event of a dispute at a later date the card issuer will usually take responsibility of the chargeback instead of the merchant. The liability issues involved with 3-D Secure transactions can be found in this FAQ.
.

 

Process overview

1
Check customer enrolment

  • Your system will need to send a THREEDQUERY request using our Webservices API (including the customer’s card details) and interpret the response returned.
  • Trust Payments will check whether the customer’s card is enrolled in 3-D Secure.
2
Authenticate the customer

If the customer is enrolled in 3-D Secure, your system will need to redirect the customer to the card issuer’s server (ACS URL) and handle the customer being redirected to your server (Term URL).

3
Authorisation

Your system will need to send an AUTH request using our Webservices API and interpret the response returned.

 


 

1. Check customer enrolment

To determine whether or not the customer’s card is enrolled in the 3-D Secure scheme, you need to manually submit a THREEDQUERY request using our Webservices API.

 

THREEDQUERY Request

The following example demonstrates how to structure a THREEDQUERY request:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

threedquery= {
  "termurl":"https://termurl.com",
  "accept":"text/html,*/*",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "currencyiso3a":"GBP",
  "requesttypedescriptions": ["THREEDQUERY"],
  "accounttypedescription":"ECOM",
  "sitereference": "test_site12345",
  "baseamount": "1050"
}

strequest = securetrading.Request()
strequest.update(threedquery)
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(
  'termurl' => 'https://termurl.com',
  'accept' => 'text/html,*/*',
  'pan' => '4111111111111111',
  'expirydate' => '12/2020',
  'securitycode' => '123',
  'currencyiso3a' => 'GBP',
  'requesttypedescriptions' => array('THREEDQUERY'),
  'accounttypedescription' => 'ECOM',
  'sitereference' => 'test_site12345',
  'baseamount' => '1050'
);

$api = \Securetrading\api($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": [{
  "termurl":"https://termurl.com",
  "accept":"text/html,*/*",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "currencyiso3a":"GBP",
  "requesttypedescriptions": ["THREEDQUERY"],
  "accounttypedescription":"ECOM",
  "sitereference": "test_site12345",
  "baseamount": "1050"
}]}'

 

Here is the specification of the fields included in the THREEDQUERY request described above:

Info
When reading the field specifications included on this page, please ensure that you reference the relevant code examples for your chosen language.

 

Key

Field name Type Length Request Description
accept Alphanumeric 1024 The exact content of the HTTP accept-header field as received from the cardholder’s user agent.
accounttypedescription Alpha 20 This must be submitted as “ECOM” (e-commerce).
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)
currencyiso3a Alpha 3 The currency that the transaction will be processed in.

Click here for a full list of available currencies.

expirydate Date MM/YYYY 7 The expiration date printed on the card.
pan
Numeric 12-19 This is the long number printed on the front of the customer’s card.

We return a masked version of this PAN in the response, in the field maskedpan. e.g. “411111######1111”

requesttypedescriptions Alpha 20 The request type required is “THREEDQUERY”.
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 field 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.
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.
termurl URL 1024

More info

  This field value is a URL of a script/file located on your system that is able to manage customers who are returned to your system. It is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS.
useragent Alphanumeric 255 The exact content of the HTTP user-agent header field as received from the cardholder’s user agent. We strongly recommend you submit this field, as failure to do so may forfeit the liability shift.

 

THREEDQUERY Response

This section documents how to interpret a THREEDQUERY response, which is used to indicate whether or not the customer’s card is enrolled in the card issuer’s 3-D Secure scheme.

Info
The acsurl, md and pareq fields are only returned in a THREEDQUERY response for enrolled cards.

 

The example below demonstrates the structure of a THREEDQUERY response, indicating that the customer’s card is enrolled in a 3-D Secure scheme:


{
  u 'requestreference': u 'Aw5mpjtv6',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:55:47',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'xid': u 'amh1OCtINGpuemJaVmQreU5YT2Y=',
        u 'pareq': u 'eJxVUmFPw9C12xiQowlCopiIqGji5Yqj25lPCwOutoQKHZzxqOQgF5soqzk=',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'threedversion': u '1.0.2',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345678',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'acsurl': u 'https://webapp.securetrading.net/acs/visa.cgi',
        u 'accounttypedescription': u 'ECOM',
        u 'requesttypedescription': u 'THREEDQUERY',
        u 'md': u 'UEZOVVBqeE5SRDQ4VFVSSVBucE9abUp5WWtTlDR0NLaFVSZUV5aStFPQ==',
        u 'maskedpan': u '411111######0211',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'enrolled': u 'Y',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A2cjnruwy"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(25) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:25:36"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["xid"] => string(28) "ZlcyU1hQcUhmaEtzd2I1SmkrMnM="
      ["pareq"] => string(27) "eJxVUstuwjAQ/BXEHZxjoOrXA=="
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["threedversion"] => string(5) "1.0.2"
      ["tid"] => string(8) 27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["transactionreference"] => string(10) "1-2-345678"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["acsurl"] => string(45) "https://webapp.securetrading.net/acs/visa.cgi"
      ["accounttypedescription"] => string(4) "ECOM"
      ["requesttypedescription"] => string(11) "THREEDQUERY"
      ["md"] => string(72) "UEZOVVBqeVQand2VTFRKzptZGY2RXZXOGQrS2V5Tko5cEk9"
      ["maskedpan"] => string(16) "411111######0211"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["enrolled"] => string(1) "Y"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-08yvq0db","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:57:44","livestatus":"0","issuer":"SecureTrading Test Issuer1","xid":"KzRLRmhSUEZ0OWZJSkJIMDU1dDk=","pareq":"eJxVUu9PwjAQ\/NtY9ts6tP8Ac1Rqq+","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","threedversion":"1.0.2","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345678","merchantname":"Test Merchant","paymenttypedescription":"VISA","acsurl":"https:\/\/webapp.securetrading.net\/acs\/visa.cgi","accounttypedescription":"ECOM","requesttypedescription":"THREEDQUERY","md":"UEZOVVBqeE5SRD06bWRzS1dBbnFZY01JRjEwZGOWhrPQ==","maskedpan":"411111######0211","errormessage":"Ok","operatorname":"[email protected]","enrolled":"Y","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"0gqEPDTnCWlvTr6G"}

Info
The md and pareq typically contain values far longer than displayed in the example above and therefore have been abbreviated, for your convenience.

 

Check the error code field value

If the errorcode value returned in the response is not ‘0’, an error has occurred. If an errorcode other than ‘0’ is returned, please consult the table below and attempt to resolve the issue:

Error code Description
0 Request was successful.
30000 Invalid field.
60031 The THREEDQUERY request used a payment type that is not supported by Trust Payments 3-D Secure.
other Other errors will require further investigation. Click here for a full list of possible error codes.

 

If you were unable to resolve the issue, you can instruct your system to perform a standard AUTH without using 3-D Secure.

Warning
When performing an AUTH request without 3-D Secure, this will result in forfeiting the liability shift.

 

Check the enrolled field value

If the enrolled value returned in the response is “Y”, the customer’s card is enrolled in 3-D secure. Please refer to the following table for enrolled values:

Enrolled Description Action
Y The card is enrolled in the card issuer’s 3-D Secure scheme. Send the customer to the card issuer’s Access Control Server (ACS). The URL for the ACS is provided in the acsurl of the THREEDQUERY response.
N The card is not enrolled in the card issuer’s 3-D Secure scheme. Perform an AUTH Request, including the transactionreference returned in the THREEDQUERY response (example can be found below).
U The card’s enrolment in the card issuer’s 3-D Secure scheme could not be determined. This typically indicates a temporary problem with the card issuer’s systems. You can configure your system to resubmit the same THREEDQUERY request. If this continues to fail, submit a standard AUTH request using our Webservices API, including the transactionreference returned in the THREEDQUERY response.

 

Here is the specification of the fields included in the THREEDQUERY response described above:

 

Key

Field name Type Length Response Description
requesttypedescription Alpha 20 “THREEDQUERY” is always returned in the response.
xid Alphanumeric 255 The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments).
enrolled Char 1 Determines if the cardholder is enrolled in a 3-D Secure scheme.

  • “Y” – Card is enrolled.
  • “N” – Card is not enrolled.
  • “U” – Unable to determine if card is enrolled.
pareq Alphanumeric including symbols 2048 The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments).
md Alphanumeric including symbols 1024 Returned if card is enrolled.

The unique 3-D Secure reference for this transaction.

acsurl URL 1024 Returned if card is enrolled.

The URL of the Access Control Server (ACS) to be used in authenticating the cardholder.

threedversion Numeric 6 Only returned for accounts with certain acquiring banks.

The version of the 3-D Secure protocol.

 


 

Your progress

Following the instructions above, your system should now be able to determine whether or not a customer’s card is enrolled in a 3-D Secure scheme. If the customer’s card is enrolled, follow the “Authenticate the customer” section below, otherwise skip ahead to the “Authorisation” section.

 


 

2. Authenticate the customer

 

Info
Only attempt to authenticate the customer if their card is confirmed to be enrolled in a 3-D Secure scheme.

 

If the card is not enrolled, skip ahead to the “Authorisation” section.

 

If the customer is enrolled in the card issuer’s 3-D Secure scheme, your system must send the customer’s browser to the card issuer-hosted Access Control Server (ACS) using an HTTPS POST. The URL for the ACS can be found in the acsurl field of the THREEDQUERY response.

On the ACS, the customer will be authenticated, sometimes by prompting for a previously-agreed PIN and/or password. The browser must send data from the termurl, pareq and md in HTML fields ‘TermUrl’, ‘PaReq’ and ‘MD’, respectively (These field names are case sensitive).

 

URL
The size of the ACS page displayed in the customer’s browser is controlled by the ACS provider (cannot be modified by merchants or Trust Payments). As a guideline, Visa and Mastercard both state that the Verified by Visa authentication window should be 390×400 pixels in size

 

Following authentication, the customer will be returned to your servers using an HTTPS POST. You will need to parse this response, as it will contain the ‘PaRes’ and ‘MD’ fields, for constructing the subsequent AUTH Request needed to process the payment.

 

Warning
When the customer’s browser is redirected to your server from the ACS, please be aware that some ACS will also include a field called “realPan”, which contains the customer’s card number in plain text. It is imperative that you do not store the value of realPan on your own server.

 

The following is an example of how to redirect the cardholder to the card issuer’s ACS :


<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01//EN'>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>Processing payment</title>
<style type="text/css">
  h3,h3,h4 { font-family: verdana, arial, sans-serif;
          font-weight: normal;}
  #logo {float: left;}
</style>
</head>
<body OnLoad="document.form.submit();" >
<form name="form" id="form" action="$acsurl" method="POST">
<div>
<input type="hidden" name="PaReq" value="$pareq" />
<input type="hidden" name="TermUrl" value="$termurl" />
<input type="hidden" name="MD" value="$md" />
</div>
<noscript>
<div>
<h3>JavaScript is currently disabled or is not supported by your browser.</h3>
<h4>Please click Submit to continue processing your 3-D Secure transaction.</h4>
<input type="submit" value="Submit">
</div>
</noscript>
</form>
</body>
</html>

 

Referencing 3-D Secure transactions

In most circumstances, your system will need to store data about the transaction in your database while the customer is being authenticated on the card issuer’s ACS, to be retrieved when the customer returns to your system via the termurl. As the 3-D Secure specification requires that only the md and pares fields are returned to your system, it is recommended that the md field is used to look up any corresponding customer session to complete the transaction.

 

Waiting for the customer to return from the ACS

Your system will need to consider the length of time it may take for the customer to enter their details on the card issuer’s ACS. The time the customer will spend on the ACS will depend on a number of factors. Longer wait times may occur when the customer is signing up to a 3-D Secure scheme for the first time, or recovering a forgotten password. While your system needs to allow time for the customer to return, it is entirely possible for the customer to close their browser on the card issuer’s ACS and not return at all. There are no specific regulations as to how long your system must wait for the customer to be redirected from the ACS to your Term URL, but we recommend waiting for no more than two hours.

 

 


Your progress

Following the instructions above, your system should now be able to redirect the browsers of customers with cards enrolled in a 3-D Secure scheme to the ACS for authentication. Your system can now proceed and submit an AUTH request using our Webservices API to process the payment, by following the instructions below.

 


 

3. Authorisation

3-D authorisations are used to seek authorisation for authenticated transactions from your acquiring bank. This is performed by manually submitting an AUTH Request using our Webservices API and interpreting the response returned.

 

AUTH Request

For enrolled cards only

The following example demonstrates how to structure a 3-D AUTH request when the card is enrolled in a 3-D Secure scheme:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth= {
  "requesttypedescriptions": ["AUTH"],
  "md":"UEZOVVBqeE5SRDQ4VFVSSVBrRjVXSGhOZFZReVUzVlalBVeE",
  "pares":"eJzVWFmzosgSfudXdPQ8Gt1sbkzYRhQ7KCjI/sYOsimgoL/+lp7Tp5"
}

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(
'requesttypedescriptions' => array('AUTH'),
'md' => 'UEZOVVBqeE5SRDQ4VFVSSVBtSllOVTlMYVdaUlJXWnZVRTA0UVdwVlJXZFpRo5cEk9',
'pares' => 'eJztWEnTqsi2nfMrKqqGxik6UajwJFCOxLb5BNvgHdPneIihB/fq2eNv777/BdaScGg='
);

$api = \Securetrading\api($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": [{
  "requesttypedescriptions": ["AUTH"],
  "md":"UEZOVVBqeE5SRDVS1FLVG9aenQrRGhaNk1NPQ==",
  "pares":"eJztWMmyq7iynfMVFVVDxyk6Y0OX0U1wTQ=="
}]}'

Info
The md and pares fields typically contain values far longer than displayed in the example above and therefore have been abbreviated for your convenience. When submitting these fields, your system must submit their full values, unmodified.

 

For non-enrolled cards only

For cards that are NOT enrolled in the card issuer’s 3-D Secure scheme (or have unknown enrolment), you will need to submit the following fields in order to inherit transaction information needed to perform the authorisation:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth= {
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678"
}

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(
'requesttypedescriptions' => array('AUTH'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678'
);

$api = \Securetrading\api($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": [{
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678"
}]}'

Inheritance

 

The example AUTH requests shown above (both enrolled and not-enrolled) contain all the fields that are required for submission. All other information required to seek authorisation will be inherited from the previous THREEDQUERY request stored on our system.

 

We allow the submission of additional fields in the AUTH request that have not been submitted in the THREEDQUERY request (e.g. the customer name, if omitted in the query).

 

Click here for a full list of fields that can be submitted in an AUTH request.

 

Here is the specification of the fields included in the AUTH requests described above:

 

Key

Field name Type Length Request Description
pares Alphanumeric including symbols 1024 Only send if card is enrolled.

Must be the value returned in the pares field of the HTTPS POST from the card issuer’s ACS, otherwise this may forfeit the liability shift.

md Alphanumeric including symbols 65536 Only send if card is enrolled.

The unique 3-D Secure reference for this transaction. Supplied if enrolled is “Y”

parenttransactionreference Alphanumeric including hyphens 25 Only send if card is NOT enrolled.

Unique reference of the parent THREEDQUERY request.

sitereference Alphanumeric including underscore 50 Only send if card is NOT enrolled.

The site reference processing the transaction.

 

AUTH Response

The data returned in the AUTH response will depend on both the card enrollment status,  and whether or not the customer was successfully authenticated on the card issuer’s ACS.

Your system should be able to interpret the response data in each of the following scenarios.

 

Enrolled and authenticated


{
  u 'requestreference': u 'Av87m7xq9',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-08 08:34:48',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'xid': u 'amh1OCtINGpuemJaVmQreU5YT2Y=',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'cavv': u 'Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'status': u 'Y',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'eci': u '05',
        u 'accounttypedescription': u 'ECOM',
        u 'tid': u '27882788',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST40',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'maskedpan': u '411111######0211',
        u 'securityresponsepostcode': u '0',
        u 'enrolled': u 'Y',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A278afgrx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(33) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:46:34"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["splitfinalnumber"] => string(1) "1"
      ["xid"] => string(28) "ZlcyU1hQcUhmaEtzd2I1SmkrMnM="
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["status"] => string(1) "Y"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["enrolled"] => string(1) "Y"
      ["eci"] => string(2) "05"
      ["accounttypedescription"] => string(4) "ECOM"
      ["cavv"] => string(28) "Q0FWVkNBVlZDQVZWQ0FWVkNBVlY="
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST30"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["securityresponsepostcode"] => string(1) "0"
      ["maskedpan"] => string(16) "411111######0211"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-n68rw97k","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:21:59","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","xid":"ZldiREFPMW5HYi90UDhxMDJTV2Q=","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","status":"Y","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"1050","enrolled":"Y","eci":"05","accounttypedescription":"ECOM","cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST05","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######0211","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"bsZP"}

 

Enrolled but NOT authenticated


{
  u 'requestreference': u 'Aq2qmp0j3',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-13 11:11:58',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-13',
        u 'errorcode': u '60022',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'status': u 'N',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'accounttypedescription': u 'ECOM',
        u 'requesttypedescription': u 'AUTH',
        u 'currencyiso3a': u 'GBP',
        u 'maskedpan': u '411111######0211',
        u 'errormessage': u 'Unauthenticated',
        u 'operatorname': u '[email protected]',
        u 'enrolled': u 'Y',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '3'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A35ahjnwx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(25) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-13 10:41:57"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-13"
      ["errorcode"] => string(5) "60022"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["status"] => string(1) "N"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(3) "1050"
      ["accounttypedescription"] => string(4) "ECOM"
      ["requesttypedescription"] => string(4) "AUTH"
      ["currencyiso3a"] => string(3) "GBP"
      ["maskedpan"] => string(16) "411111######0211"
      ["errormessage"] => string(15) "Unauthenticated"
      ["operatorname"] => string(23) "[email protected]"
      ["enrolled"] => string(1) "Y"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "3"
    }
  }
}
{
  "requestreference": "W23-mjuwx1f5",
  "version": "1.00",
  "response": [{
    "transactionstartedtimestamp": "2016-12-13 11:00:44",
    "parenttransactionreference": "1-2-345678",
    "livestatus": "0",
    "issuer": "SecureTrading Test Issuer1",
    "splitfinalnumber": "1",
    "dccenabled": "0",
    "settleduedate": "2016-12-13",
    "errorcode": "60022",
    "tid": "27882788",
    "merchantnumber": "00000000",
    "merchantcountryiso2a": "GB",
    "status": "N",
    "transactionreference": "1-2-345679",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "VISA",
    "baseamount": "1050",
    "accounttypedescription": "ECOM",
    "requesttypedescription": "AUTH",
    "currencyiso3a": "GBP",
    "maskedpan": "411111######0211",
    "errormessage": "Unauthenticated",
    "operatorname": "[email protected]",
    "enrolled": "Y",
    "issuercountryiso2a": "US",
    "settlestatus": "3"
  }],
  "secrand": "3J"

 

Not enrolled


{
  u 'requestreference': u 'Adyw3fdbw',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:47:39',
        u 'parenttransactionreference': u '1-2-345678',
        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 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345679',
        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 'TEST23',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'maskedpan': u '411111######0021',
        u 'securityresponsepostcode': u '0',
        u 'enrolled': u 'N',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A256agnuw"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(29) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:53:36"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["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"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["enrolled"] => string(1) "N"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST08"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["securityresponsepostcode"] => string(1) "0"
      ["maskedpan"] => string(16) "411111######0021"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-fwpp74eu","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:24:51","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"1050","enrolled":"N","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST42","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######0021","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"O3L"}

 

Managing authorisation response

Your system will need to interpret the AUTH response in order to determine if the transaction was successful. The most important field to check in the response is the errorcode.

Error code Description
0 Cardholder was successfully authenticated on the card issuer’s ACS.
Customer’s bank authorised the transaction.
Funds will be transferred.
70000 Cardholder was successfully authenticated on the card issuer’s ACS.
Customer’s bank declined the transaction.
Funds will NOT be transferred.
60022 Cardholder was NOT successfully authenticated on the card issuer’s ACS.
Trust Payments did not contact the acquiring bank to seek authorisation.
Funds will NOT be transferred.
99999 An error code of ‘99999’ indicates an unknown error occurred, which requires manual inspection.
We recommend contacting our Support Team for assistance, providing a copy of the entire request submitted and the response returned.
In the interest of security, ensure you omit or mask sensitive field values, such as card details.
other Click here for a full list of error codes used by Trust Payments.

 

Regardless of the errorcode returned in the response, we strongly recommend that you refer to our best practices and configure your system to perform all of the checks outlined.

 

Here is the specification of the fields that are included in the AUTH responses described above, which are specific to 3-D Secure:

Info
Please note that other fields that can be returned are documented on our page covering AUTH requests.

 

Key

Field name Type Length Response Description
enrolled Char 1 Indicates if the cardholder is enrolled in a 3-D Secure scheme:

  • “Y” – Card is enrolled.
  • “N” – Card is not enrolled.
  • “U” – Unable to determine if card is enrolled.
xid Alphanumeric 255 The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments).
status Char 1 Returned if card is enrolled.

Indicates whether or not the customer was authenticated on the card issuer’s ACS:

  • “Y” – Customer authenticated.
  • “N” – Customer not authenticated.
  • “A” – An authentication attempt occurred but could not be completed.
  • “U” – Unable to perform authentication.
cavv Alphanumeric 32 Returned if card is enrolled and authenticated.

The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer.

eci Alphanumeric 2 Returned if card is enrolled and authenticated.

The ECI (E-Commerce Indicator) security level associated with the transaction.

 

Info
The above fields may be requested by a card issuer in the event of a disputed transaction and are included in the response for your reference.

 

Testing

We recommend that you thoroughly test your solution before processing live payments.
Click here for test card details that you can submit when testing.

 

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