american Archives - Documentation

american

Authorisations

The following documentation explains how to manually submit an AUTH request using our Webservices API.

If you are already processing e-commerce payments using our JavaScript Library (using 3-D Secure v2), you no longer need to manually perform the AUTH request described herein (as the JavaScript Library will automatically perform the authorisation).

This page is written for those processing Mail or Telephone Order (MOTO) payments, Merchant Initiated Transactions (MIT), or other advanced workflows that do not warrant 3-D Secure v2 being enabled.

Requirements

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) will soon be mandated to use 3-D Secure when processing e-commerce transactions, as part of the PSD2 mandate.

To perform 3-D Secure, you will need to utilise our JavaScript Library. Click here to get started.

ECOM (e-Commerce) Maestro transactions require the implementation of 3-D Secure in order to be processed successfully.

To perform 3-D Secure, you will need to utilise our JavaScript Library. Click here to get started.

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.

Click here for further information.

AUTH request

Example

To successfully process an AUTH request, you must follow the specification below:

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)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}

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(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'pan' => '4111111111111111',
  'expirydate' => '12/2020',
  'securitycode' => '123'
);

$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": ["AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","baseamount":"1050","orderreference":"My_Order_123","accounttypedescription":"ECOM","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123"}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <payment>
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
      </payment>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

When testing the AUTH request, ensure you submit your test sitereference. This ensures that transactions are processed to our test bank and no money will change hands. When you go live, you will need to swap out your test sitereference for your live sitereference.

Click here for test card numbers you can submit in AUTH requests while testing.

Field specification

Operation

The following fields relate to the type of request submitted:

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The type of account to be used: “ECOM” – E-commerce “MOTO” – Mail or Telephone Order “RECUR” – Recurring transactions
authmethod XPath: /operation/authmethod	Alpha (11)	Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click here for further information.
credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	The allowed values for this field are 0, 1 and 2. “0” – Not eligible for CoF, or no intention of re-using credentials at a later time. “1” – Transaction credentials flagged as available for future use. “2” – Payment using previously-stored credentials.
initiationreason XPath: /operation/initiationreason	Char (1)	Allows you to assign a reason for a Merchant Initiated Transaction (MIT). Do not submit when processing a Customer Initiated Transaction (CIT).The allowed values for this field are “A”, “C”, “D”, “S” and “X”. “A” – Reauthorisation “C” – Unscheduled payment “D” – Delayed Charges “S” – Resubmission “X” – No-show (for a hotel booking) Click here for further information on the different initiationreason values. Note: You must ensure the initiationreason submitted in the request correctly represents the reason for the new payment. Visa may introduce new values to this list in the future. Please refer to Visa’s own documentation for further information.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “AUTH”, as shown in the request example.
sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	Identifies your site on the Trust Payments system. If you do not know your site reference, please contact our Support Team.

Payment

The following fields contain the customer’s payment details:

Field	Format	Description
baseamount XPath: /billing/amount	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 XPath: /billing/amount/@currencycode	Alpha (3)	The currency of the transaction. Click here for a full list of available currencies. If the currency is submitted in a child request, it must be the same value as the parent transaction.
expirydate XPath: /billing/payment/expirydate	Date MM/YYYY	The expiry date printed on the card.
pan XPath: /billing/payment/pan	Numeric (12-19)	This is the long number printed on the front of the customer’s card.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	Payment method (e.g. “VISA” or “MASTERCARD”). Click here for a full list of different card-based payment types.
securitycode XPath: /billing/payment/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 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.

Merchant

The following fields relate to your account configuration and allow you to configure custom unique references for your request:

Field	Format	Description
chargedescription XPath: /merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the payment that appears on the customer’s bank statement. Only supported by certain acquiring banks. Specification of this field will depend on your acquiring bank. Click here for further information. Valid characters: Uppercase/lowercase A-Z Numbers 0-9 Spaces Punctuation: + – _ . @ ( )
merchantemail XPath: /merchant/email	Email (255)	The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
operatorname XPath: /merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request. By default, this is the Web Services username included in the request. This can be overridden with a custom value by passing through this field in the request (optional).
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	Your unique order reference that can be stored on the Trust Payments system. Note: This can be updated at a later time (only if transaction is pending settlement).

Billing

The following fields contain the customer’s billing details:

Field	Format	Description
billingpremise XPath: /billing/premise	Alphanumeric including symbols (25)	The house number or first line of the customer’s billing address.
billingstreet XPath: /billing/street	Alphanumeric including symbols (127)	The street entered for the customer’s billing address.
billingtown XPath: /billing/town	Alphanumeric including symbols (127)	The town entered for the customer’s billing address.
billingcounty XPath: /billing/county	Alphanumeric including symbols (127)	The county entered for 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 XPath: /billing/country	Alpha (2)	The country for the customer’s billing address. This will need to be in ISO2A format. Click here for a full list of country codes.
billingpostcode XPath: /billing/postcode	Alphanumeric (25)	The postcode entered for 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 XPath: /billing/email	Email (255)	The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingtelephonetype XPath: /billing/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work
billingtelephone XPath: /billing/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
billingprefixname XPath: /billing/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname XPath: /billing/name/first	Alphanumeric including symbols (127)	The customer’s billing first name.
billingmiddlename XPath: /billing/name/middle	Alphanumeric including symbols (127)	The customer’s billing middle name(s).
billinglastname XPath: /billing/name/last	Alphanumeric including symbols (127)	The customer’s billing last name.
billingsuffixname XPath: /billing/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s billing name (e.g. Bsc).

Customer and delivery

The following fields contain the customer’s delivery details:

Field	Format	Description
customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The customer’s house name or number.
customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The customer’s street name.
customertown XPath: /customer/town	Alphanumeric including symbols (127)	The customer’s town.
customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The customer’s county. 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”.
customercountryiso2a XPath: /customer/country	Alpha (2)	The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The customer’s postcode or ZIP code. If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.
customeremail XPath: /customer/email	Email (255)	The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
customertelephonetype XPath: /customer/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work
customertelephone XPath: /customer/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
customerprefixname XPath: /customer/name/prefix	Alphanumeric including symbols (25)	The customer’s prefix name (e.g. Mr, Miss, Dr).
customerfirstname XPath: /customer/name/first	Alphanumeric including symbols (127)	The customer’s first name.
customermiddlename XPath: /customer/name/middle	Alphanumeric including symbols (127)	The customer’s middle name(s).
customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The customer’s last name.
customersuffixname XPath: /customer/name/suffix	Alphanumeric including symbols (25)	The customer’s suffix name (e.g. Bsc).
customerforwardedip XPath: /customer/forwardedip	IP address (39)	Customer forwarded IP address, as provided by a proxy server if available.
customerip XPath: /customer/ip	IP address (39)	The IP of the customer.

Settlement

The following fields contain the Settlement details:

Field

Format

Description

settleduedate
XPath: /settlement/settleduedate

Date YYYY-MM-DD

You can submit this field in the request to specify the date you would like your transaction to settle. This must be within 7 days of the authorisation date.

settlestatus
XPath: /settlement/settlestatus

Numeric (3)

A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.

Click here for a full list of settlestatus values.

AUTH response

The following is an example of an AUTH response indicating the request was processed successfully.

Python
PHP
Raw JSON
Raw XML

{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
        u 'livestatus': u '0',
        u 'issuer': u 'Test Issuer',
        u 'splitfinalnumber': u '1',
        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-80001',
        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 'TEST36',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}

array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 09:52:19"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "Test Issuer"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["orderreference"] => string(12) "My_Order_123"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "0"
      ["transactionreference"] => string(10) "72-9-80003"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST31"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}

