Follow these instructions when using Account Checks to verify the customer’s details prior to processing a payment.
If you are already processing e-commerce payments using our JavaScript Library, your existing solution can be updated to also submit Account Check requests with minimal changes to the mark-up. Click here to learn more.
Prerequisites
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.
All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure when processing e-commerce Account Checks, as part of the PSD2 mandate.
To process an e-commerce Account Check that is authenticated with 3-D Secure, you will need to utilise our JavaScript Library instead of the solution described below. Click here to get started.
The following content should only be utilised by merchants processing Account Checks that are Mail Order Telephone Order (MOTO) payments, Merchant Initiated Transactions (MIT), or other workflows that are exempt from the PSD2 mandate.
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.
- Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
- Account checks can only be performed for card-based payment methods.
Mandate considerations
Visa and Mastercard have mandated that you must obtain cardholder consent if storing card details for future use, and that these must be flagged at the time of the first authorisation, by submitting the credentialsonfile field in your requests. To do so, you will need to ensure the ACCOUNTCHECK request submitted includes the additional field credentialsonfile, with value set to “1”.
You must also flag any subsequent payments that are utilising previously-stored credentials, by including the credentialsonfile field in these requests with value set to “2”.
Click here to learn more about Credentials on File.
Checks performed
All Account Checks processed will perform checks on the cardholder’s first line of address, the cardholder’s postcode and the security code, to ensure the details entered by the customer are valid.
Click here to learn more about these checks.
Process overview
- Merchant submits ACCOUNTCHECK request.
- Trust Payments validates the request and contacts the bank.
- The acquiring bank will contact the card issuer to perform AVS and security code checks.
- Trust Payments receives results of the request and passes this back to the merchant.
- Merchant receives and interprets this response.
No funds are reserved by ACCOUNTCHECK requests
The customer’s account is not debited when an ACCOUNTCHECK request is performed.
Similar to standard AUTH requests, AVS and Security Code Checks are performed on ACCOUNTCHECK requests. We recommend reading our documentation on these checks before proceeding.
ACCOUNTCHECK request
The fields required in an ACCOUNTCHECK request are the same as a standard AUTH request, except with the following differences:
- The baseamount can be “0”. A non-zero amount can be submitted – this will be inherited in any subsequent requests that reference this Account check as its parent, unless overridden with a new amount.
Field specification
| Field | Format | Description | |
| credentialsonfile XPath: /operation/credentialsonfile |
Numeric (1) |
The allowed values for this field are 0, 1 and 2.
This is required for transactions where the merchant is utilising Credentials on File (CoF). If the transaction is not eligible for CoF, or you do not wish to use credentials for future transactions, you can omit this field. |
About inheritance
You can submit any field that you can submit in an AUTH request and these will be inherited by any subsequent child requests. Click here to learn more.
The following is an example of an ACCOUNTCHECK request:
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
accountcheck= {
"currencyiso3a": "GBP",
"requesttypedescriptions": ["ACCOUNTCHECK"],
"sitereference": "test_site12345",
"baseamount": "0",
"orderreference": "My_Order_123",
"accounttypedescription": "MOTO",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"billingpremise": "789",
"billingpostcode": "TR45 6ST",
"credentialsonfile": "1"
}
strequest = securetrading.Request()
strequest.update(accountcheck)
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' => 'webservices@example.com',
'password' => 'Password1^',
);
$requestData = array(
'currencyiso3a' => 'GBP',
'requesttypedescriptions' => array('ACCOUNTCHECK'),
'sitereference' => 'test_site12345',
'baseamount' => '0',
'orderreference' => 'My_Order_123',
'accounttypedescription' => 'MOTO',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'billingpremise' => '789',
'billingpostcode' => 'TR45 6ST',
'credentialsonfile' => '1'
);
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
?>
curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
"currencyiso3a": "GBP",
"requesttypedescriptions": ["ACCOUNTCHECK"],
"sitereference": "test_site12345",
"baseamount": "0",
"orderreference": "My_Order_123",
"accounttypedescription": "MOTO",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"billingpremise": "789",
"billingpostcode": "TR45 6ST",
"credentialsonfile": "1"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescriptions":["ACCOUNTCHECK"],
"sitereference":"test_site12345",
"baseamount":"0",
"orderreference":"My_Order_123",
"accounttypedescription":"MOTO",
"pan":"4111111111111111",
"expirydate":"12\/2020",
"securitycode":"123",
"billingpremise":"789",
"billingpostcode":"TR45 6ST",
"credentialsonfile":"1"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="ACCOUNTCHECK">
<merchant>
<orderreference>My_Order_123</orderreference>
</merchant>
<billing>
<amount currencycode="GBP">0</amount>
<postcode>TR45 6ST</postcode>
<premise>789</premise>
<payment>
<pan>4111111111111111</pan>
<securitycode>123</securitycode>
<expirydate>12/2020</expirydate>
</payment>
</billing>
<operation>
<accounttypedescription>MOTO</accounttypedescription>
<sitereference>test_site12345</sitereference>
<credentialsonfile>1</credentialsonfile>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
ACCOUNTCHECK response
After the request has been processed, you will receive a single response that contains the response to the ACCOUNTCHECK request:
{
u 'requestreference': u 'Ar2xj1hjr',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2016-12-07 16:12:00',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
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-80023',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '0',
u 'accounttypedescription': u 'MOTO',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'ACCOUNTCHECK',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST46',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com',
u 'securityresponsepostcode': u '2',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '2',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0',
u 'credentialsonfile': u '1'
}]
}
array(3) {
["requestreference"] => string(9) "A4cenptwx"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(28) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 11:04:29"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["baseamount"] => string(1) "0"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["securityresponsepostcode"] => string(1) "2"
["transactionreference"] => string(10) "72-9-80018"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["orderreference"] => string(12) "My_Order_123"
["accounttypedescription"] => string(4) "MOTO"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(12) "ACCOUNTCHECK"
["securityresponsesecuritycode"] => string(1)"2"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(6) "TEST39"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "webservices@example.com"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "2"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
["credentialsonfile"] => string(1) "1"
}
}
}
{
"requestreference":"W23-q3wa45ge",
"version":"1.00",
"response":[{
"transactionstartedtimestamp":"2016-12-07 16:16:39",
"livestatus":"0",
"issuer":"SecureTrading Test Issuer1",
"dccenabled":"0",
"settleduedate":"2016-12-07",
"errorcode":"0",
"baseamount":"0",
"tid":"27882788",
"merchantnumber":"00000000",
"securityresponsepostcode":"2",
"transactionreference":"23-9-80024",
"merchantname":"Test Merchant",
"paymenttypedescription":"VISA",
"orderreference":"My_Order_123",
"accounttypedescription":"MOTO",
"acquirerresponsecode":"00",
"requesttypedescription":"ACCOUNTCHECK",
"securityresponsesecuritycode":"2",
"currencyiso3a":"GBP",
"authcode":"TEST53",
"errormessage":"Ok",
"operatorname":"webservices@example.com",
"merchantcountryiso2a":"GB",
"maskedpan":"411111######1111",
"securityresponseaddress":"2",
"issuercountryiso2a":"US",
"settlestatus":"0",
"credentialsonfile":"1"
}],
"secrand":"NunVEQ"
}
<responseblock version="3.67">
<requestreference>X575647667</requestreference>
<response type="ACCOUNTCHECK">
<merchant>
<merchantname>Test Merchant</merchantname>
<orderreference>My_Order_123</orderreference>
<tid>27882788</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>16-9-1</transactionreference>
<billing>
<amount currencycode="GBP">0</amount>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<issuercountry>US</issuercountry>
<pan>411111######1111</pan>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST53</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2013-01-16 10:48:17</timestamp>
<acquirerresponsecode>00</acquirerresponsecode>
<security>
<address>2</address>
<postcode>2</postcode>
<securitycode>2</securitycode>
</security>
<settlement>
<settleduedate>2013-01-16</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<operation>
<accounttypedescription>MOTO</accounttypedescription>
<credentialsonfile>1</credentialsonfile>
</operation>
</response>
<secrand>bByuPvGz9Hcm</secrand>
</responseblock>
Handling the response
- Ensure that the errorcode value returned is “0”, indicating success. (You must not store credentials if an error has occurred)
- Check the values returned in the securityresponseaddress, securityresponsepostcode and securityresponsesecuritycode fields and only proceed if business requirements have been satisfied. (More info provided below)
It is strongly recommended that you check the security fields returned in the response, and manually investigate transactions where the returned securityresponsesecuritycode is “4” (indicating the customer entered a security code that doesn’t match the value found on the back of the card).
| Field | Format | Description | |
| securityresponseaddress XPath: /security/address |
Numeric (1) |
“0” Not given – Your system did not provide the acquiring bank the information required to perform this check. “1” Not checked – The acquiring bank did not perform this check on the information you provided in the request. “2” Matched – The information you provided in the request matches the information obtained by the acquiring bank, from the customer’s payment issuer. “4” Not matched – The information you provided in the request does not match the information obtained by the acquiring bank, from the customer’s payment issuer. |
|
| securityresponsepostcode XPath: /security/postcode |
Numeric (1) | ||
|
securityresponsesecuritycode XPath: /security/securitycode |
Numeric (1) |
