Card store


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.


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.

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.
With mandates that have been introduced recently (such as Credentials on File), we strongly recommend that you process Account check requests instead of Card store.


Click here for further information on Account checks.


Process overview

Submit a STORE request including the customer’s card details. We store the card details securely on our system for future use.
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.



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:

import securetrading

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

store = {
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["STORE"],
    "orderreference": "EXAMPLE CARDSTORE",
    "pan": "4111111111111111",
    "expirydate": "12/2020",
    "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()
stresponse = st.process(strequest) #stresponse contains the transaction response

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');

$configData = array(
  'username' => '[email protected]',
  'password' => 'Password1^',
$requestData = array(
    'sitereference' => 'test_site12345',
    'requesttypedescriptions' => array('STORE'),
    'orderreference' => 'EXAMPLE CARDSTORE',
    'pan' => '4111111111111111',
    'expirydate' => '12/2020',
    '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 = \Securetrading\api($configData);
$response = $api->process($requestData);

curl --user [email protected]:Password1^ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["STORE"],
  "orderreference": "EXAMPLE CARDSTORE",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "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'response': [{
    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"
  ["response"]=> 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","issuercountryiso2a":"US","livestatus":"0","issuer":"SecureTrading Test Issuer1"}],"secrand":"mXMQitD4uY7kO4B"}


Field specification


Field name Type Length Request Response Description
expirydate Date MM/YYYY 7 The expiry 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 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 Trust Payments 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 the Trust Payments 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 Trust Payments 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:



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.