{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:08:47","livestatus":"0","issuer":"Test Issuer","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"23-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST96","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"zO9"}

<responseblock version="3.67">
  <requestreference>A3579dkvx</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <orderreference>MyOrder123</orderreference>
      <tid>27882788</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>23-9-80006</transactionreference>
    <security>
      <postcode>2</postcode>
      <securitycode>2</securitycode>
      <address>2</address>
    </security>
    <billing>
      <amount currencycode="GBP">1050</amount>
      <payment type="VISA">
        <issuer>Test Issuer</issuer>
        <issuercountry>ZZ</issuercountry>
        <pan>411111######1111</pan>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <authcode>TEST96</authcode>
    <timestamp>2012-10-08 12:46:02</timestamp>
    <settlement>
      <settleduedate>2012-10-08</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <acquirerresponsecode>00</acquirerresponsecode>
    <operation>
      <splitfinalnumber>1</splitfinalnumber>
      <authmethod>PRE</authmethod>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </response>
  <secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>

When you receive an AUTH response, you must check the field values, to ensure the request was processed successfully.

Please refer to our “Best practices” for further information.

Field specification

Operation

The following fields relate to the type of request submitted:

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The type of account to be used: “ECOM” – E-commerce. “MOTO” – Mail or Telephone Order “RECUR” – Recurring transactions
authmethod XPath: /operation/authmethod	Alpha (11)	Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click here for further information.
credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	The allowed values for this field are 0, 1 and 2. “0” – Not eligible for CoF, or no intention of re-using credentials at a later time. “1” – Transaction credentials flagged as available for future use. “2” – Payment using previously-stored credentials.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference of a previous request, from which key details have been inherited.
requesttypedescription XPath: /@type	Alpha (20)	“AUTH” is returned in the response.

Billing

The following fields contain the customer’s billing details:

Field	Format	Description
baseamount XPath: /billing/amount	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 XPath: /billing/amount/@currencycode	Alpha (3)	The currency of the transaction. Click here for a full list of available currencies.
dccenabled XPath: /billing/dcc/@enabled	Numeric (1)	Indicates if your account is configured for DCC: 1= Yes 0 = No
issuer XPath: /billing/payment/issuer	Alphanumeric (255)	The customer’s card issuer.
issuercountryiso2a XPath: /billing/payment/issuercountry	Alpha (2)	The country for the customer’s card issuer. This will be in ISO2A format. Click here for a full list of country codes.
maskedpan XPath: /billing/payment/pan	Alphanumeric including “#” (12-19)	The customer’s card number. This is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	Payment method (e.g. “VISA” or “MASTERCARD”). Click here for a full list of different card-based payment types.

Merchant

The following fields relate to your account configuration:

Field	Format	Description
chargedescription XPath: /merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the payment that appears on the customer’s bank statement. Only supported by certain acquiring banks. Specification of this field will depend on your acquiring bank. Click here for further information. Valid characters: Uppercase/lowercase A-Z Numbers 0-9 Spaces Punctuation: + – _ . @ ( )
merchantnumber XPath: /merchant/merchantnumber	Alphanumeric (32)	The merchant number that was used to process the transaction. Provided by the acquiring bank.
merchantcategorycode XPath: /merchant/merchantcategorycode	Alphanumeric (255)	These are details associated with the account used to process the transaction.To amend these fields, please contact our Support Team.
merchantcity XPath: /merchant/merchantcity	Alphanumeric (127)
merchantcountryiso2a XPath: /merchant/merchantcountryiso2a	Alpha (2)
merchantname XPath: /merchant/merchantname	Alphanumeric (255)
merchantstatecode XPath: /merchant/merchantstatecode	Alphanumeric (127)
merchantzipcode XPath: /merchant/merchantzipcode	Alphanumeric (10)
operatorname XPath: /merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	Your unique order reference that can be stored on the Trust Payments system. Note: This can be updated at a later time (only if transaction is pending settlement).
tid XPath: /merchant/tid	Alphanumeric (255)	The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.

Settlement

The following fields contain the Settlement details:

Field

Format

Description

settleduedate
XPath: /settlement/settleduedate

Date YYYY-MM-DD

The date on which the transaction will be settled.

settlestatus
XPath: /settlement/settlestatus

Numeric (3)

A numeric value used to indicate the progress of settlement regarding this transaction.

Click here for a full list of settlestatus values.

Transaction status

The following fields returned in the response indicate the outcome of the request:

Field	Format	Description
acquireradvicecode XPath: /acquireradvicecode	Numeric (1)	A numeric value returned following a repeat payment request, indicating if further payments can be processed. Mapping: 0 – No action required. 1 – New account information available. (Help) 2 – Cannot approve at this time. (Help) 4 – Do not process further recurring transactions. 8 – Payment blocked by card scheme. (Help)
acquirerresponsecode XPath: /acquirerresponsecode	Alphanumeric (255)	Used by your acquirer to indicate the outcome of the request.
acquirerresponsemessage XPath: /acquirerresponsemessage	Alphanumeric (255)
authcode XPath: /authcode	Alphanumeric (255)	The authorisation code provided by the issuing bank. This will differ depending on which bank you use.
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the request was successful or not. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Click here for a full list of errorcode and message values.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error.
errormessage XPath: /error/message	Alphanumeric (255)	This provides a brief explanation as to the cause of the error. For successful transactions, this is returned as “Ok”. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
retrievalreferencenumber XPath: /other/retrievalreferencenumber	Alphanumeric (255)	An ISO term. This is used to reference the source transaction.
securityresponseaddress XPath: /security/address	Numeric (1)	The result of AVS and Security Code Checks. Click here to learn more.
securityresponsepostcode XPath: /security/postcode	Numeric (1)
securityresponsesecuritycode XPath: /security/securitycode	Numeric (1)
transactionreference XPath: /transactionreference	Alphanumeric including hyphens (25)	A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
transactionstartedtimestamp XPath: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the transaction was processed.

In addition to the response object, two additional fields are also returned in the response:

Field	Format	Description
requestreference	Alphanumeric (25)	This is an internal field generated by Trust Payments. It must not be validated. If problems are experienced with the request this field may be requested by Trust Payments support to aid in determining the cause.
secrand	Alphanumeric (16)	Random string of characters, returned in the response of non-API-based libraries developed by Trust Payments.

Tokenisation from previous request

To submit subsequent transactions with the same details, your system can process another AUTH request, and reference the previously-completed payment’s transactionreference, which is returned in the response. Submit this reference in the parenttransactionreference field of the new AUTH request, and the majority of fields (card details, billing address, delivery address, order reference, etc.) will be re-used when proceeding with the new payment. Please refer to the following example 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)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "parenttransactionreference": "23-9-80006"
}

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(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'parenttransactionreference' => '23-9-80006'
);

