Contents

Card store

You can submit card store requests if you wish to store the customer’s card and billing details for future use, without the need to take an initial payment from their card, or needing to store sensitive data on your own server. Once stored, simply refer to the unique card store Transaction Reference in a future request to process a payment using the stored card details. This allows returning customers to pay without the need to re-enter their card details.

We do not contact your acquiring bank during the card store process.

Disabled
Although the customer’s card number and expiry date are stored as part of the card store, the security code is not. You must never store the customer’s security code on your system, or include the value in a card store request.

 

Process overview

1
Submit a STORE request, including a cachetoken submitted by the customer’s browser by the JavaScript Client SDK. We store the card details securely on our system for future use.
2
You will be returned a STORE response, which includes a unique transactionreference.
Submit this value in the parenttransactionreference field of future requests to inherit the card details.

 

Requirements

Warning
You will need to enable card store on your account before continuing
Please contact our Support team to arrange this.
Duplicate checks

Supported payment methods

  • American Express
  • Diners Club International
  • Discover
  • JCB
  • Maestro
  • Mastercard
  • Debit Mastercard
  • V PAY
  • Visa
  • Visa Debit
  • Visa Electron
  • Visa Purchasing

 

STORE request

The following is an example of a STORE request:


#!/usr/bin/python
import securetrading

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

store = {
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["STORE"],
    "accounttypedescription": "ECOM",
    "orderreference": "EXAMPLE CARDSTORE",
    "cachetoken": "token_posted_by_st.js",
    "accounttypedescription": "CARDSTORE",
    "billingprefix": "Mr",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingpremise": "789",
    "billingstreet": "Test Street",
    "billingtown": "Bangor",
    "billingcounty": "Gwynedd",
    "billingcountryiso2a": "GB",
    "billingemail": "[email protected]",
    "billingtelephone": "01234567890",
    "billingtelephonetype": "H"
}

strequest = securetrading.Request()
strequest.update(store)
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('STORE'),
    'accounttypedescription' => 'ECOM',
    'orderreference' => 'EXAMPLE CARDSTORE',
    'cachetoken' => 'token_posted_by_st.js',
    'accounttypedescription' => 'CARDSTORE',
    'billingprefix' => 'Mr',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingpremise' => '789',
    'billingstreet' => 'Test Street',
    'billingtown' => 'Bangor',
    'billingcounty' => 'Gwynedd',
    'billingcountryiso2a' => 'GB',
    'billingemail' => '[email protected]',
    'billingtelephone' => '01234567890',
    'billingtelephonetype' => 'H'
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["STORE"],
  "accounttypedescription": "ECOM",
  "orderreference": "EXAMPLE CARDSTORE",
  "cachetoken": "token_posted_by_st.js",
  "accounttypedescription": "CARDSTORE",
  "billingprefix": "Mr",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "billingpremise": "789",
  "billingstreet": "Test Street",
  "billingtown": "Bangor",
  "billingcounty": "Gwynedd",
  "billingcountryiso2a": "GB",
  "billingemail": "[email protected]",
  "billingtelephone": "01234567890",
  "billingtelephonetype": "H"
}]}'

 

STORE response

The following is an example of a STORE response, indicating the request was processed successfully:


{
  u'requestreference': u'A65h6rv73',
  u'version': u'1.00',
  u'responses': [{
    u'transactionreference': u'23-52-101',
    u'merchantname': u'Test Merchant',
    u'paymenttypedescription': u'VISA',
    u'transactionactive': u'1',
    u'orderreference': u'EXAMPLE CARDSTORE',
    u'transactionstartedtimestamp': u'2017-02-16 14:31:09',
    u'errormessage': u'Ok',
    u'operatorname': u'[email protected]',
    u'accounttypedescription': u'CARDSTORE',
    u'errorcode': u'0',
    u'maskedpan': u'411111######1111',
    u'requesttypedescription': u'STORE',
    u'operatorname': u'[email protected]',
    u'issuercountryiso2a': u'US',
    u'livestatus': u'0',
    u'issuer': u'SecureTrading Test Issuer1'
  }]
}
array(3) {
  ["requestreference"]=> string(9) "A126cfruw"
  ["version"]=> string(4) "1.00"
  ["responses"]=> array(1) {
    [0]=> array(16) {
      ["transactionreference"]=> string(9) "23-52-103"
      ["merchantname"]=> string(4) "Test Merchant"
      ["paymenttypedescription"]=> string(4) "VISA"
      ["transactionactive"]=> string(1) "1"
      ["orderreference"]=> string(17) "EXAMPLE CARDSTORE"
      ["transactionstartedtimestamp"]=> string(19) "2017-03-01 10:05:29"
      ["errormessage"]=> string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["accounttypedescription"]=> string(9) "CARDSTORE"
      ["errorcode"]=> string(1) "0"
      ["issuercountryiso2a"]=> string(2) "US"
      ["maskedpan"]=> string(16) "411111######1111"
      ["requesttypedescription"]=> string(5) "STORE"
      ["operatorname"]=> string(23) "[email protected]"
      ["livestatus"]=> string(1) "0"
      ["issuer"]=> string(26) "SecureTrading Test Issuer1"
    }
  }
}
{
  "requestreference": "W23-ytfz8fzk",
  "version": "1.00",
  "response": [{
    "transactionreference": "23-52-102",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "VISA",
    "transactionactive": "1",
    "orderreference": "EXAMPLE CARDSTORE",
    "transactionstartedtimestamp": "2017-02-16 14:46:38",
    "errormessage": "Ok",
    "operatorname": "[email protected]",
    "accounttypedescription": "CARDSTORE",
    "errorcode": "0",
    "maskedpan": "411111######1111",
    "requesttypedescription": "STORE",
    "operatorname": "[email protected]",
    "issuercountryiso2a": "US",
    "livestatus": "0",
    "issuer": "SecureTrading Test Issuer1"
  }],
  "secrand": "mXMQitD4uY7kO4B"
}

 

Field specification

Key

Field name Type Length Request Response Description
cachetoken Alphanumeric including hyphen Variable This contains a reference to the customer’s payment details. This is the value posted to your servers after the customer has entered their payment details into your HTML form and clicked “Submit”.
requesttypedescriptions Alpha 20 You must submit “STORE”, as shown in the request example.

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

sitereference Alphanumeric including underscore 50 The unique Secure Trading reference that identifies your site.
accounttypedescription Alpha 20 This must be submitted as “CARDSTORE”. This is returned in the response.
orderreference Alphanumeric including symbols 255 Your unique order reference that can be stored on Secure Trading’s system.
transactionactive Numeric 1 This flag indicates if the card details are enabled for future requests. It can be one of two values:

  • “0” for No (disabled for future requests)
  • “1” for Yes [default] (enabled for future requests)

You can update this value by submitting a TRANSACTIONUPDATE request.

billingpremise Alphanumeric including symbols 25 Use this field to store the house number or first line of the customer’s billing address.
billingstreet Alphanumeric including symbols 127 Use this field to store the street of the customer’s billing address.
billingtown Alphanumeric including symbols 127 Use this field to store the town of the customer’s billing address.
billingcounty Alphanumeric including symbols 127 Use this field to store the county of the customer’s billing address. For US addresses, the state would be entered in this field. Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
billingcountryiso2a Alpha 2 Use this field to store the country of the customer’s billing address. This will need to be in ISO2A format. Click here for a full list of country codes.
billingpostcode Alphanumeric 25 Use this field to store the postcode of the customer’s billing address.

If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.

billingemail Email 255 Use this field to store the customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingtelephonetype Char 1 Use this field to store the type of telephone number. The options available are:

  • H = Home
  • M = Mobile
  • W = Work

 

billingtelephone Numeric and includes symbols 20 Use this field to store the customer’s telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )

 

billingprefixname Alphanumeric including symbols 25 Use these fields to store the customer’s billing name.
billingfirstname 127
billingmiddlename 127
billinglastname 127
billingsuffixname 25
transactionreference Alphanumeric 25 The unique Secure Trading reference for the transaction.

It is important that you keep a record of this reference, as this is used to inherit the stored card details for use in future payment requests.

 

Further actions

Following the completion of a card store request, you can use the stored details in future requests as follows:

 

Querying stored details

Perform a TRANSACTIONQUERY request to retrieve the stored details (for security reasons, the card number will be masked in the response).

 

Updating stored details

Perform a TRANSACTIONUPDATE request to update the stored details. You can update the following fields:

 

Working with stored details

You can take the value of the transactionreference returned in the STORE response, and submit this in the parenttransactionreference of a new request. The card and billing details submitted in the card store request will be inherited in the new request. The following request types support this behaviour:

 

Padlock

Card store and 3-D Secure

  • You can reference a card store to inherit the stored details to include them in a THREEDQUERY request.
  • The customer must be present when performing the 3-D Secure authentication.
  • All e-commerce Maestro transactions must be processed using 3-D Secure.