CSV Download. 2.1 (a) Automatically downloading transactions as Comma Separated Values (CSV). Published: 1 August 2017

Transcription

1 Automatically downloading transactions as Comma Separated Values (CSV). Published: 1 August (a)

2 Table of Contents 1 Introduction Process overview For transaction download For report download Basic Access Authentication Supported user roles Authorization header Filters Required filters Optional filters Display preferences For transaction download For report download Examples For transaction download For report download Further Information and Support Secure Trading Support Secure Trading Sales Useful Documents Frequently Asked Questions Appendix Transaction download optional fields Secure Trading Limited August 2017 Page 2 / 18

3 1 Introduction This document describes how to download transaction and reporting data as Comma Separated Values (CSV) by submitting a HTTPS POST query string. By implementing the CSV download functionality outlined in this document, your system can be configured to process requests on your behalf, allowing you to automate the process of downloading the records required. Please note that we also provide similar functionality in MyST, but this is a manual process where a user has to be signed in and present to trigger the download. Please refer to the MyST User Guide for further information. There are two types of CSV download that we support: Transaction download Download individual records of processed requests meeting specified criteria. Report download Download reports that allow you to keep track of the number of requests processed on your account. The maximum number of records that can be downloaded is 75,000 lines. If you have greater than 75,000 records, we recommend requesting smaller timeframes and performing multiple sequential requests (see section 4.2.3). Secure Trading Limited August 2017 Page 3 / 18

4 2 Process overview 2.1 For transaction download This feature allows you to download details of requests processed on your account that meet your specified criteria. You can choose the fields that are returned, so you only download the information you need. Example use cases: Download information on all transactions processed on a single day. Download the names of all customers that have made purchases for greater than 999 in the last month. Download the transaction references of suspended transactions in a given timeframe. The following is an example of a POST for requesting a transaction download CSV report: wget --output-document=output.csv --user=example@example.com --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&optionalfields=errorcode&optionalfields=currencyi so3a&optionalfields=authcode&optionalfields=orderreference&optionalfie lds=paymenttypedescription&optionalfields=settlestatus&optionalfields= settlemainamount&optionalfields=settleduedate&optionalfields=customerc ountryiso2a" The request above consists of four main parts: Basic User Authentication - You will need to provide a MyST username with sufficient user privileges to perform the download for the given sitereference/s. See section 3 for further information. Filters - Filters can be included in the request so that only records meeting certain criteria are returned. See section 4 for further information. Display preferences - This is where you can specify the data fields to be returned. See section 5 for further information. Transaction download URL Provided your POST is successful, the CSV output has the following structure: transactionreference,errorcode,currencyiso3a,authcode,orderreference,p aymenttypedescription,settlestatus,settlemainamount,settleduedate,cust omercountryiso2a ,0,GBP,TEST,20161,VISA,100,10.99, ,GB ,0,GBP,TEST,20162,MASTERCARD,100,11.98, ,GB ,0,GBP,TEST,20163,MASTERCARD,100,10.99, ,GB ,0,GBP,TEST,20164,MASTERCARD,100,10.99, ,GB ,0,GBP,TEST,20165,DELTA,100,16.98, ,GB ,0,GBP,TEST,20166,AMEX,100,10.99, ,GB Secure Trading Limited August 2017 Page 4 / 18

5 2.2 For report download Reports allow you to keep track of the number of requests processed on your account during a specified period of time. This information is grouped by criteria specified in the POST. Example use cases: Download the number of transactions authorised. Download the number of transactions suspended. Download the total funds settled. Download the number of transactions processed with PayPal. The following is an example of a POST for requesting a report download CSV report: wget --output-document=output.csv --user=example@example.com --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&sqlgroupbys=currencyiso3a&sqlgroupbys=paymenttype description" The request above consists of four main parts: Basic User Authentication - You will need to provide a MyST username with sufficient user privileges to perform the download for the given sitereference/s. See section 3 for further information. Filters - Filters can be included in the request so that only requests meeting certain criteria are counted. See section 4 for further information. Display preferences - This is where you can specify the data fields to be returned. See section 5 for further information. Report download URL Provided your POST is successful, the CSV output has the following structure: acquirertypedescription,currencyiso3a,paymenttypedescription,settledco unt,sumsettlemainamount TEST,GBP,VISA,1,10.99 TEST,GBP,MASTERCARD,3,33.96 TEST,EUR,VISA,17, TEST,EUR,MASTERCARD,7,72.80 Secure Trading Limited August 2017 Page 5 / 18