$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": ["AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "parenttransactionreference": "23-9-80006"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","baseamount":"1050","orderreference":"My_Order_123","accounttypedescription":"ECOM","parenttransactionreference":"23-9-80006"}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>12-23-34</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

SafetyPay

The requests outlined in this document will need to be processed manually using our Webservices API.

SafetyPay is a real-time bank transfer / cash payment method. When selecting SafetyPay, customers will be presented with two options. The first allows the customer to pay via online banking, by signing in to their online banking account. After reviewing the pre-filled payment details, they can agree to the payment, before being redirected back to your website. The second option allows the customer to pay the amount in cash at a bank. Once completed, you will receive confirmation via a URL notification.

Features

Supported customer countries	AT, BE, CL, CO, CR, DE, EC, ES, MX, NL, PE, PR
Supported currencies	EUR, USD
Protect Plus	Supported.
Refunds	Full and partial refunds supported (permitted for up to 90 days).
Chargebacks	Payments are not subject to chargebacks.

Configuration

To enable SafetyPay on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.

Process overview

Initiate the customer

Customer agrees to a payment using SafetyPay on the merchant’s website.
Merchant submits AUTH request to initiate the session, including the successfulurlredirect and errorurlredirect.
Merchant receives AUTH response, including redirecturl.

Redirect to SafetyPay

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on SafetyPay’s hosted pages to authorise the payment.
If successful, the browser is redirected to the successfulurlredirect, a page hosted by the merchant that displays confirmation of payment.
If there has been a problem with the payment, the browser is redirected to the errorurlredirect, a page hosted by the merchant that displays an error to the customer.

