Using Account Check to verify customer’s details

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.

If you are unsure, please contact our Support Team for assistance.

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 or Telephone Order (MOTO), Merchant Initiated Transactions (MIT), or using other workflows that are exempt from the PSD2 mandate.

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

Failure to submit these fields will result in a “60025” (Invalid request) error being returned in the response. Click here for further information.

Account checks are only available for certain acquiring banks. Before you begin, please contact our Support Team and ensure your acquiring bank supports this functionality.
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

1. Merchant submits ACCOUNTCHECK request.
2. Trust Payments validates the request and contacts the bank.
3. The acquiring bank will contact the card issuer to perform AVS and security code checks.
4. Trust Payments receives results of the request and passes this back to the merchant.
5. 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.
Additional field credentialsonfile must be submitted with value “1”. (See below)

Field specification

	Field	Format	Description
	credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	This must be set to “1”, to indicate the customer agreed for the payment credentials to be stored for future transactions. See below for further information.

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:

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
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": "TE45 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' => '[email protected]',
'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' => 'TE45 6ST',
'credentialsonfile' => '1'
);

$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": ["ACCOUNTCHECK"],
  "sitereference": "test_site12345",
  "baseamount": "0",
  "orderreference": "My_Order_123",
  "accounttypedescription": "MOTO",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "billingpremise": "789",
  "billingpostcode": "TE45 6ST",
  "credentialsonfile": "1"
}]}'

{"alias":"[email protected]","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":"TE45 6ST","credentialsonfile":"1"}]}

<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="ACCOUNTCHECK">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">0</amount>
      <postcode>TE45 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:

Python
PHP
Raw JSON
Raw XML

{
  u 'requestreference': u 'Ar2xj1hjr',
    u 'version': u '1.00',
    u 'response': [{
      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 '[email protected]',
        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"
  ["response"] => 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) "[email protected]"
      ["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":"[email protected]","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"2","issuercountryiso2a":"US","settlestatus":"0","credentialsonfile":"1"}],"secrand":"NunVEQ"}

<?xml version='1.0' encoding='utf-8'?>
<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>[email protected]</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)