6 3 Basic Access Authentication wget --output-document=output.csv --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&optionalfields=errorcode&optionalfields=currencyi so3a&optionalfields=authcode&optionalfields=orderreference&optionalfie lds=paymenttypedescription&optionalfields=settlestatus&optionalfields= settlemainamount&optionalfields=settleduedate&optionalfields=customerc ountryiso2a" The CSV file can be downloaded using a HTTPS POST query string with Basic Access Authentication. Basic Access Authentication is a method for a web browser client program to provide a username and password when processing a request. 3.1 Supported user roles You can use your Webservices username and password to download transaction records and reports. If you do not already have a Webservices username, you can create a new user using the MyST service. We also support two additional user roles for CSV downloads. These are Transaction download and Report download, for downloading transaction records and reports respectively. To set up users with these roles, please contact our Support Team (see section 7.1). 3.2 Authorization header A username and password, separated by a colon, then base64 encoded must be included in the authorisation header when performing the request. Most URL libraries will construct the basic authentication header automatically, but if you need to perform this manually, please follow this example: Username: csvdownload@example.com Password: pa55word Separated by a colon: csvdownload@example.com:pa55word Base64 encode: Y3N2ZG93bmxvYWRAZXhhbXBsZS5jb206cGE1NXdvcmQ= Therefore, the authorisation header should be: Authorization: Basic Y3N2ZG93bmxvYWRAZXhhbXBsZS5jb206cGE1NXdvcmQ= Secure Trading Limited August 2017 Page 6 / 18

7 4 Filters wget --output-document=output.csv --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&optionalfields=errorcode&optionalfields=currencyi so3a&optionalfields=authcode&optionalfields=orderreference&optionalfie lds=paymenttypedescription&optionalfields=settlestatus&optionalfields= settlemainamount&optionalfields=settleduedate&optionalfields=customerc ountryiso2a" By default, all transactions within the date range for the specified SiteReference(s) will be returned in the download. Filters can be applied to the download so only certain records are returned. In the example above, the following filters have been applied: Site reference: test_site12345 Transaction authorisation date: 1 st January st January 2017 Settle status: 100 Multiple values for the same filters can be included in the call separated by a &. For example, for downloading Ecommerce and Mail Order Telephone transactions, the accounttypedescriptions filter can be included twice with two different values. accounttypedescriptions=ecom&accounttypedescriptions=moto 4.1 Required filters The following fields must be included in the POST data: sitereferences The site reference/s to download data from. startdate enddate The start date for the specified records (in the format YYYY-MM-DD). The end date for the specified records (in the format YYYY-MM-DD). Data can be downloaded for multiple site references by including additional sitereferences fields in the call separated by a &. For example, if transactions are needed for site1 and site2, the call would include the following. sitereferences=site1&sitereferences=site2 Please note that even if downloading transactions for one site reference, the field must always be called sitereferences. Secure Trading Limited August 2017 Page 7 / 18