Payment completion

At a later time, SafetyPay will contact Trust Payments with confirmation that funds have been settled.
Trust Payments will submit a URL notification to the merchant’s system to confirm funds have settled.
Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.

1. Initiate the customer

When the customer chooses to pay with SafetyPay, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.

AUTH request

The example request below is for a SafetyPay AUTH 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)

auth = {
    "currencyiso3a": "EUR",
    "requesttypedescription": "AUTH",
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "paymenttypedescription": "SAFETYPAY",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "DE"
}

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(
    'currencyiso3a' => 'EUR',
    'requesttypedescription' => 'AUTH',
    'accounttypedescription' => 'ECOM',
    'sitereference' => 'test_site12345',
    'baseamount' => '1050',
    'paymenttypedescription' => 'SAFETYPAY',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'DE'
);

$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": "EUR",
     "requesttypedescription": "AUTH",
     "accounttypedescription": "ECOM",
     "sitereference": "test_site12345",
     "baseamount": "1050",
     "paymenttypedescription": "SAFETYPAY",
     "successfulurlredirect": "https://www.example.com/success",
     "errorurlredirect": "https://www.example.com/error",
     "billingfirstname": "Joe",
     "billinglastname": "Bloggs",
     "billingcountryiso2a": "DE"
 }]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"SAFETYPAY","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE"}]}

<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
<successfulurlredirect>https://www.example.com/success</successfulurlredirect>
<errorurlredirect>https://www.example.com/error</errorurlredirect>
    </merchant>
    <billing>
      <name>
        <first>Joe</first>
        <last>Bloggs</last>
      </name>
      <country>ES</country>
      <amount currencycode="EUR">1050</amount>
      <payment type="SAFETYPAY"/>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	Only “ECOM” (e-commerce) is supported.
baseamount XPath: /billing/amount	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)
billingprefixname XPath: /billing/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname XPath: /billing/name/first	Alphanumeric including symbols (127)	The customer’s billing first name.
billingmiddlename XPath: /billing/name/middle	Alphanumeric including symbols (127)	The customer’s billing middle name(s).
billinglastname XPath: /billing/name/last	Alphanumeric including symbols (127)	The customer’s billing last name.
billingsuffixname XPath: /billing/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s billing name (e.g. Bsc).
billingcountryiso2a XPath: /billing/country	Alpha (2)	The country for the customer’s billing address. This will need to be in ISO2A format. For a list of country codes supported by SafetyPay, refer to the list found at the top of this page.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency that the transaction will be processed in (in ISO3A format). For a list of currency codes supported by SafetyPay, refer to the list found at the top of this page.
errorurlredirect XPath: /merchant/errorurlredirect	URL (2048)	The URL that the customer will be returned to following an error on the SafetyPay-hosted pages.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	Your unique order reference that can be stored on the Trust Payments system.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value must be submitted as “SAFETYPAY”.
requesttypedescription XPath: /@type	Alpha (20)	The value in the request must be “AUTH”.
sitereference XPath: /operation/sitereference	Alphanumeric & 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.
successfulurlredirect XPath: /merchant/successfulurlredirect	URL (2048)	The URL that the customer will be returned to following a successful authorisation by SafetyPay.

