3dquery Archives - Documentation

3dquery

Testing

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

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

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

Before you begin testing…

Please be aware of the following notes:

Most fields submitted to our test system will be accepted. Any data breaching its defined specification will return an error message.

Any test data that generates a successful response when submitted while a merchant is in test mode, will produce a declined response when a merchant is switched into live mode. In some cases, the test data may return an error response.

Our test system attempts to simulate responses in a similar fashion to the live system. However, depending on your acquirer you may find some responses differ slightly from those given by the test system.

In the interest of security, we recommend against using real payment details when using your test account.

We recommend specifying the main amount “10.50” when testing. Other amounts can be used but may return unexpected responses.

If you’re unsure where to start with your testing, you may find these resources helpful:
- Payment Pages integrations
- JavaScript Library integrations

Test card details

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

Do not use these credentials when processing transactions on your live site reference.

While testing, all card types are supported, but when using your live account, you will receive an error if you do not have a valid merchant number for the payment type submitted.

A baseamount of 70000 (£700.00) will always return a declined response from the test bank.
A baseamount of 60010 (£600.10) will always return a bank system error from the test bank.
Using baseamount 1050 (£10.50) will not generate an error.

3-D Secure v2

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

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

3-D Secure v1

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

Visa-branded cards

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

Mastercard-branded cards

Test case	Mastercard
Test case	Credit	Debit	Maestro (Intl.)	Maestro (UK)
Enrolled (Y)	5100000000000511 2221000000000611	5124990000000911	5000000000000611	6759000000000711
Not enrolled (N)	5100000000000321 2221000000000991	5124990000000721	5000000000000421	6759000000000521
Unknown enrollment (U)	5100000000000701 2221000000000801	5124990000000101	5000000000000801	6759000000000901

3-D Secure status testing

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

Displaying the test ACS page

For Payment Pages:

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

For JavaScript library implementations:

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

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

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

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

Non 3-D Secure

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

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

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

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

Testing AVS and security code checks

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

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

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

Premise

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

Postcode / ZIP code

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

Security code

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

Testing non-card payment methods

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

Testing recurring payments

Testing for the acquirer advice code

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

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

Where to find the acquirer advice code

This code is returned in your daily subscription email report.
It’s viewable within MyST by selecting the additional field to be displayed on the transaction search page. It can also be viewed on the single transaction view.
Additionally, for those who have processed a recurring AUTH transaction using the API, the code is returned in the acquireradvicecode field in the response.

How to test for different acquirer advice codes

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

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

Acquirer advice code ‘1’ can only be returned for recurring Mastercard transactions.

Mastercard
Acquirer advice code returned	Card number	Base amount
0	5100000000000511	1050
1	5100000000000271	1001
2	5100000000000271	1002
4	5100000000000271	1004
8	5100000000000271	1008

Testing Protect Plus

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

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

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

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

Testing DCC

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

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

Successful authorisations

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

Declined authorisations

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

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

3-D Secure (version 1)

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.

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

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.

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

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:

PYTHON
PHP
CURL

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

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.

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:

PYTHON
PHP
CURL

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

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.

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

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

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.

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 :

HTML

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

PYTHON
PHP
CURL

#!/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=="
}]}'

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:

PYTHON
PHP
CURL

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

PYTHON
PHP
CURL

{
  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

PYTHON
PHP
CURL

{
  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

PYTHON
PHP
CURL

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

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.

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.