8 4.2 Optional filters Below are some example filters. Please contact Secure Trading Support with questions regarding any additional filters (see section 7.1) Useful filters Field Name accounttypedescriptions currencyiso3as errorcodes Filter by account type, e.g. ECOM for e-commerce. You can view the account types enabled on your account in MyST, by selecting your site from the side-bar on the left and viewing the Accounts tab. Filter by currency. For a list of currencies, Filter by error codes. For a list of error codes, go to paymenttypedescriptions Filter by payment type. e.g. VISA, MASTERCARD etc. requesttypedescriptions Type of request, for example AUTH, REFUND etc. settlestatuss Filter by status. e.g. 100 for all settled transactions. Please note that to search by settlestatus the field must be called settlestatuss Filter by time Secure Trading allows you to download transactions within a specified range of time. To do this, you will need to include the following fields in your request: Field Name starttimehour starttimeminute endtimehour endtimeminute To find transactions between HH:mm:00 and HH:mm:59 *Required if end time specified To find transactions between HH:mm:00 and HH:mm:59 * Required if starttimehour specified To find transactions between HH:mm:00 and HH:mm:59 * Required if start time specified To find transactions between HH:mm:00 and HH:mm:59 * Required if endtimehour specified For example, for downloading transactions between 13:30:00 and 14:29:59 : starttimehour=13&starttimeminute=30&endtimehour=14&endtimeminute=29 Secure Trading Limited August 2017 Page 8 / 18

9 4.2.3 Date type By default, dates and times specified are filtered based on when the transaction was processed on Secure Trading s servers. However, you can explicitly specify the type of date/time that is filtered by including the following additional filter: Field Name datetypes Specify settledtimestamp to filter by date/time transactions were settled. Specify transactionstartedtimestamp to filter by date/time requests were processed. Please note if your system is processing a high volume of transactions, Secure Trading recommends downloading CSV files of transactions on an hourly basis (instead of daily), for optimum performance and to reduce the size of the files downloaded. Your system can submit a request every hour, specifying the time filters as described in section 4.2.2, to ensure only transactions processed in the last hour are included. An example of such a request can be found in example B in section Secure Trading Limited August 2017 Page 9 / 18

10 5 Display preferences As a minimum, all CSV downloads will contain the following fields: Transaction download always contains the transaction reference for each record returned. Report download always contains the acquirer name and number of transactions settled for each of these acquirers within the given timeframe. Transaction download example output transactionreference Report download example output acquirertypedescription,settledcount BARCLAYS,1916 PAYPAL,249 PAYSAFE,18 TEST,4 You can change how the results are displayed by adding additional fields in your request, as outlined in this section of the document. 5.1 For transaction download You can specify additional fields to be returned in the transaction download, as highlighted in the example below in bold: wget --output-document=output.csv --user=example@example.com --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&optionalfields=errorcode&optionalfields=currencyi so3a&optionalfields=authcode&optionalfields=orderreference&optionalfie lds=paymenttypedescription&optionalfields=settlestatus&optionalfields= settlemainamount&optionalfields=settleduedate&optionalfields=customerc ountryiso2a" Full list of fields, see section 8.1. The example above includes the following optional fields: Error code Currency Auth code Order reference Payment type Settle status Settle main amount Settle due date Customer country The output would contain these optional fields. The field names specified in the request are shown on the first line of the CSV output, in the same order: transactionreference,errorcode,currencyiso3a,authcode,orderreference,p aymenttypedescription,settlestatus,settlemainamount,settleduedate,cust omercountryiso2a ,0,GBP,TEST,20161,VISA,100,10.99, ,GB ,0,GBP,TEST,20162,MASTERCARD,100,11.98, ,GB ,0,GBP,TEST,20163,MASTERCARD,100,10.99, ,GB ,0,GBP,TEST,20164,MASTERCARD,100,10.99, ,GB If a requested optional field has no value, an empty string will be returned in the CSV. Secure Trading Limited August 2017 Page 10 / 18