{
  u'requestreference': u'An3ug1kap',
  u'version': u'1.00',
  u'response': [{
    u'transactionreference': u'23-86-113',
    u'merchantname': u'Test Merchant',
    u'paymenttypedescription': u'SAFETYPAY',
    u'settleduedate': u'2017-03-16',
    u'baseamount': u'1050',
    u'transactionstartedtimestamp': u'2017-03-16 16:25:08',
    u'errormessage': u'Ok',
    u'settlestatus': u'10',
    u'accounttypedescription': u'ECOM',
    u'errorcode': u'0',
    u'redirecturl': u'https://example.com',
    u'acquirertransactionreference': u'12',
    u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww',
    u'requesttypedescription': u'AUTH',
    u'acquirerresponsemessage': u'PENDING',
    u'operatorname': u'[email protected]',
    u'livestatus': u'0',
    u'currencyiso3a': u'EUR'
  }]
}

array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(18) {
      ["transactionreference"] => string(9) "23-86-113"
      ["merchantname"] => string(4) "Test Merchant"
      ["paymenttypedescription"] => string(10) "SAFETYPAY"
      ["settleduedate"] => string(10) "2017-03-16"
      ["baseamount"] => string(4) "1050"
      ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08"
      ["errormessage"] => string(2) "Ok"
      ["settlestatus"] => string(2) "10"
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["redirecturl"] => string(107) "https://example.com"
      ["acquirertransactionreference"] => string(2) "12"
      ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww"
      ["requesttypedescription"] => string(4) "AUTH"
      ["acquirerresponsemessage"] => string(7) "PENDING"
      ["operatorname"] => string(11) "[email protected]"
      ["livestatus"] => string(1) "0"
      ["currencyiso3a"] => string(3) "EUR"
    }
  }
}

{"requestreference":"W23-fjgvn3d9","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"SAFETYPAY","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2017-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","redirecturl":"https:\/\/example.com","acquirertransactionreference":"12","acquirersecret":"q9gy5ppgdyd5fh60kfe2j0f26peu2xww","requesttypedescription":"AUTH","acquirerresponsemessage":"PENDING","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"EUR"}]}

<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>Xd4nk260v</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>44-86-102</transactionreference>
    <timestamp>2017-03-16 17:34:16</timestamp>
    <acquirersecret>gfc8mx0p2fx26f1n5tpy6mtk21naap8c</acquirersecret>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2017-03-16</settleduedate>
      <settlestatus>10</settlestatus>
    </settlement>
    <acquirerresponsemessage>PENDING</acquirerresponsemessage>
    <billing>
      <amount currencycode="EUR">1050</amount>
      <payment type="SAFETYPAY"/>
    </billing>
    <live>0</live>
    <other>
      <redirecturl>https://example.com</redirecturl>
    </other>
    <acquirertransactionreference>4</acquirertransactionreference>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
  </response>
  <secrand>Z1W</secrand>
</responseblock>

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The value returned is “ECOM”.
acquirerresponsemessage XPath: /acquirerresponsemessage	Alphanumeric (255)	Used by your acquirer to indicate the outcome of the request.
acquirersecret XPath: /acquirersecret	Alphanumeric (64)	Used by Trust Payments to verify the response from the acquirer. (Your system does not need to verify this)
acquirertransactionreference XPath: /acquirertransactionreference	Alphanumeric including symbols (127)	Unique transaction reference assigned by SafetyPay.
baseamount XPath: /billing/amount	Numeric (13)	The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency that the transaction was processed in (in ISO3A format). For a list of currency codes supported by SafetyPay, refer to the list found at the top of this page.
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the request was successful or not. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Click here for a full list of errorcode and message values.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
merchantname XPath: /merchant/merchantname	Alphanumeric (255)	These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team.
operatorname XPath: /merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value returned is “SAFETYPAY”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on SafetyPay’s hosted pages.
requesttypedescription XPath: /@type	Alpha (20)	The value returned is “AUTH”.
settleduedate XPath: /settlement/settleduedate	Date YYYY-MM-DD	The date on which the transaction will be settled.
settlestatus XPath: /settlement/settlestatus	Numeric (3)	This allows you to determine the status of the payment. Refer to the Handling the response section below for information on how to best interpret this field.
transactionreference XPath: /transactionreference	Alphanumeric including hyphens (25)	A unique reference for the transaction assigned by Trust Payments.
transactionstartedtimestamp XPath: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the transaction was processed.

