XML Specification (c)

Transcription

1 This document is to be used as a reference when viewing any XML throughout Secure Trading s documentation. The conventions used to describe XML Requests and Responses are outlined. Published: 25 April (c)

2 Table of Contents 1 Introduction Pre-requisites How to read our documentation Secure Trading s XML Authorisation Process Overview AUTH XML Request AUTH XML Response Refund Process Overview REFUND XML Request REFUND XML Response CFT Refunds Requirements CFT REFUND XML Request CFT REFUND XML Response Account Check Process Overview ACCOUNTCHECK XML Request ACCOUNTCHECK XML Response Combining Account Checks with other request types Rules Activating rules Rule types Interpreting the XML Response Merchant Decline Rule (STR-1) Best Practices Error code Settle status Security fields Sanity checks Troubleshooting Invalid or incomplete XML Request Testing Testing successful transactions Testing unsuccessful transactions Further Information and Support Secure Trading Support Secure Trading Sales Useful Documents Frequently Asked Questions Appendix Pre-Authorisations and Final Authorisations VISA Additional Authorisation Data Merchant Category Code (MCC 6012) Payment facilitator Digital wallet Settle Statuses Secure Trading Limited April 2018 Page 2 / 73

3 1 Introduction The XML Specification describes the structure of the XML code to be submitted to the Secure Trading Payment Platform (STPP) and what will be returned to your system. In particular, we will cover the three most common types of request to STPP: AUTH - Used to seek authorisation for a payment. REFUND - To process a refund against a previous transaction. ACCOUNTCHECK - This is used to check the customer s account prior to performing an AUTH. There are other request types that can performed and these are covered in smaller supplemental documents that can be downloaded separately from our website ( The supplier-customer chain within Secure Trading s systems has two levels of customer, Secure Trading therefore make a clear definition between the two: Merchant relates to a customer of Secure Trading that uses the system to process requests, such as those for online payments. Customer relates to a customer of the merchant. 1.1 Pre-requisites Please ensure you have considered the following pre-requisites before continuing: Internet Merchant Account An Internet Merchant Account is required if you would like to process online e-commerce transactions. We have relationships in place with certain acquirers and will therefore be able to assist you. For contact details of our sales team, please refer to section Secure Trading Account In order to be able to set up your system to process the XML Requests and Responses outlined within this document (or any of our technical specifications), you will need to have a Secure Trading account. If you do not have an account, please contact our Sales team (see section 10.2). Secure Trading Limited April 2018 Page 3 / 73

4 1.2 How to read our documentation Our documents use diagrams and parameter tables to convey the structure of the XML code Diagrams The structure of the XML is displayed diagrammatically as follows: 1 request 2 parent 3 child1 4 child2 5 child XML nodes are represented by rectangles, labelled with the name of the node. Arrows are used to link parent tags to child nodes. e.g. child1 element shown above can be denoted /request/parent/child1. A plus symbol indicates the tag contains additional child nodes that have been omitted from the diagram because they are not relevant. e.g. /request/parent/hiddenchild Solid border shows a required node. Dashed border shows an optional node. Dotted border shows a conditional node (required under certain conditions). Please note that all fields that are processed through Secure Trading s systems should be submitted as lowercase values, without spaces, hyphens or line-breaks. Secure Trading Limited April 2018 Page 4 / 73

5 1.2.2 Parameter Tables Consider the following XML: <payment type="visa"> <pan> </pan> <expirydate>06/2016</expirydate> </payment> This would be described in the parameter tables as follows: Tag Type Length Required Comment payment type="" an 20 Y The customer s card type. E.g. VISA pan n Y The number on the front of the card. expirydate an 7 Y The expiry date. E.g. 06/ Tag The "Tag" column lists the names of relevant nodes. Child nodes are indented. e.g. <pan> is a child element in the <payment> node. Notation such as payment type= indicates a tag <payment> with an attribute type. E.g. <payment type= VISA > Type The "Type" column indicates the field type. Either an, n or char, indicating alphanumeric, numeric or character respectively Length The "Length" column states the maximum or required length of the field. e.g. "20" Required The "Required" column indicates whether a node must be present in the XML: Y is for required. "N" is for optional. "C" is for conditional. These are only required under certain conditions Comment The "Comment" column provides a short description of the node. Secure Trading Limited April 2018 Page 5 / 73

6 1.3 Secure Trading s XML Future compatibility considerations In order to maintain compatibility with future updates to this specification, the following criteria should be adhered to. A missing request tag will be considered the same as an empty tag. A missing response tag should be considered the same as an empty tag. A missing response element should be considered the same as an empty element. The order of nodes within a given block may change at any time and your system should allow for this. Any unexpected elements should be ignored. Any unexpected tags should be ignored. Any unexpected attributes should be ignored. Whitespace characters at the start and end of data within a tag should be ignored. Secure Trading does not specify the total length of XML Responses, as the nodes included in the responses depend on the type of request performed, third-parties that may be involved and also because the nodes returned may be changed in the future updates Character Encoding The STPP system will accept any Unicode characters. The default encoding used for XML is UTF-8 which is a multi-byte encoding scheme. Most XML parsers will automatically handle this. A request that is not properly encoded may receive the following response: "XML: Invalid byte 1 of 1-byte UTF-8 sequence" In order to avoid this, either encode the XML request using UTF-8, or specify the encoding in the first line of the request. Any request must be correctly encoded according to the character encoding specified in the XML header. For example, to use the Western character set: <?xml version="1.0" encoding="iso "?> All responses from Secure Trading are encoded using UTF-8. Your system must be prepared to accept any valid XML encoded this way (even if the request uses a different encoding). Most XML parsers will handle this automatically as it is part of the XML Specification Escaping Characters The data submitted within the XML <tags> must be correctly escaped. Most XML parsers will automatically do this. For example: The character '&' MUST be escaped as '&' The character '<' MUST be escaped as '<' Failure to properly escape characters can lead to Malformed XML and may lead to security problems with malicious users System Time Secure Trading s System Time is in Greenwich Mean Time (GMT). Secure Trading Limited April 2018 Page 6 / 73

7 1.3.5 Inheritance Using inheritance, you are able to re-use details from a previous transaction when performing subsequent requests through STPP. This is achieved by including the transaction reference of a previous request (the parent) in a new XML Request (the child). The parent transaction reference is submitted in operation / parenttransactionreference. When you submit this field, you will not have to re-enter the values submitted in the parent transaction as these will be inherited from the parent. The majority of fields in a parent transaction will be inherited by the child e.g. the parent s billing address, delivery address and payment details. This is especially useful when performing refunds or re-authorisations, as this means you don t have to needlessly submit the same information multiple times. e.g. When first processing an authorisation request, you will be required to submit the necessary fields to process the payment (e.g. the card number and expiry date). At a later date, you may wish to perform a refund once the initial payment has settled. In this case, you won t need to resubmit the same card details, as these will be inherited from the parent transaction (but you can opt to resubmit the card details if you prefer to do so). If you submit a child request immediately after the parent, you may be returned a Missing parent error. If this happens, wait a few more minutes and try again Partial inheritance It is possible to inherit a subset of fields from a parent request and specify new values for others. To achieve this, submit the parent transaction reference as described above and also submit values for the fields you would like to override. e.g. You can include a parent transaction reference to inherit the card details and billing address, but then specify a new delivery address. The billing address cannot be partially inherited. If you are updating the billing address, you must submit the new address in full. If you wish to inherit the billing address details you must leave the billing address fields blank in any child request that you submit. Note: The same applies to the customer address fields. Please note that child transactions cannot override the currency of a parent Required fields When we specify a field as required in our specification, this infers that the field must be present, be it submitted directly in the XML Request or inherited from a parent. e.g. To process a VISA payment, a card number is always required. You must either submit this in the XML Request or inherit this from an earlier request Tokenisation (repeat payments) You can use inheritance to perform tokenisation. See section for further information Additional considerations While most fields are inherited by the child request, there can be minor variations in inheritance behaviour, depending on the request types, account types and the specific acquiring bank involved. If your implementation relies on certain inherited fields being present, we recommend contacting our Support team to clarify which fields will be inherited, based on your configuration (see section 10.1). Secure Trading Limited April 2018 Page 7 / 73

8 2 Authorisation 2.1 Process Overview This section of the document will provide an overview of the process of performing an authorisation and a breakdown of the parties affected. The following is an overview of performing an Authorisation (AUTH) through STPP: M E R C H A N T Customer opts to make a payment A C Q U I R I N G B A N K C A R D I S S U E R Merchant submits an AUTH XML Request to Secure Trading. Secure Trading validates the request and forwards the details to the acquiring bank using a secure connection. See section 2.2 The acquiring bank will contact the card issuer to perform checks on the customer's payment details.. The acquiring bank retrieves information from the card issuer and returns this to Secure Trading. The card issuer performs various checks (including AVS and CVV2) and decides to either authorise or decline the transaction. Secure Trading interprets the response from the acquiring bank. Then returns an XML Response to the merchant. Merchant receives an AUTH XML Response from Secure Trading and interprets this response. See section 2.3 The merchant stores this response in their system for future reference. See section 7 Secure Trading Limited April 2018 Page 8 / 73

9 2.2 AUTH XML Request In order to successfully process an Authorisation Request, the XML submitted by the merchant to Secure Trading must follow the formatting outlined in this section of the document AUTH XML Request Overview If you wish to process an authorisation through Secure Trading s systems, then you will need to have a merchant account with an acquiring bank. If you are unsure of this, please Secure Trading Support (see section 10.1). The following diagram shows a standard e-commerce authorisation. Each child element is outlined in greater detail within this section of the document. alias request type = AUTH operation merchant billing customer settlement An <alias> tag is included for each request. The value is dependent on how the merchant has integrated with Secure Trading: Web Services: The alias is your Web Services username. STAPI: The alias is your site reference. Please note that elements submitted in the XML Request must have a value length less than or equal to the length assigned in the parameter tables. Longer field submissions will either be processed in a truncated form or cause an invalid field error ( ) <operation> request type = AUTH operation accounttypedescription authmethod parenttransactionreference sitereference The <operation> tag contains two mandatory elements, both of which are outlined in the following table. Secure Trading Limited April 2018 Page 9 / 73

10 Tag Type Length Required Comment operation Y accounttype description an 20 Y authmethod an 5 N The source of the transaction. For an e-commerce AUTH Request, the value should be ECOM. For Mail Order or Telephone Order (MOTO) requests, the value should be MOTO. For a recurring transaction, the value should be RECUR. Either PRE or FINAL. See section 11.1 for further details. (For split shipments, this must be set to PRE.) This is required for Visa and Mastercard transactions where the merchant is utilising the Credentials on File (CoF) feature. If the transaction is not eligible for CoF, or you do not wish to use credentials for future transactions, you can omit this field. The allowed values for this field are 0, 1, 2 and 3. 0 Not eligible for CoF, or no intention of reusing credentials at a later time. 1 Transaction credentials flagged as available for future use. 2 - A scheduled payment using previouslystored credentials.* 3 - An unscheduled payment using previously-stored credentials.* credentials onfile n 1 C *When submitting value 2 or 3, this requires a parent where the credentialsonfile value is 1. The CoF mandate only applies for new transactions processed after 30th April However, if you are storing credentials as part of your solution, we strongly recommend implementing the above ahead of the cut-off date, so you are ready when it comes into effect. Any CoF payments processed manually after 30th April 2018 (not processed using our subscription engine) must include the credentialsonfile field. Secure Trading Limited April 2018 Page 10 / 73

11 Tag Type Length Required Comment This is required when you are initiating a new child transaction using previouslystored Visa or Mastercard credentials. Allows you to assign a reason for re-using previously-stored credentials. As such, this field only needs to be submitted for unscheduled Merchant Initiated Transactions (MIT). This field can only be submitted with AUTH request types. The allowed values for this field are "A", "D", "L", "S", "T" and "X". initiation reason an 1 C "A" - Reauthorisation "D" - Delayed Charges "S" - Resubmission "T" - Account top up "X" - No-show (for a hotel booking) Note: Visa may introduce new values to this list in the future. For further information on these fields, please refer to Visa s own documentation. This field is only required for new CoF transactions processed after 30th April However, if you are storing credentials as part of your solution, we strongly recommend implementing the above ahead of the cut-off date, so you are ready when it comes into effect. parent transaction reference site reference an 25 N an 50 Y Here would be the reference of a previous transaction. This allows for inheritance (see section 1.3.5). You can use the parenttransactionreference element to perform an authorisation with a card that has previously been processed through your system (for more information, see section 2.2.9). If the currency is submitted in a child XML Request, it must be the same value as the parent transaction. The site reference relates to your individual account which you received on setup. If you do not know your Site Reference, please contact Support (see section 10.1). Secure Trading Limited April 2018 Page 11 / 73

12 2.2.3 <merchant> request type = AUTH merchant orderreference chargedescription operatorname As the <merchant> tag is not mandatory for a standard e-commerce Authorisation request, both its child elements are also optional. Tag Type Length Required Comment merchant N an 255 N The merchant s address. Maximum length of 255 (maximum of 64 characters before symbol). order reference an 255 N Your unique order reference that can be stored on Secure Trading s system. Note: This can be updated at a later time (only if transaction is pending settlement). Please refer to the Transaction Update document. This is a description of the payment that appears on the customer s bank statement. charge description an 25 N Only supported by certain acquiring banks. Specification of this field will depend on your acquiring bank. For further information, contact Support (10.1). Valid characters: Uppercase/lowercase A-Z Numbers 0-9 Spaces Punctuation: - ( ) operatorname an 255 N Refer to the Charge Description supplement for further information. The value of this field contains the name of the user that processed the request. This is optional. If omitted, the value of the alias will be recorded instead, which will either be your site reference or Web Services username, depending on your configuration. Secure Trading Limited April 2018 Page 12 / 73

13 2.2.4 <billing> The <billing> tag has two child tags in addition to nine elements. The child elements are <name> and <payment> and are outlined in sections and , respectively. The following diagram provides an overview of the <billing> tags: request type = AUTH billing premise street county country name payment postcode town amount currencycode= telephone type= Secure Trading recommends that you submit the <premise> and the <postcode> in the AUTH Request, as these fields are forwarded onto your acquiring bank to check that they match those that the card is registered against. Please refer to the AVS & CVV2 document for further information. Secure Trading Limited April 2018 Page 13 / 73

14 The fields included within the <billing> tags are outlined in the following table: Tag Type Length Required Comment billing Y premise an 25 N The house number or first line of the customer s billing address. street an 127 N The street entered for the customer s billing address. town an 127 N The town entered for the customer s billing address. county an 127 N The county entered for the customer s billing address (see section for validation information). country an 2 N The country for the customer s billing address. This will need to be in ISO2A format. For a list of country codes, see trycodes.html postcode an 25 N The postcode entered for the customer s billing address (see section for validation information). an 255 N The customer s billing address. Maximum length of 255 (maximum of 64 characters before symbol). amount currencycode= an 3 Y amount n 13 Y telephone type= an 1 N telephone an 20 N The currency that the transaction will be processed in. There is a list of available currencies on our website ( encycodes.html). The amount of the transaction should be in base units, with no commas or decimal points. e.g would be submitted as 1099 but 246 would be submitted as 246. This value must be greater than zero. (Max length may vary depending on your acquiring bank - Contact your bank for further info) The type of telephone number. The options available are: H = Home M = Mobile W = Work The customer s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: - ( ) Secure Trading Limited April 2018 Page 14 / 73

15 <name> request type = AUTH billing name prefix first middle last suffix All elements within the <name> tag are optional. The table below contains more information regarding the data that can be contained within these elements. It is imperative that the name details should match those on the card. Tag Type Length Required Comment billing Y name N prefix an 25 N The prefix of the customer s billing name (e.g. Mr,Miss,Dr). first an 127 N The customer s billing first name. middle an 127 N The customer s billing middle name(s). last an 127 N The customer s billing last name. suffix an 25 N The customer s suffix of the billing name (e.g. Bsc). Secure Trading Limited April 2018 Page 15 / 73

16 <payment> request type = AUTH billing payment pan expirydate securitycode The following table includes a breakdown of all the fields that are or can be included within the <payment> tags. Tag Type Length Required Comment billing Y payment type = an 20 Y pan n Y expirydate an 7 Y security code n 4 N The customer s card type, for example VISA or MASTERCARD. This is the card number printed on the front of the customer s card. The expiry date printed on the card. This needs to be submitted in the format MM/YYYY. These relate to the three (four for AMEX) digit security code, printed on the back of the card. This field is not a required field by STPP, although some banks do require it. Secure Trading recommends that you include the <securitycode> as it is submitted to your acquiring bank and then checked against the actual security code of the card to help prevent fraud. The result of this check is then returned to you in the XML Response (see section 2.3.6). Please refer to the AVS & CVV2 document for further information. Please note that Secure Trading will determine the payment type based on the pan. Secure Trading Limited April 2018 Page 16 / 73

17 2.2.5 <customer> request type= AUTH customer telephone type= forwardedip ip premise street county country postcode town name The <billing> tags include information on whoever is paying for the goods, while the <customer> tags are optional and include information of whoever is receiving the goods. In many cases, these are the same person, but not always. The <billing> tags are important because the address details are checked against the details of the card on authorisation, but the <customer> tags can also be used in additional fraud checks. The <customer> tag has a child <name> tag. The <name> tag contains elements in exactly the same format as those found in the <billing> tag, explained in section 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 the <customer> tag of AUTH and ACCOUNTCHECK XML Requests, if provided by the customer making the payment. Failure to submit these fields will result in a errorcode being returned in the response. Your MCC is a four-digit number assigned to you by your acquirer. It is used to classify the business by the type of products or services it provides. If you are unsure of the value of your merchant category code, please contact Secure Trading Support (section 10.1). Please refer to section 11.2 for further details and a full XML example. Secure Trading Limited April 2018 Page 17 / 73

18 Tag Type Length Required Comment customer N telephone type= an 1 N telephone an 20 N The type of telephone number. The options available are: H = Home M = Mobile W = Work The customer s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: - ( ) an 255 N The customer s address. forwardedip an 39 N Customer Forwarded IP address, as provided by a proxy server if available. ip an 39 N The IP of the customer. premise an 25 N The customer address premise (house name or number). street an 127 N The customer address street name. town an 127 N The town of the customer address. county an 127 N country an 2 N postcode an 25 C The customer county (see section for validation information). The country for the customer s billing address. This will need to be in ISO2A format. For a list of Country Codes, see trycodes.html Customer address postcode (see section for validation information). Only required if Merchant Category Code (MCC) is 6012 and payment type is VISA. See section 11.2 for more information. Secure Trading Limited April 2018 Page 18 / 73

19 2.2.6 <settlement> request type = AUTH settlement settlestatus settleduedate Settlement is a process that follows authorisation. Secure Trading submit a file to the acquiring bank, requesting that authorised funds are transferred into your bank account. You can defer these transactions if you wish by submitting a specific date in the settleduedate field. Please note that although you can specify when a payment is to be settled, (for example, 3 days after submitting the request), you cannot specify a date that is more than 7 days in the future (this limit is extended to 28 days for preauthorisations see section 11.1). The reason for this is that the authorisation for a transaction is no longer valid after seven days. Tag Type Length Required Comment settlement N settleduedate an 10 N Here you can set which day in the future you wish for your transaction to settle. It must be in the format YYYY-MM-DD. settlestatus n 3 N A numeric value used to define the settlement instruction. See section for a full list of values that can be submitted in this field Settlement instructions You can submit the following values in the settlement/settlestatus element. Providing the transaction is authorised successfully, the settle status submitted is used to determine how the transaction will be settled. Settle status Outcome Automatic (default value when element is not submitted): The transaction will be scheduled for settlement in the next settlement run. If enabled, fraud and duplicate checks (1) are run prior to settlement and will suspend any transactions where problems have been raised. Manual: The transaction will be scheduled for settlement in the next settlement run. Fraud and duplicate checks are not performed. Suspended: The transaction will be held in a suspended state until updated (2). Transactions not actioned within 7 days are automatically cancelled. This limit is extended to 28 days for pre-authorisations (see section 11.1). Settled (3) (only supported by certain acquiring banks): Following successful authorisation, the transaction is settled immediately. (1) Refer to the Fraud checks document for further information. (2) Refer to section 11.5 for further information on all possible transaction states. (3) Please contact Support to find out if your acquiring bank supports immediate settlement. Secure Trading Limited April 2018 Page 19 / 73

20 2.2.7 Additional Validation <postcode> If included within the request, validation is performed on the postcode. Please note that postcode validation is dependent on the country supplied. If no country is supplied, then no additional validation is performed. The following table outlines the format the postcode needs to be in when it is submitted to Secure Trading. T represents Text (A-Z or a-z) and N represents Number (0-9): Country United States (US) Great Britain (GB) Canada (CA) Other Validation Needs to be a 5 or 9 digit zip code. Needs to be between 6 and 8 characters long, including spaces. Can be one of the following formats: TN NTT TNT NTT TNN NTT TTN NTT TTNN NTT TTNT NTT Needs to be 6 or 7 digits long, including spaces. Can be one of the following formats: TNT NTN TNTNTN The format of postcodes for other countries is not validated by Secure Trading <county> If the country is entered and is United States (US), the county field needs to be a valid twodigit state code (e.g. NY for New York). For a list of US state codes, see: Secure Trading Limited April 2018 Page 20 / 73

21 2.2.8 AUTH XML Request Example The following is an example of an AUTH XML Request. <requestblock version="3.67"> <alias>site12345</alias> <request type="auth"> <merchant> <orderreference>auth_visa</orderreference> <operatorname>name of operator</operatorname> </merchant> <customer> <town>bangor</town> <name> <middle>mary</middle> <prefix>miss</prefix> <last>smith</last> <first>joanne</first> </name> <ip> </ip> <telephone type="h"> </telephone> <street>second Street</street> <postcode>cu888st</postcode> <premise>111</premise> </customer> <billing> <telephone type="m"> </telephone> <county>gwynedd</county> <street>test Street</street> <postcode>te45 6ST</postcode> <premise>789</premise> <payment type="visa"> <expirydate>10/2031</expirydate> <pan> </pan> <securitycode>123</securitycode> </payment> <town>bangor</town> <name> <prefix>miss</prefix> <first>zöe</first> <last>bloggs</last> </name> <country>gb</country> <amount currencycode="gbp">100</amount> </billing> <operation> <sitereference>site12345</sitereference> <accounttypedescription>ecom</accounttypedescription> </operation> </request> </requestblock> Secure Trading Limited April 2018 Page 21 / 73

22 2.2.9 Repeat Payments (Tokenisation) Using inheritance (see section 1.3.5), you can easily perform repeat payments that retain all billing and customer fields (including card details, with the exception of the security code) from an initial payment, meaning that you do not need to keep resubmitting the same fields Processing the initial payment Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use (e.g. by a Subscription or by processing a re-authorisation). Following this, you must appropriately identify credentials that are to be stored for later, by submitting an extra field in your requests. This field is as follows: credentialsonfile Submit this with a value of 1, which indicates you plan on using these credentials in a future transaction. The CoF mandate only applies for new transactions processed after 30th April However, if you are storing credentials as part of your solution, we strongly recommend implementing this ahead of the cut-off date, so you are ready when it comes into effect. Any CoF payments processed manually after 30th April 2018 (not processed using our subscription engine) must include the credentialsonfile field. Please refer to the following example, with the credentialsonfile field highlighted in bold: <requestblock version="3.67"> <alias>site12345</alias> <request type="auth"> <merchant> <orderreference>auth_visa</orderreference> <operatorname>name of operator</operatorname> </merchant> <billing> <postcode>te45 6ST</postcode> <premise>789</premise> <payment type="visa"> <expirydate>10/2031</expirydate> <pan> </pan> <securitycode>123</securitycode> </payment> <amount currencycode="gbp">100</amount> </billing> <operation> <sitereference>site12345</sitereference> <accounttypedescription>ecom</accounttypedescription> <credentialsonfile>1</credentialsonfile> </operation> </request> Please turn over for information on processing the repeat payment using Visa Credentials on File (CoF). Secure Trading Limited April 2018 Page 22 / 73

23 Processing the repeat payment This section assumes you have previously processed an AUTH request, and are using these stored credentials in order to process a subsequent payment. You will need to include a reference to this in the repeat payment request (as highlighted in the example below). If the parent response indicates an error occurred (error/code 0 ), the credential cannot be considered a stored credential, and you must not use these card details in any subsequent payments. When processing an AUTH using previously-stored payment credentials, you will need to pass through the credentialsonfile field: credentialsonfile This can be one of the following values: o 2 - indicating a scheduled payment (e.g. a regular subscription payment). o 3 - indicating an unscheduled payment. If the repeat payment is an unscheduled Merchant Initiated Transaction (MIT), you will need to submit the initiationreason field, along with a value indicating the reason this new transaction is being processed. If the repeat payment is a Customer Initiated Transaction (CIT), this field is not required. initiationreason The reason for processing this request: o "A" Re-authorisation o "D" - Delayed Charges o "S" - Resubmission o "T" - Account top up o "X" - No-show (for a hotel booking) Visa may introduce new initiationreason values to this list in the future. For further information on these fields, please refer to Visa s own documentation. The information above, on credentialsonfile and initiationreason fields, is only mandatory after 30th April It applies even if the parent AUTH was processed before the mandate came into effect. We strongly recommend implementing the above ahead of the cut-off date, so you are ready when it comes into effect. Please refer to the following example, with both credentialsonfile and initiationreason fields highlighted in bold: <?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>test_site12345</alias> <request type="auth"> <merchant> <orderreference>myorder123</orderreference> <operatorname>operator name</operatorname> </merchant> <billing> <amount currencycode="gbp">1000</amount> </billing> <operation> <initiationreason>s</initiationreason> <parenttransactionreference> </parenttransactionreference> <sitereference>test_site12345</sitereference> <credentialsonfile>3</credentialsonfile> <accounttypedescription>ecom</accounttypedescription> </operation> </request> </requestblock> Secure Trading Limited April 2018 Page 23 / 73

24 Further examples Processing a repeat payment with a new delivery address This example will perform a repeat payment, with an updated delivery address: <requestblock version="3.67"> <alias>site12345</alias> <request type="auth"> <customer> <premise>111</premise> <street>second Street</street> <town>bangor</town> <county>gwynedd</county> <country>gb</country> <postcode>cu888st</postcode> </customer> <operation> <initiationreason>s</initiationreason> <parenttransactionreference>1-2-3</parenttransactionreference> <sitereference>site12345</sitereference> <credentialsonfile>3</credentialsonfile> <accounttypedescription>ecom</accounttypedescription> </operation> </request> </requestblock> The billing address cannot be partially inherited. If you are updating the billing address, you must submit the new address in full. If you wish to inherit the billing address details you must leave the billing address fields blank in any child request that you submit. Note: The same applies to the customer address fields. Processing a repeat payment with the security code Secure Trading will never store card security codes. As such, repeat payments cannot inherit a card s security code, resulting in the security code response to be 0 (Not Given). You can opt to submit the security code on repeat payments in order to pass this check, as follows: Important: You must NEVER store card security codes. The customer must re-enter their security code on your website when processing a repeat payment. <requestblock version="3.67"> <alias>site12345</alias> <request type="auth"> <billing> <payment> <securitycode>123</securitycode> </payment> </billing> <operation> <initiationreason>s</initiationreason> <parenttransactionreference>1-2-3</parenttransactionreference> <sitereference>site12345</sitereference> <credentialsonfile>3</credentialsonfile> <accounttypedescription>ecom</accounttypedescription> </operation> </request> </requestblock> Secure Trading Limited April 2018 Page 24 / 73

25 2.3 AUTH XML Response Following processing an Authorisation (AUTH) XML Request, Secure Trading will return an AUTH XML Response. The XML will be made up of the tags outlined within this section of the document. The fields are based on that of a successful response, not an error or a decline AUTH XML Response Overview requestreference secrand response type = AUTH authcode timestamp live transactionreference merchant security settlement billing operation error acquirerresponsecode acquirerresponsemessage The responseblock returned will contain two elements (requestreference and secrand) and a response type = AUTH tag <requestreference> This is an internal field generated by Secure Trading. It must not be validated. If problems are experienced with the request this field may be requested by Secure Trading support to aid in determining the cause. (Maximum length of the requestreference field is 25) <secrand> Random string of characters added to the response for security purposes. (secrand has a variable length of 1-16) Secure Trading Limited April 2018 Page 25 / 73

26 2.3.4 <response type = AUTH > This tag contains six elements (without child tags), the details of which are in the following table. There are also an additional six tags that contain further child tags, outlined in greater detail after the table. Tag Type Length Required Comment authcode an 255 Y The authorisation code provided by the Issuing Bank, this is generated by the Issuing Bank, and will differ pending on which bank you use. timestamp an 19 Y The timestamp relates to the time of the individual transaction. It will be in the format: :00:00 live n 1 Y This will indicate if the account is live or in test. If the transaction was a live one, it will return a 1, whereas for test transactions the value will be a 0. A unique Secure Trading reference for the transaction. You will need to store this if you wish transaction to perform any additional request reference an 25 Y such as a refund on the transaction. Additionally, it can then be used for any future correspondence with Secure Trading. acquirerresponse code acquirerresponse message an 255 C an 255 C This will only be returned if supplied by the merchant s Acquirer. The corresponding message to the above code. Will only be returned if supplied by the merchant s acquirer. Secure Trading Limited April 2018 Page 26 / 73

27 2.3.5 <merchant> response type = AUTH merchant merchantnumber orderreference tid merchantcategorycode merchantname merchantcity merchantstatecode merchantzipcode merchantcountryiso2a chargedescription operatorname Secure Trading Limited April 2018 Page 27 / 73

28 The following fields can be returned in the <merchant> tag: Tag Type Length Required Comment merchant Y merchant number order reference an 32 Y an 255 N tid an 255 N merchant categorycode merchant name merchant city merchant state code merchant zipcode merchant countryiso2a charge description an 255 N an 255 N an 127 N an 127 N an 10 N an 2 N an Max length 25 operatorname an 255 Y N The Merchant Number that was used to process the transaction. Provided by the acquiring bank. This will match the order reference supplied within your initial request. The Terminal ID used to process the transaction, this is accredited to your merchant number when we setup your account in our systems. The merchant category code that was used to process the AUTH. The merchant name that was used to process the AUTH. The merchant city that was used to process the AUTH (if applicable). The merchant state code that was used to process the AUTH (if applicable). The merchant zip/post code that was used to process the AUTH (if applicable). The merchant country that was used to process the AUTH (if applicable). The description of the payment that appears on the customer s bank statement (Only supported by certain acquiring banks). The value is determined by the XML Request and your account configuration (refer to the Charge Description supplement for further information). The value of this field contains the name of the user that processed the request. If this was omitted from the request, the value returned will either be your site reference or Web Services username, depending on your configuration. Secure Trading Limited April 2018 Page 28 / 73

29 2.3.6 <security> response type = AUTH security address postcode securitycode The <security> tags within an XML Response provide the results of checks performed by your acquiring bank on the customer s address and security code. Please refer to the AVS & CVV2 document for further information. These are the child elements returned in the <security> tag, in the XML Response: Tag Type Length Required Comment security Y address n 1 Y The result of the Address Verification System checks performed on authorisation. postcode n 1 Y The result of the postcode check performed on authorisation. securitycode n 1 Y The result of the security code check performed on authorisation. The security responses follow this key: Security responses Description Comment 0 Not Given Your system did not provide the acquiring bank the information required to perform this check, in the XML Request. 1 Not Checked The acquiring bank did not perform this check on the information you provided in the XML Request. 2 Matched The information you provided in the XML Request, matches the information obtained by the acquiring bank, from the customer s payment issuer. 4 Not Matched The information you provided in the XML Request, does not match the information obtained by the acquiring bank, from the customer s payment issuer. When interpreting the response, you may prefer to suspend transactions that include a security response that doesn t meet an acceptable standard for your business. Please consider the full list of security responses shown above and ensure your system proceeds in such a way that is most appropriate for your solution in each possible scenario ( matched, not matched, etc.). For example, your system could be configured to suspend when a postcode has a value of 0 ( not given ), indicating that the customer did not enter a billing postcode when checking out on your website. An especially important field to consider is the security/securitycode field. A value of 4 here indicates a not matched security code. i.e. The code entered by the customer did not match the value found on the back of their card. Secure Trading automatically suspends such transactions by default as part of your account s security policy. Secure Trading Limited April 2018 Page 29 / 73

30 2.3.7 <settlement> response type = AUTH settlement settleduedate settlestatus The <settlement> tag will contain information detailing the status of a transaction with the settlement date. Tag Type Length Required Comment settlement Y settleduedate an 10 Y The date the transaction is due to settle. This is only relevant if the settlestatus is 0 or 1. Will be in the format YYYY-MM-DD. settlestatus n 3 Y The current status of transaction at the end of the request. See section 11.5 for a list of possible values. Secure Trading Limited April 2018 Page 30 / 73

31 2.3.8 <billing> response type = AUTH billing payment type= issuercountry amount currencycode= pan dccenabled= issuer The billing tags returned will include the transaction type supplied within the original authorisation. Tag Type Length Required Comment billing Y payment The type of payment processed, for type= an 20 Y example VISA or MASTERCARD. issuer country issuer an 2 Y an 255 C pan an Y amount currencycode= an 3 Y amount n 13 Y dccenabled= n 1 Y The country for the customer s card issuer. This will be in ISO2A format. For a list of Country Codes, see trycodes.html. This will be returned if the data is available. The customer s card issuer. This will be returned if the data is available. The first six and last four digits of the card. The rest of the card details are not shown and obscured with #. For example ######0211. The currency that the transaction was processed in. There is a list of available currencies on our website ( encycodes.html) The amount of the transaction in base units, with no commas or decimal points. e.g is returned as is returned as 246 (Max length may vary depending on your acquiring bank - Contact your bank for further info) Indicates if the transaction was processed using DCC or not. 1= Yes 0 = No Refer to the DCC document for further information. Secure Trading Limited April 2018 Page 31 / 73

32 2.3.9 <operation> response type = AUTH operation accounttypedescription authmethod For a standard e-commerce authorisation, the operation tags returned will include the account type specified in the Authorisation Response. Tag Type Length Required Comment operation Y accounttype description an 20 Y authmethod an 5 N This will match the account type description supplied within the request (e.g. ECOM ). Either PRE or FINAL. See section 11.1 for further information. Only returned if a value was sent to the acquirer by Secure Trading during authorisation. This is returned in the response when submitted in the request, when supported by your acquiring bank. The possible values that can be returned are 0, 1, 2 or 3: credentials onfile n 1 C 0 Not eligible for CoF, or no intention of re-using credentials at a later time. 1 - Intending to re-use these credentials in a future transaction 2 - A scheduled payment using previously-stored credentials 3 - An unscheduled payment using previously-stored credentials Secure Trading Limited April 2018 Page 32 / 73

33 <error> response type = AUTH error code message 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. An error code of represents an unknown error that can happen during a request and requires manual investigation to determine the state of the transaction. Please contact Secure Trading Support (see section 10.1). For a full list of error codes and error messages please see: Tag Type Length Required Comment error Y code n 5 Y The code will be 0 if the transaction was successful. message an 255 Y This is the corresponding message to the above code. Additional information to help troubleshoot the error. data an 255 N This tag contains one or more child elements. If the error code is (Field Error) then this field will contain the field (or fields) which caused the error <other> The <other> tag may appear in the XML Response. The contents of the <other> tag are undefined and can be ignored unless specified otherwise by Secure Trading and your acquirer, for a specific reason. Please allow for any number of elements to be returned in the <other> tag, containing any length of data. Secure Trading Limited April 2018 Page 33 / 73

34 AUTH XML Response Example The following is an example of an AUTH XML Response. <responseblock version="3.67"> <requestreference>x6mh36u8g</requestreference> <response type="auth"> <merchant> <merchantname>example UNICODE merchantname</merchantname> <orderreference>auth_visa</orderreference> <tid> </tid> <merchantnumber> </merchantnumber> <merchantcountryiso2a>gb</merchantcountryiso2a> <operatorname>name of operator</operatorname> </merchant> <transactionreference>17-9-5</transactionreference> <security> <postcode>2</postcode> <securitycode>2</securitycode> <address>2</address> </security> <billing> <amount currencycode="gbp">100</amount> <payment type="visa"> <issuer>test Issuer</issuer> <issuercountry>zz</issuercountry> <pan>411111######0211</pan> </payment> <dcc enabled="0"/> </billing> <authcode>test</authcode> <timestamp> :46:02</timestamp> <settlement> <settleduedate> </settleduedate> <settlestatus>0</settlestatus> </settlement> <live>0</live> <error> <message>ok</message> <code>0</code> </error> <acquirerresponsecode>00</acquirerresponsecode> <operation> <accounttypedescription>ecom</accounttypedescription> </operation> </response> <secrand>hywfmkiiaz0wkhfz</secrand> </responseblock> Secure Trading Limited April 2018 Page 34 / 73

35 3 Refund 3.1 Process Overview This section of the document will provide an overview of the process of performing a refund and a breakdown of the parties affected. This can be summarised in the following diagram: M E R C H A N T Merchant opts to perform a refund A C Q U I R I N G B A N K C A R D I S S U E R Merchant submits an REFUND XML Request to Secure Trading. Secure Trading validates the request and forwards the details to the acquiring bank using a secure connection. See section 3.2 The acquiring bank will contact the card issuer. The acquiring bank will respond to Secure Trading with details of the refund. The customer s card issuer receives the request. A decision is made to issue a refund and submit a response to the acquiring bank. Secure Trading interprets the response from the acquiring bank. Then returns an XML Response to the merchant. Merchant receives a REFUND XML Response from Secure Trading and interprets this response. See section 3.3 The merchant stores this response in their system for future reference. See section 7 Secure Trading Limited April 2018 Page 35 / 73

36 3.1.1 Pre-Requisites The following criteria must be met in order for refunds to be processed: The transaction being refunded must be settled (in settle status 100 ). You cannot refund a greater amount than was originally settled. The payment details must still be valid (e.g. the card can t be beyond its expiry date 1 ). 1 Please note that if the customer s card has expired, an updated expiry date can be submitted in the XML Request in order to perform the refund. However, you cannot process the refund using a different PAN using this request. 3.2 REFUND XML Request In order to successfully process a Refund Request, the XML submitted by the merchant to the Secure Trading must follow the formatting outlined in this section of the document REFUND XML Request Overview The following is an overview of an XML Refund Request: alias request type = REFUND operation merchant billing Secure Trading Limited April 2018 Page 36 / 73

37 3.2.2 <merchant> request type = REFUND merchant orderreference chargedescription operatorname Tag Type Length Required Comment merchant N an 255 N The merchant s address. Maximum length of 255 (maximum of 64 characters before symbol). Your unique order reference that can be stored on Secure Trading s system. order reference an 255 N If this is not submitted, it is inherited from the initial authorisation. Note: This can be updated at a later time (only if transaction is pending settlement). Please refer to the document. This is a description of the payment that appears on the customer s bank statement. charge description an Max length 25 N Only supported by certain acquiring banks. Specification of this field will depend on your acquiring bank. For further information, contact Support (10.1). Valid characters: Uppercase/lowercase A-Z Numbers 0-9 Spaces Punctuation: - ( ) operatorname an 255 N Refer to the Charge Description supplement for further information. The value of this field contains the name of the user that processed the request. This is optional. If omitted, the value of the alias will be recorded instead, which will either be your site reference or Web Services username, depending on your configuration. Secure Trading Limited April 2018 Page 37 / 73

38 3.2.3 <operation> request type = REFUND operation accounttypedescription parenttransactionreference sitereference Tag Type Length Required Comment operation Y accounttype description parent transaction reference an 20 Y an 25 Y sitereference an 50 Y This will match the account type description supplied within the original authorisation. This field must contain the transaction reference of the authorised transaction that you wish to refund (using inheritance; see section 1.3.5). The site reference relates to your individual account which you will receive on setup. If you do not know your Site Reference, please contact Secure Trading Support (see section 10.1). Secure Trading allows merchants to perform CFT refunds (Cardholder Funds Transfer). Please refer to section 4 for further information. The site reference submitted in the REFUND Request should be the same as the site reference used to process the original parent AUTH Request. Secure Trading Limited April 2018 Page 38 / 73

39 3.2.4 <billing> billing amount currencycode = payment expirydate Tag Type Length Required Comment billing an 3 N The refund amount in base units, with no commas or decimal points. e.g would be submitted as 1099 but 246 would be submitted as 246. You cannot refund more than the settle amount of the AUTH being refunded. amount n 13 N You can opt to perform a partial refund by submitting a lower amount here. Please see section for an example of a partial refund request. amount currencycode= an 3 N If this field is not present then the full amount of the transaction will be refunded. (Max length of amount may vary depending on your acquiring bank - Contact your bank for further info) The currency that the refund will be processed in. Note: This field is optional, but if included, it must be the same as the currency used in the original AUTH. payment expirydate an 7 N N There is a list of available currencies on our website ( encycodes.html). If you would like to process a refund with an updated expiry date, the new value is submitted in this element. Please see section for an example of a REFUND XML Request that utilises this element. Secure Trading Limited April 2018 Page 39 / 73

40 3.2.5 REFUND XML Request Example Full refund The following example REFUND XML Request performs a full refund on the specified AUTH: <requestblock version="3.67"> <alias>site12345</alias> <request type="refund"> <merchant> <orderreference>refund_visa</orderreference> </merchant> <operation> <sitereference>site12345</sitereference> <parenttransactionreference>17-9-5</parenttransactionreference> </operation> </request> </requestblock> Partial refund The following example REFUND XML Request performs a partial refund on the specified AUTH. You can specify the amount to be refunded in the billing/amount element, highlighted in bold, below: <requestblock version="3.67"> <alias>site12345</alias> <request type="refund"> <merchant> <orderreference>refund_visa</orderreference> </merchant> <billing> <amount>100</amount> </billing> <operation> <sitereference>site12345</sitereference> <parenttransactionreference>17-9-5</parenttransactionreference> </operation> </request> </requestblock> Secure Trading Limited April 2018 Page 40 / 73

41 Refund with new expiry date The following example REFUND XML Request performs a full refund on the specified AUTH, using a new card expiry date. The new expiry date is submitted in the billing/payment/expirydate element, as highlighted in bold in the example below: <requestblock version="3.67"> <alias>site12345</alias> <request type="refund"> <merchant> <orderreference>refund_visa</orderreference> </merchant> <billing> <payment> <expirydate>10/2020</expirydate> </payment> </billing> <operation> <sitereference>site12345</sitereference> <parenttransactionreference>17-9-5</parenttransactionreference> </operation> </request> </requestblock> Secure Trading Limited April 2018 Page 41 / 73

42 3.3 REFUND XML Response In this section of the document is a breakdown of the XML Response for a Refund Request that will be received by the merchant. The fields are based on that of a successful response, not an error or a declined refund REFUND XML Response Overview The following is a diagrammatic representation of the XML Response to a REFUND Request. requestreference secrand response type = REFUND authcode timestamp live transactionreference merchant security settlement billing operation error The responseblock returned will contain two elements (requestreference and secrand) and a response type = REFUND tag <requestreference> This is an internal field generated by Secure Trading. It must not be validated. If problems are experienced with the request this field may be requested by Secure Trading support to aid in determining the cause. (Maximum length of the requestreference field is 25) <secrand> Random string of characters added to the response for security purposes. (secrand has a variable length of 1-16) Secure Trading Limited April 2018 Page 42 / 73

43 3.3.4 <response type = REFUND > This tag contains four elements (without child tags), the details of which are in the following table. There are also an additional six tags that contain further child tags, outlined in greater detail after the table. Tag Type Length Required Comment authcode an 255 Y Authorisation code if provided by the acquirer. timestamp an 19 Y The timestamp relates to the time of the individual transaction. It will be in the format: :00:00 live n 1 Y 0 equals test transaction, 1 equals live transaction. transaction A unique Secure Trading reference for reference an 25 Y the transaction <merchant> response type = REFUND merchant merchantnumber orderreference tid chargedescription operatorname The following fields can be returned within the merchant tag: Tag Type Length Required Comment merchant Y merchant number order reference an 32 Y an 255 N tid an 255 N charge description an Max length 25 operatorname an 255 Y N This will be the merchant number that has been provided to Secure Trading to process on-line transactions on your account. This will match the order reference supplied within your initial request. The Terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems. The description of the refund appears on the customer s bank statement (Only supported by certain acquiring banks). The value is determined by the XML Request and your account configuration (refer to the Charge Description supplement for further information). The value of this field contains the name of the user that processed the request. If this was omitted from the request, the value returned will either be your site reference or Web Services username, depending on your configuration. Secure Trading Limited April 2018 Page 43 / 73

44 3.3.6 <billing> response type = REFUND billing payment type= issuercountry amount currencycode= pan dccenabled= issuer The <billing> tags returned will include the transaction type supplied within the original authorisation. Tag Type Length Required Comment billing Y payment The type of payment processed, for type= an 20 Y example VISA or MASTERCARD. issuer country issuer an 2 Y an 255 C pan an Y amount currencycode= an 3 Y amount n 13 Y dccenabled= n 1 Y <security> The country for the customer s card issuer address. This will need to be in ISO2A format. For a list of Country Codes, see trycodes.html. This will be returned if the data is available. The issuer for the customer s card. This will be returned if the data is available. The first six and last four digits of the card that was refunded. The rest of the card details are not shown and obscured with #. For example ######0211. The currency that the refund was processed in. There is a list of available currencies on our website ( encycodes.html) The amount refunded in base units, with no commas or decimal points. e.g is returned as is returned as 246 (Max length may vary depending on your acquiring bank - Contact your bank for further info) Indicates if the transaction was processed using DCC or not. 1= Yes 0 = No Refer to the DCC document for further information. These tags follow the same convention as those outlined in section <security>. For refunds, they will most likely be a 0 for each check as the details aren t usually submitted for refunds. Secure Trading Limited April 2018 Page 44 / 73

45 3.3.8 <settlement> response type = REFUND settlement settleduedate settlestatus Tag Type Length Required Comment settlement Y settleduedate an 10 Y The date that the transaction is due to settle. Will be in the format YYYY-MM-DD. settlestatus an 3 Y The current settle status of transaction at the end of the request. See section 11.5 for a list of possible values <operation> response type = REFUND operation accounttypedescription parenttransactionreference Tag Type Length Required Comment operation Y accounttype description parent transaction reference an 20 Y an 25 Y This will match the account type description supplied within the request ECOM. A unique Secure Trading reference for the parent transaction. Within a Refund Response, this relates to the transaction you have refunded. Secure Trading Limited April 2018 Page 45 / 73

46 <error> response type = REFUND error code message The error code should be used to determine if the individual requests were 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. An error code of represents an unknown error that can happen during a request and requires manual investigation to determine the state of the transaction. Please contact Secure Trading Support (see section 10.1). For a full list of error codes and error messages please see: Tag Type Length Required Comment error Y code n 5 Y The code will be 0 if the refund was processed successfully. message an 255 Y This is the corresponding message to the above code. Additional information to help troubleshoot the error. data an 255 N This tag contains one or more child elements. If the error code is (Field Error) then this field will contain the field (or fields) which caused the error. Secure Trading Limited April 2018 Page 46 / 73

47 REFUND XML Response Example The following is an example XML of a REFUND Response: <responseblock version="3.67"> <requestreference>xk3mvyk5v</requestreference> <response type="refund"> <merchant> <merchantname>example UNICODE merchantname</merchantname> <orderreference>refund_visa</orderreference> <tid> </tid> <merchantnumber> </merchantnumber> <merchantcountryiso2a>gb</merchantcountryiso2a> <operatorname>name of operator</operatorname> </merchant> <transactionreference> </transactionreference> <billing> <amount currencycode="gbp">100</amount> <payment type="visa"> <issuer>test Issuer</issuer> <issuercountry>zz</issuercountry> <pan>411111######0211</pan> </payment> <dcc enabled="0"/> </billing> <authcode>test REFUND ACCEPTED</authcode> <live>0</live> <error> <message>ok</message> <code>0</code> </error> <timestamp> :46:11</timestamp> <acquirerresponsecode>00</acquirerresponsecode> <security> <address>2</address> <postcode>2</postcode> <securitycode>0</securitycode> </security> <settlement> <settleduedate> </settleduedate> <settlestatus>0</settlestatus> </settlement> <operation> <parenttransactionreference>17-9-5</parenttransactionreference> <accounttypedescription>ecom</accounttypedescription> </operation> </response> <secrand>f</secrand> </responseblock> Secure Trading Limited April 2018 Page 47 / 73

48 4 CFT Refunds CFT Refunds are similar to standard refunds (see section 3), except they can be performed without referring to an original authorisation. This means that the amount can be greater than the original payment, if required. 4.1 Requirements You will need to have a CFT merchant number associated with your Secure Trading account. Please check you are following any guidelines outlined by your bank before proceeding. If your merchant number category code is 4829 or 6012, you will not be permitted to process CFT refunds. 4.2 CFT REFUND XML Request The XML Request required to process a CFT refund is the same as a standard refund request, except for the following differences: The value associated within the operation/accounttypedescription element must be CFT. You are not required to include the operation/parenttransactionreference element. If omitted, you will need to include the card details and amount in order to process the payment (see section 4.2.2). If the parenttransactionreference is included, the card details are not required to be submitted, however if they are included they must be the same as those used in the original payment (see section 4.2.1). See the next page for XML examples. Secure Trading Limited April 2018 Page 48 / 73

49 4.2.1 XML example using parent transaction reference <requestblock version="3.67"> <alias>site12345</alias> <request type="refund"> <operation> <sitereference>site12345</sitereference> <accounttypedescription>cft</accounttypedescription> <parenttransactionreference>1-2-3</parenttransactionreference> </operation> </request> </requestblock> XML example without parent transaction reference <requestblock version="3.67"> <alias>site12345</alias> <request type="refund"> <billing> <payment type="visa"> <expirydate>10/2031</expirydate> <pan> </pan> <securitycode>123</securitycode> </payment> <amount currencycode="gbp">100</amount> </billing> <operation> <sitereference>site12345</sitereference> <accounttypedescription>cft</accounttypedescription> </operation> </request> </requestblock> 4.3 CFT REFUND XML Response The response returned is similar to the Refund XML Response shown in section , except the operation/accounttypedescription element is CFT. Secure Trading Limited April 2018 Page 49 / 73

50 5 Account Check 5.1 Process Overview An Account Check Request allows a card to be validated by checking the cardholder s first line of address, the cardholder s postcode and the security code (CVV2), to ensure the details entered by the customer are valid. Account Checks are only available for certain acquiring banks. Please contact Secure Trading Support for further details (see section 10.1). The following is an overview of performing an Account Check through STPP: M E R C H A N T A C Q U I R I N G B A N K C A R D I S S U E R Merchant opts to perform Account Check Merchant submits an ACCOUNTCHECK XML Request to Secure Trading. Secure Trading validates the request and forwards the details to the acquiring bank using a secure connection. See section 5.2 The acquiring bank will contact the card issuer to perform checks on the customer s payment details. The card issuer performs various checks (including AVS and CVV2). The acquiring bank retrieves information from the card issuer and returns this to Secure Trading. Merchant receives an ACCOUNTCHECK XML Response from Secure Trading and interprets this response. Secure Trading interprets the response from the acquiring bank. Then returns an XML Response to the merchant. See section 5.3 The merchant stores this response in their system for future reference. See section 7 Secure Trading Limited April 2018 Page 50 / 73

51 5.2 ACCOUNTCHECK XML Request The XML Request for an Account Check is similar to a normal Authorisation Request (see section 2.2). Please note that the checks performed on an Account Check Request are the same as those carried out on a regular e-commerce Authorisation (AUTH) Request. With the difference being that no funds will be reserved as part of an Account Check <request type = ACCOUNTCHECK > The request type for an Account Check Request is ACCOUNTCHECK <billing> In the <billing> tag, your system can submit the same fields as in a standard AUTH XML Request (as described in section 2.2.4). Tag Type Length Required Comment billing Y premise an 25 N The house number or first line of the customer s billing address. postcode an 25 N The postcode entered for the customer s billing address. amount currencycode= an 3 Y amount n 13 Y About the billing premise and postcode The currency that the transaction will be processed in. There is a list of available currencies on our website ( encycodes.html). This can either be 0 or a value in base units, with no commas or decimal points. See below for further information. (Max length may vary depending on your acquiring bank - Contact your bank for further info) In order for AVS checks to be performed, the billing premise and postcode elements need to be submitted in the ACCOUNTCHECK XML Request About the amount The amount for an Account Check can be 0. If a value greater than 0 is sent in the request, it will be stored and can be inherited in subsequent requests, such as future Authorisations (although you can submit a new amount in an inheriting Authorisation Request). This functionality is discussed in section Please note that if an amount of 0 is submitted in an Account Check Request, you must submit a new non-zero amount in inheriting requests. An Authorisation Request must be for a non-zero amount. No funds will be reserved or transferred by the Account Check Request. Secure Trading Limited April 2018 Page 51 / 73

52 <payment> Within the <billing> tag, your system is required to include the following card information: Tag Type Length Required Comment billing Y payment The customer s card type, for type = an 20 Y example VISA or MASTERCARD. pan n Y This is the card number printed on the front of the customer s card. The expiry date printed on the card. expirydate an 7 Y security code n 4 N This needs to be submitted in the format MM/YYYY. These relate to the three (four for AMEX) digit security code, printed on the back of the card. Although not required, this field is necessary for security code checks to be performed as part of the Account Check. Please note that if your system submits a settlestatus in an ACCOUNTCHECK XML Request, this will be inherited by any subsequent child requests. It has no effect on the outcome of an Account Check. Secure Trading Limited April 2018 Page 52 / 73

53 5.2.3 ACCOUNTCHECK XML Request Example The following is an example ACCOUNTCHECK XML Request. For all checks to be performed, please ensure your system submits the fields highlighted in bold. Before you begin testing Account Checks, please contact Secure Trading Support (see section 10.1) and ensure your acquiring bank supports this functionality. 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 the <customer> tag of AUTH and ACCOUNTCHECK XML Requests, if provided by the customer making the payment. Failure to submit these fields will result in a errorcode being returned in the response. Your MCC is a four-digit number assigned to you by your acquirer. It is used to classify the business by the type of products or services it provides. If you are unsure of the value of your merchant category code, please contact Secure Trading Support (section 10.1). Please refer to section 11.2 for further details and a full XML example. <?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>site12345</alias> <request type="accountcheck"> <billing> <country>gb</country> <amount currencycode="gbp">0</amount> <postcode>te45 6ST</postcode> <premise>789</premise> <payment type="visa"> <pan> </pan> <securitycode>123</securitycode> <expirydate>10/2031</expirydate> </payment> </billing> <operation> <accounttypedescription>ecom</accounttypedescription> <sitereference>site12345</sitereference> </operation> </request> </requestblock> Secure Trading Limited April 2018 Page 53 / 73

54 5.3 ACCOUNTCHECK XML Response The response for an Account Check is the same as a normal Authorisation (see section 2.3), with the exception of the response type being ACCOUNTCHECK. It is strongly recommended that you check the <security> fields returned in the XML Response, and discontinue further transactions with the customer, if the security code entered does not match the one expected by the acquiring bank (returns a 4). The results of the checks performed are returned in the security response of the Account Check (in the <security> tag). The security response consists of three different fields, each containing the result of an individual check. The names of the fields are listed, below: Tag Type Length Required Comment security Y address n 1 Y The result of the address check performed. postcode n 1 Y The result of the postcode check performed. securitycode n 1 Y The result of the security code check performed. An Account Check Request will analyse the details provided by the customer and respond with the following results for each check performed: Security responses Description Comment 0 Not Given Your system did not provide the acquiring bank the information required to perform this check, in the XML Request. 1 Not Checked The acquiring bank did not perform this check on the information you provided in the XML Request. 2 Matched The information you provided in the XML Request, matches the information obtained by the acquiring bank, from the customer s payment issuer. 4 Not Matched The information you provided in the XML Request, does not match the information obtained by the acquiring bank, from the customer s payment issuer. For example, the XML Response may return a security response with the values shown in the following table: Field name Value security/address 2 security/postcode 2 security/securitycode 4 This would indicate that the first line of the address and the postcode match those on the card issuer s records, but the security code (CVV2) entered by the customer does not match the details held by the customer s card issuer. Secure Trading Limited April 2018 Page 54 / 73

55 Alternatively, you can view security responses in the Single Transaction View for the Account Check transaction in MyST (see Figure 1). Please refer to the MyST User Guide for further information. Figure 1 - Security Response in MyST For further information on the nature of the checks performed, please refer to the AVS & CVV2 document. Secure Trading Limited April 2018 Page 55 / 73

56 5.3.1 ACCOUNTCHECK XML Response Example The following is an example ACCOUNTCHECK XML Response. The differences between an ACCOUNTCHECK XML Response and a standard AUTH XML Response is highlighted in bold. <?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>x </requestreference> <response type="accountcheck"> <merchant> <merchantname>example UNICODE merchantname</merchantname> <orderreference>accountcheck_auth</orderreference> <tid> </tid> <merchantnumber> </merchantnumber> <merchantcountryiso2a>gb</merchantcountryiso2a> <operatorname>site12345</operatorname> </merchant> <transactionreference>16-9-1</transactionreference> <billing> <amount currencycode="gbp">0</amount> <payment type="visa"> <issuer>test Issuer</issuer> <issuercountry>zz</issuercountry> <pan>411111######0211</pan> </payment> <dcc enabled="0"/> </billing> <authcode>test</authcode> <live>0</live> <error> <message>ok</message> <code>0</code> </error> <timestamp> :48:17</timestamp> <acquirerresponsecode>00</acquirerresponsecode> <security> <address>2</address> <postcode>2</postcode> <securitycode>2</securitycode> </security> <settlement> <settleduedate> </settleduedate> <settlestatus>0</settlestatus> </settlement> <operation> <accounttypedescription>ecom</accounttypedescription> </operation> </response> <secrand>bbyupvgz9hcm</secrand> </responseblock> Secure Trading Limited April 2018 Page 56 / 73

57 5.4 Combining Account Checks with other request types The preceding sections have described how to process independent Account Check Requests. In practice, Account Checks are often performed in conjunction with other request types. There are two main methods of integrating Account Checks into your payment flow: Inheriting Account Check information in subsequent requests After performing an Account Check, you can opt to perform another request using the same billing and payment details. This is achieved by submitting a new XML Request that includes the transaction reference of the Account Check. This transaction reference is submitted in the operation/parenttransactionreference element. The following is an example of an AUTH XML Request that inherits billing and payment details from an earlier Account Check: <requestblock version="3.67"> <alias>site12345</alias> <request type="auth"> <billing> <amount currencycode="gbp">100</amount> </billing> <operation> <sitereference>site12345</sitereference> <accounttypedescription>ecom</accounttypedescription> <parenttransactionreference>1-2-3</parenttransactionreference> </operation> </request> </requestblock> Missing information in the new request is inherited (section 1.3.5) from the Account Check referenced in the parenttransactionreference element. In particular, please note that if you submit a settle status or amount in the Account Check, this is applied to the new request, unless you override this by submitting a new value. In additional to AUTH XML Requests, this method is supported with other Secure Trading request types, such as: Request Type ORDER RISKDEC STORE THREEDQUERY Description Used to initiate a PayPal transaction. Used to process a Risk Decision Request Used to process a Card Store Request Used to process a 3-D Query Request For information on the use of the request types listed above, please refer to the relevant documentation. For information on using Account Checks with other request types that are not listed above, please contact Secure Trading Support (see section 10.1). Secure Trading Limited April 2018 Page 57 / 73

58 5.4.2 Multi-Process Request Multi-Process Requests allow you to process a single XML Request that instructs Secure Trading to perform an Account Check on the billing and payment details provided, and then to immediately perform another request(s). When configuring this kind of solution, it is especially important to configure rules on your Secure Trading account to manage the subsequent processing of Authorisations. See section for further information. If the Account Check is sent as part of a Multi-Process Request, it should be before an Authorisation Request in the sequence. E.g. Below is an outline of an XML Multi-Process Request that includes an Account Check. Notice how there are multiple requests in a single request block. <?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>site12345</alias> <request type="accountcheck"> </request> <request type="auth"> </request> </requestblock> Please note that each Multi-Process Request must be relating to the same payment details. You cannot process multiple Account Checks for different customers in the same XML Request Account Check Rules Optionally, rules can be assigned on your account by the Secure Trading Support team, which will use the results of the Account Check to decide whether or not to process an associated Authorisation transaction. The recommended process flow is as follows: 1. If the Account Check returns a Matched, then process the Authorisation. 2. If the Account Check returns a Not Checked, then process the Authorisation, but suspend the transaction allowing for manual investigation to take place. 3. If the Account Check returns a Not matched, then do NOT process an Authorisation. Please note that the default process flow can be customised. For example, you could choose to process the Authorisation if the Account Check returns Not Matched. For more information, contact Secure Trading Support (see section 10.1). An alternative to having rules configured, is that your system has this logic present which determines whether or not to submit an Authorisation Request. Secure Trading Limited April 2018 Page 58 / 73

59 6 Rules Secure Trading will perform certain actions on requests processed on your site reference using rules configured on your account. If pre-specified criteria are met and an action is performed on a request, the rule identifier will be returned in the XML Response. Please read the MyST Rule Manager supplement for information on how to create and maintain rules. The following information will explain how to use rules in conjunction with your XML implementation. 6.1 Activating rules Using MyST Rules can be activated on any of your site references by using MyST. This can be used to easily activate rules on ALL of your processed AUTH requests, without having to modify the XML In the XML Request Rules can be activated for individual AUTH XML Requests by submitting the unique rule identifier in the operation/ruleidentifier element. Rules specified in the AUTH XML Request will cause Secure Trading to perform certain actions if pre-defined criteria are met (regardless of whether or not said rules are active on your site references). The following code snippet is from an AUTH XML Request where two rules STR-1 and UDR-19 are specified: <request type="auth"> <operation> <sitereference>site12345</sitereference> <accounttypedescription>ecom</accounttypedescription> <ruleidentifier>str-1</ruleidentifier> <ruleidentifier>udr-19</ruleidentifier> </operation> </request> Please note that rules you have activated in MyST do not need to be manually specified in the AUTH XML Request. Specification of relevant nodes Tag Type Required Comment operation Y The unique identifier of a rule to be used in this request. ruleidentifier an N This element can be included once or multiple times in any XML Request, allowing you to specify as many rules as required. This element cannot be inherited in future child requests. It must be submitted in every request it is needed. Secure Trading Limited April 2018 Page 59 / 73

60 Please note that rules cannot be inherited in child XML Requests. They can only be activated by using the methods described in section Rule types Secure Trading Rules Rules with a Rule ID of STR-x (where x is a number) are Secure Trading Rules. e.g. STR-1 Secure Trading provides a number of pre-defined rules that can be activated on any of your site references (inactive by default). These rules are displayed within the rule manager interface in MyST and can be activated or deactivated by following the instructions outlined in the MyST User Guide. Secure Trading Rules are always performed before User-Defined Rules User-Defined Rules Rules with a Rule ID of UDR-x (where x is a number) are User-Defined Rules. e.g. UDR-19 Using MyST, you can create, modify and enable your own custom rules on any of your site references. For information on how to do this, please refer to the MyST Rule Manager supplement. 6.3 Interpreting the XML Response Most rules triggered during on a request will be returned in the operation/rule identifier element of the subsequent XML Response. The following code snippet is from an XML Response where a single rule STR-1 has been triggered on a submitted XML Request: <operation> <sitereference>site12345</sitereference> <accounttypedescription>ecom</accounttypedescription> <rule identifier="str-1">auth security code not matched - Merchant decline</rule> </operation> Specification of relevant nodes Tag Type Required Comment operation Y rule identifier= an C Unique rule identifier for rule triggered on the request. Always returned if a rule has been triggered, otherwise not returned. rule an C Description of rule triggered on the request. Always returned if a rule has been triggered, otherwise not returned. Secure Trading Limited April 2018 Page 60 / 73

61 6.4 Merchant Decline Rule (STR-1) Please note that this rule is only supported by acquirers and payment methods that support security code checks. When active, the STR-1 rule will automatically cancel transactions (update the settle status to 3) when the security code entered by the customer does not match the value held on the bank s records. This feature allows you to display a Merchant Declined message to your customers when they enter an incorrect security code. Please note that when a transaction is cancelled by a rule, the error code may remain in status 0 (Ok). This would indicate that the payment was authorised by the acquiring bank, but later cancelled by Secure Trading. Please note that if activated, the rule will also be enabled on payments processed using the Virtual Terminal, where a message of "Transaction Failed" will be displayed For merchants with existing rules When a transaction is cancelled by an update transaction response rule (e.g. Merchant Decline), the error code may remain in status 0 (Ok). This would indicate that the payment was authorised by the acquiring bank, but later cancelled by Secure Trading. Therefore, you may need to update any active rules to take this possible outcome into account. To prevent a rule from being triggered on a merchant decline, remove the settle status 3 (Cancelled) from existing conditions on the affected site reference(s). When creating new conditions using the MyST Rule Manager, we will automatically deselect settle status 3 when you select errorcode of 0, by default. Secure Trading Limited April 2018 Page 61 / 73

62 7 Best Practices You will need to perform checks on the fields returned in XML Responses from Secure Trading to ensure the request was processed successfully. The scope of the checks that need to be performed will depend on the type of the request processed. Secure Trading have provided an example flow diagram that you can use as a guide for configuring your system to manage the XML Responses returned. Merchant receives XML Response from Secure Trading Error code Ensure the error code returned is 0, indicating a successful transaction. Other error codes indicate failures that your system will need to be able to handle. Yes Pass? No See section 7.1 Settle status If you are expecting a transaction to be scheduled for settlement, ensure the settle status is 0, 1 or 10 (or 100 if settling immediately). Yes Pass? No See section 7.2 Security fields Please ensure that you have read section and have an assigned action to be performed for each security response that can be returned. For each transaction processed, only proceed if the security response meets your pre-specified criteria. (e.g. check the security/securitycode field is NOT 4 ) Yes Pass? No See section 7.3 Sanity checks Ensure the response type, live status, amount and currency contain expected values. (In most cases, the expected value will be the same as the value submitted in the request) Yes Pass? No See section 7.4 Proceed Secure Trading Limited April 2018 Page 62 / 73

63 7.1 Error code When experiencing errors, consult the table below for the recommended steps to handle the problem: Error code(s) Description Decline The acquirer has declined the request. No funds have been reserved against the customer s account. Invalid details The request was unsuccessful because either: Field(s) does not meet specification. OR: Required field(s) is missing. The name of the invalid/missing field will be highlighted. How to handle Display a declining payment error to the customer and allow them to try again; ensure you also offer alternative methods of payment (if enabled on your account). If the invalid fields are entered by the customer, highlight the invalid fields. The customer can correct them and try again. For invalid fields that are not entered by the customer, please manually review the invalid fields specified STAPI Error There is a problem with your STAPI configuration. Please review your STAPI configuration, ensuring you have followed the installation instructions in the STAPI User Guide Internal error There has been a problem processing the payment and the final transaction status is unknown. This can be due to a communication problem with a bank or third party. Display a message to the customer that indicates a problem has occurred and prompt them to contact you for clarification. You will need to contact our Support team, providing the transaction reference and we will contact the relevant parties to establish the status of the transaction. Secure Trading provides a full list of error codes that can be returned: If you need further information on a particular error code, please contact Secure Trading Support (see section 10.1). Secure Trading Limited April 2018 Page 63 / 73

64 7.2 Settle status When the following settle statuses are returned in an XML Response, they indicate the transaction has not been scheduled for settlement. Please refer to the following sections for further information: Settle status 2 If you are expecting a transaction to be scheduled for settlement, but the settle status 2 is returned, this indicates the transaction has been suspended. We recommend that you inform the customer that the payment has been processed successfully and investigate the issue (contact Support for further information - section 10.1). If there is an issue with the transaction, inform the customer that there has been a problem processing their payment (e.g. by ). If no action is taken, any authorised funds will not be transferred to your bank account Settle status 3 If you are expecting a transaction to be scheduled for settlement, but the settle status 3 is returned, this indicates the transaction has been cancelled. Display an error to the customer and allow them to try again; ensure you also offer alternative methods of payment (if enabled on your account). The error code will provide information on why the transaction was cancelled: If a transaction is cancelled, any authorised funds will not be transferred into your bank account. In order to resolve this, you must look at the error code and settle status returned, address the problem and attempt to process the payment again. For further information on settle statuses, please refer to section Security fields Authorisations and Account Checks will return three fields within the security tag, following Address Verification Service (AVS) and security code checks. Please ensure you are familiar with these security responses by reading section You can then configure your solution to alert on undesired security responses. e.g. If the security code entered by the customer does not match the value found on the back of their card, this could be deemed suspicious, and you may wish to manually investigate before proceeding with payment. For further information on AVS and security code checks, please refer to the AVS & CVV2 document. If the security/securitycode field has a value of 4 (not matched), Secure Trading will automatically suspend the transaction by default as part of your account s security policy, allowing you to manually investigate. You can customise the conditions under which transactions are automatically suspended. Please contact Secure Trading Support for further information (see section 10.1). Secure Trading Limited April 2018 Page 64 / 73

65 7.4 Sanity checks Your server should immediately alert you when any of the following issues arise, as they indicate atypical problems that lie outside the normal payment flow. We recommend that your system displays a generic error message to the customer indicating that a problem occurred, and allow them to try again. You will need to investigate any problems with the following fields to ensure your checkout is functioning correctly: Response type: Ensure it matches the request type (e.g. alert if response type is ERROR ). Live status: This should always be 1 when processing live payments ( 0 indicates request was processed on a test account). Amount and/or currency: The values returned in the response must match those sent in the request, unless stated otherwise in the relevant documentation (DCC). Error code: When processing live payments, the error code should never be 10500, or If these error codes are returned, contact Support immediately (see section 10.1). Secure Trading Limited April 2018 Page 65 / 73

66 8 Troubleshooting 8.1 Invalid or incomplete XML Request Invalid or incomplete XML Requests (e.g. error codes or in the XML Response) can be caused by the following: Missing XML tags check the XML Specification to see if any required tags are missing from the request. Newline character at the end of the XML check the XML Request to ensure there is a newline character at the end. Character encoding see section for further information. Character escaping see section for further information. Secure Trading Limited April 2018 Page 66 / 73

67 9 Testing During your integration, you will need to thoroughly test your system to ensure it is ready to process live payments. After Secure Trading has provided you with a test site reference, you can process AUTH, REFUND and ACCOUNTCHECK Requests and check that your system handles the responses correctly. We recommend specifying the base amount "1050" when testing. Other amounts can be used but may return unexpected responses. 9.1 Testing successful transactions You can process successful transactions by including the following PANs as part of valid XML Requests to Secure Trading: Payment type Test PAN VISA MASTERCARD To ensure these transactions pass AVS and CVV2 checks (see the AVS & CVV2 document for further details), you will also need to ensure your requests contain the following values: Field name Value billing/premise 789 billing/postcode billing/payment/securitycode 123 TE45 6ST Please ensure you have tested your integration with all payment methods that will be made available to your customers. The Testing document contains a full list of payment credentials that can be used when testing. 9.2 Testing unsuccessful transactions Your system will also need to be able to handle requests that are not successful. You can submit XML Requests with the following amounts to test for different responses returned by Secure Trading: Base amount Outcome Transaction declined by bank response Bank system error response. To simulate not matched responses for AVS and CVV2 checks, ensure your XML Request contains the following values: Field name Value billing/premise 123 billing/postcode billing/payment/securitycode 214 TE12 3ST The Testing document contains further test data for testing AVS & CVV2 checks. Please ensure your system is able to handle these scenarios. Secure Trading Limited April 2018 Page 67 / 73

68 10 Further Information and Support This section provides useful information with regards to documentation and support for the merchant s Secure Trading solution Secure Trading Support If you have any questions regarding integration or maintenance of the system, please contact our support team using one of the following methods. Method Details Telephone 44 (0) Fax 44 (0) support@securetrading.com Website Secure Trading Sales If you do not have an account with Secure Trading, please contact our Sales team and they will inform you of the benefits of a Secure Trading account. Method Details Telephone Telephone (Int l) 44 (0) Fax 44 (0) sales@securetrading.com Website Useful Documents The documents listed below should be read in conjunction with this document: STAPI User Guide This document outlines how to install a STAPI java client. This client can be used to process XML Requests and Responses through Secure Trading. STPP Web Services User Guide This document describes how to process XML Requests and Responses through Secure Trading s Web Services solution. XML Reference Transaction Query This document outlines how to perform a Transaction Query Request. STPP Transaction Update This document outlines how to perform a Transaction Update Request. STPP MyST User Guide This document outlines how to use MyST to monitor your transactions and manage your account. Any other document regarding the STPP system can be found at the following URLs: Frequently Asked Questions Please visit the FAQ section on our website ( Secure Trading Limited April 2018 Page 68 / 73

69 11 Appendix 11.1 Pre-Authorisations and Final Authorisations You can use the operation/authmethod field to designate an AUTH request as a preauthorisation or a final authorisation. These are described as follows: Pre-Authorisation: Settlement can be deferred by up to 28 days following authorisation. During this time, the amount to be settled can be updated to a value that is lower than the amount authorised. The transaction can be cancelled by updating the settlestatus to 3. Funds are reserved on the customer s account for up to 30 days. Final authorisation (only supported by Mastercard): Settlement can be deferred by up to 7 days following authorisation. Following authorisation, the amount value must not be updated. Following authorisation, this transaction must not be cancelled. Funds are reserved on the customer's account for up to 7 days. Mastercard Europe have mandated that Mastercard and Maestro transactions processed with certain European acquiring banks must be flagged as either preauthorisation or final authorisation. Such transactions are subject to acquirerspecific conditions. Failure to adhere to these conditions may incur a fine from the card issuer. For full terms and conditions, please contact your acquiring bank. We recommend that you contact your acquirer to ensure your system submits the correct authmethod value for your configuration. By default, Secure Trading will process AUTH requests as follows: Mastercard payments are processed as final authorisations, if required by the participating acquirer. Visa payments will not include the authmethod, meaning they will be processed as standard authorisations. You can change this default behaviour to submit pre-authorisations, by contacting Secure Trading Support (see section 10.1). Alternatively, see section for information on overriding the default behaviour on a transaction-by-transaction basis. Please note that when performing split shipments, the operation/authmethod field must always be set to PRE. For info on split shipments, please refer to the Split Shipment Guide. Secure Trading Limited April 2018 Page 69 / 73

70 Override You can include the operation/authmethod field to indicate whether the associated payment is a pre-authorisation or a final authorisation. When submitted, this overrides the default settings on your account (see section for info on finding your default setting). The values that can be submitted are: PRE - Requests a pre-authorisation. FINAL - Requests a final authorisation (default) (only affects Mastercard). The operation/authmethod field can ONLY be submitted in XML Requests of the following type: THREEDQUERY: If submitted, the authmethod value is inherited (section 1.3.5) by the child AUTH Request. AUTH: If submitted, the authmethod overrides the value submitted in the parent THREEDQUERY or the default value for the site. The operation/authmethod field cannot be inherited from previous authorisations. When performing repeat authorisations, the default value of your site will be used, unless you override this by manually submitting a new authmethod field in the request. If Secure Trading submits a value for the authmethod to the acquirer during authorisation, it will always be returned within the operation tag of the AUTH XML Response, in order to indicate whether the payment processed was a pre-authorisation or a final authorisation View default auth method setting To view the default Auth method settings on your site, sign in to MyST and choose your site from the drop-down in the left side-menu and click the magnifying glass. The default Auth method setting for the selected site is visible under the Site details tab: For further information on using MyST, please refer to the MyST User Guide. To change your default Auth method setting, please contact Secure Trading Support (section 10.1). Secure Trading Limited April 2018 Page 70 / 73