11 5.2 For report download Grouping The output returned in the report download can be grouped by the following options: day sitereference currencyiso3a requesttypedescription accounttypedescription paymenttypedescription errorcode settlestatus livestatus transactionactive enrolled fraudcontrolshieldstatuscode orderreference You can apply preferred grouping the report download, as highlighted in the example below in bold: wget --output-document=output.csv --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&sqlgroupbys=currencyiso3a&sqlgroupbys=paymenttype description" The output would be grouped as follows: acquirertypedescription,currencyiso3a,paymenttypedescription,settledco unt,sumsettlemainamount TEST,GBP,VISA,1,10.99 TEST,GBP,MASTERCARD,3,33.96 TEST,EUR,VISA,17, TEST,EUR,MASTERCARD,7,72.80 Notice that data was requested to be grouped by both currency and payment type, and the result is that there is a row in the output for each combination of currency and payment type. The order in which the sqlgroupbys are submitted affects the output. The output is always grouped in the order submitted in the request. In the example above, the output is grouped by currency first, then payment type. If these two properties were swapped around, you could instead choose to group the output by payment type first, then currency. Secure Trading Limited August 2017 Page 11 / 18

12 6 Examples The CSV file must be downloaded using a HTTPS POST query string. The following are examples of CSV download requests: 6.1 For transaction download Example A Note: This is the example referenced in previous sections of this document. Filters by: Site reference: test_site12345 Transaction authorisation date: 1 st January st January 2017 Settle status: 100 Includes fields: Transaction reference Error code Currency Auth code Order reference Payment type Settle status Settle main amount Settle due date Customer country wget --output-document=output.csv --user=example@example.com --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&optionalfields=errorcode&optionalfields=currencyi so3a&optionalfields=authcode&optionalfields=orderreference&optionalfie lds=paymenttypedescription&optionalfields=settlestatus&optionalfields= settlemainamount&optionalfields=settleduedate&optionalfields=customerc ountryiso2a" Output: transactionreference,errorcode,currencyiso3a,authcode,orderreference,p aymenttypedescription,settlestatus,settlemainamount,settleduedate,cust omercountryiso2a ,0,GBP,TEST,20161,VISA,100,10.99, ,GB ,0,GBP,TEST,20162,MASTERCARD,100,11.98, ,GB ,0,GBP,TEST,20163,MASTERCARD,100,10.99, ,GB ,0,GBP,TEST,20164,MASTERCARD,100,10.99, ,GB ,0,GBP,TEST,20165,DELTA,100,16.98, ,GB ,0,GBP,TEST,20166,AMEX,100,10.99, ,GB Secure Trading Limited August 2017 Page 12 / 18

13 6.1.2 Example B Filters by: Site reference: test_site12346 Transaction settlement date: 1 st January 2017, 09:00-09:59 Error code: Include fields: Transaction reference Error code Currency Settle main amount Settle due date wget --output-document=output.csv --user=example@example.com --askpassword --post- data="sitereferences=test_site12346&errorcodes=70000&startdate= &starttimehour=9&starttimeminute=0&enddate= &endtimehour=9&endtimeminute=59&datetypes=settledtimestamp&optionalf ields=errorcode&optionalfields=currencyiso3a&optionalfields=settlemain amount&optionalfields=settleduedate" Output: transactionreference,errorcode,currencyiso3a,settlemainamount,settledu edate ,70000,GBP,123.99, ,70000,GBP,123.99, Example C - Downloadable Java example Example Java code that can be used to perform CSV downloads can be found at the following URL: ownload.java Before executing the code, you will need to modify the example to include any filters and optional fields as described in this document. This example code requires you to submit your previously registered Transaction download or Webservices user details and password as parameters, securely submitting your specified filters and optional fields to Secure Trading to output a CSV file. This example code is provided for demonstration purposes and it is expected that all merchants develop their own solution. Secure Trading Limited August 2017 Page 13 / 18

14 6.2 For report download Example D Filters by: Site reference: test_site12345 Transaction authorisation date: 1 st January st January 2017 Settle status: 100 Group output by: Currency Payment type wget --output-document=output.csv --user=example@example.com --askpassword --post-data="sitereferences=test_site12345&startdate= &enddate= &settlestatuss=100&sqlgroupbys=currencyiso3a& sqlgroupbys=paymenttypedescription" Output: acquirertypedescription,currencyiso3a,paymenttypedescription,settledco unt,sumsettlemainamount TEST,GBP,VISA,1,10.99 TEST,GBP,MASTERCARD,3,33.96 TEST,EUR,VISA,17, TEST,EUR,MASTERCARD,7,72.80 Secure Trading Limited August 2017 Page 14 / 18