Handling the response

The settlestatus returned in the AUTH response is used to determine the status of the SafetyPay payment:

If the settlestatus is “10”, the payment is pending settlement.

The funds have not yet been settled into your bank account.
The next step is to redirect the customer’s browser to the redirecturl to complete the payment.

Funds will not be settled into your account until the customer is redirected to SafetyPay’s pages, in order to complete the payment. Read on for further information.

When there is an update to the settle status of the AUTH, you will receive a URL notification to inform you that the settlestatus has been updated to either “3” or “100”.
Further information on the notifications can be found below.

If the settlestatus is “3”, the payment has been cancelled.

The payment has been declined, or has encountered an error.
To learn more about why the payment was unsuccessful, you will need to look at the errorcode. e.g. “70000” indicates that the payment was declined. Click here for a full list of error codes.

In addition to the above, we also recommend following our Best practices.

2. Redirect to SafetyPay

Your system will need to redirect the customer’s browser to the redirecturl, which is a page hosted by SafetyPay, in order to process the payment. At a later time, the customer will be redirected back to either the successfulurlredirect or the errorurlredirect provided in the AUTH request.

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on SafetyPay’s pages.
Recommended actions: Display confirmation that the payment was successful.

If the customer is redirected to the errorurlredirect:
The customer encountered a problem that has prevented them from completing the payment.
Recommended actions: Inform the customer that there was a problem with the payment, displaying sufficient transaction details for the customer to query the payment attempt.

When testing, you will be displayed the sandbox as provided by SafetyPay. To complete a test transaction, you will need to follow the instructions displayed on screen. Please contact your account manager for test credentials to enter while on the sandbox.

3. Payment completion

Once the customer returns from the SafetyPay hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

Please check for any URL redirect rules that may be enabled in the MyST Rule manager on your site reference(s), as these may conflict and take precedence over the successfulurlredirect and errorurlredirect fields submitted in the AUTH request.

Once a payment has been authorised, funds will be settled at a later time, as determined by SafetyPay.

The settlement process for SafetyPay differs from the standard process followed with card-based payment methods.

The settlement notification may not be sent immediately after processing the AUTH.

In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.

Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

We recommend including at least the following fields in your authorisation notification:

Acquirer Response Message (acquirerresponsemessage)
Base Amount (baseamount) (e.g. £10.50 is “1050”)*
Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
Billing Country (billingcountryiso2a)
Currency (currencyiso3a)
Error Code (errorcode)
Live Status (livestatus)
Order Reference (orderreference)
Payment Type (paymenttypedescription)
Request Type (requesttypedescription)
Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)
Transaction Started Timestamp (transactionstartedtimestamp)

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

Cancelled transactions (settlestatus “3”) may be settled at a later time. In situations where the customer has completed the steps required to fulfil the payment, the settlestatus is updated to “100” to indicate the funds have been transferred to your account.

If you have contacted the Support Team to configure settlement notifications (as described above), you will be notified when this occurs.

Testing

You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.

Requirements

You will need to contact our Support team, providing your SafetyPay test account details. We will then configure your test site reference to connect directly to the SafetyPay testing environment.

When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the SafetyPay testing environment to simulate a payment. Other than this, the process will be exactly the same as processing live payments.

Refunds

After processing a payment with SafetyPay, it is possible to pay the customer back by submitting a REFUND request.

Refunds for SafetyPay are settled immediately (settlestatus “100”).

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

The REFUND request and response for SafetyPay payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.

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.