15 7 Further Information and Support 7.1 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) 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 below document might be useful when generating your calls to Secure Trading. MyST User Guide - How to use the Secure Trading account management system. This document covers Transaction Searches in MyST. Any document regarding the STPP system can be found on SecureTrading s website ( Alternatively, please contact our support team as outlined above. 7.4 Frequently Asked Questions Please visit the FAQ section on our website ( Secure Trading Limited August 2017 Page 15 / 18

16 8 Appendix 8.1 Transaction download optional fields You can specify additional fields to be returned in the transaction download. This is reflected in the output returned (as highlighted in the example below): transactionreference,errorcode,currencyiso3a,authcode,orderreference,p aymenttypedescription,settlestatus,settlemainamount,settleduedate,cust omercountryiso2a ,0,GBP,TEST,20161,VISA,100,10.99, ,GB ,0,GBP,TEST,20162,MASTERCARD,100,11.98, ,GB ,0,GBP,TEST,20163,MASTERCARD,100,10.99, ,GB ,0,GBP,TEST,20164,MASTERCARD,100,10.99, ,GB If a requested optional field has no value, an empty string will be returned in the CSV. The following sections list fields that can be included in the output, if specified in the request: Transaction Details Optional Field Name transactionreference Secure Trading unique transaction reference. parenttransaction Transaction reference of parent transaction. For example, reference in the case of refunds, this would be the reference to the transaction that has been refunded. Account type, e.g. ECOM for e-commerce. accounttypedescription You can view the account types enabled on your account in MyST, by selecting your site from the side-bar on the left and viewing the Accounts tab. baseamount Transaction in base amount. For example 10 will be 1000 mainamount Transaction in main amount. For example 10 will be errorcode Error code for the transaction. For a list of error codes, go to currencyiso3a Currency of transaction. For a list of currency codes, go to authcode Transaction authorisation code. customerip Customer IP. fraudrating Transaction fraud rating. orderreference Merchant s order reference Payment Details Optional Field Name paymenttypedescription maskedpan expirydate Type of payment, for example VISA, MASTERCARD. Masked card number. Card expiry date. Secure Trading Limited August 2017 Page 16 / 18

17 8.1.3 Settlement Details Optional Field Name settlestatus settlemainamount settleduedate The current transaction status. Amount due to settle/settled. Date due to settle/settled Security Response The response of the security checks performed during authorisation. This can be one of the following values: 0 = DATA NOT GIVEN 1 = DATA NOT CHECKED 2 = DATA MATCH 4 = DATA NOT MATCHED Optional Field Name securityresponse securitycode Result of security code check. securityresponseaddress Result of address check. securityresponse postcode Result of postcode check Billing Details The details submitted for the billing contact. Optional Field Name billingprefixname billingfirstname billingmiddlename billinglastname billingsuffixname billingpremise billingstreet billingtown billingcounty billing billingcountryiso2a billingpostcode billingtelephones Name prefix. For example, Mr, Mrs, Miss. First Name. Middle Name. Last Name. Name suffix. For example, BSc, PhD. First line of the address. Address Street. Address Town. Address County. address. Address Country. For a list of country codes, go to Address Postcode. Telephone. Secure Trading Limited August 2017 Page 17 / 18

18 8.1.6 Customer Details Optional Field Name customerprefixname customerfirstname customermiddlename customerlastname customersuffixname customerpremise customerstreet customertown customercounty customer customercountryiso2a customerpostcode customertelephones Name prefix. For example, Mr, Mrs, Miss. First Name. Middle Name. Last Name. Name suffix. For example, BSc, PhD. First line of the address. Address Street. Address Town. Address County. address. Address Country. For a list of country codes, go to Address Postcode. Telephone Merchant Details Optional Field Name merchantname tid Merchant name associated with site reference. The Terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems. Secure Trading Limited August 2017 Page 18 / 18