Transaction Search and Reporting API

Created by Richard Moore, Modified on Wed, 19 Apr, 2023 at 11:06 AM by Richard Moore

The Search and Reporting API allows users to search transaction records and to generate standard reports (Activity, Closed Batches, Pending Batches, Declined). The report data is returned in CSV format. The urls (without parameters) are:

search - https://api.e-xact.com/transaction/search
reports - https://api.e-xact.com/transaction/report

Create a 'Read Only API' User

Before using the Transaction Search and Reporting API, the account administrator will need to create a ‘Read Only API’ user. This user class is designated for use with the Search and Reporting API, only—this new user will not have access to the E-xact/Chase RPM site.

The first step is to create a new user under the ‘Administration’ -> ‘Users’ menu:

Fill in the user’s ‘Contact’ information. Next, under the ‘Login’ tab, you will choose a login name and select the Role of ‘Read Only API’.

You will now see the option to generate a Token and Alternative Token for the user. Click the ‘Generate’ link beside each empty field; record these tokens. Press ‘Update’ to save them.

This login and token can now be used as the authorized credentials each time a search is conducted using this service. These credentials will never expire.

Note: Two tokens are generated and saved. You may use either of these tokens when making an API search request.

Search (download Transaction Records in CSV format)

This service allows authenticated users—like the one created above—to download the Transaction Records for the Account they are associated with. All arguments are optional and provide defaults (see below).

Parameters

account - the optional account id to select (account=123456). If not specified, it defaults to the user default account (set in the user preferences in RPM). To obtain associated account id values please contact E-xact.
merchant - the optional integer merchant id - restrict the search to include only the merchant with the given id. If not specified defaults to all the merchant accounts. To obtain your merchant id values please contact E-xact.
terminal - the optional integer terminal id, return only the Transactions that belong to the specified Terminal ID (terminal=AD0009-01). If not specified defaults to all terminals.
start_date, end_date - date interval criteria (start_date=2010-06-01%2000:00:00&end_date=2010-06-01%2023:59:59) - defaults to today (beginning of the day, end of the day)
status - optional 'A' - approved, 'D' - declined - 'E' error, by default includes all transactions
search_field - the field to search for : cardholder, refno, custref, tag, cardno) - defaults to cardholder, refno, custref (if no search_field specified)
search - the value to search for (search=Mary) - searches the transaction where cardholder, refno, custref have substring Mary)
amount_from, amount_to - amount range criteria (amount_from=100&amount_to=200)
inactive_merchants - defaults to false, include (or not) inactive merchants
offset - An integer determining the offset from where the rows should be fetched. So at 5, it would skip rows 0 through 4. This can be used to paginate over the large dataset (see the related Result Header section below).

Examples

Return the transactions for the given period and default account

https://api.e-xact.com/transaction/search?start_date=2010-06-01%2000:00:00&end_date=2010-06-01%2023:59:59

Return the transactions for the given period, default account, searching for cardholder that matches the name Wilma

https://api.e-xact.com/transaction/search?start_date=2010-06-01%2000:00:00&end_date=2010-06-01%2023:59:59&search=Wilma

Sample Output

Tag,Cardholder Name,Card Number,Expiry,Card Type,Amount,Transaction Type,Status,Auth No,Time,Ref Num,Cust. Ref Num,Reference 3,Account Name,Merchant Name,Merchant Code,Terminal Name,Gateway
48669,Bill Simpson,############1111,0611,VISA,$5.00,Purchase,Approved,ET103159,06/06/2010 00:05:10,33,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48668,Larry Ellison,############1111,0611,VISA,$5.00,Purchase,Approved,ET127835,06/06/2010 00:05:10,32,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48667,John Kennedy,############1111,0611,VISA,$5.00,Purchase,Approved,ET184208,06/06/2010 00:05:10,31,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48666,Johnny Mercer,############1111,0611,VISA,$5.00,Purchase,Approved,ET145058,06/06/2010 00:05:10,30,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48665,Tony Braxton,############1111,0611,VISA,$5.00,Purchase,Approved,ET188440,06/06/2010 00:05:10,29,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48664,Don Johnson,############1111,0611,VISA,$5.00,Purchase,Approved,ET150886,06/06/2010 00:05:09,27,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48663,Cybil Shepherd,############1111,0611,VISA,$5.00,Purchase,Approved,ET132544,06/06/2010 00:05:09,28,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48662,Merle Haggard,############1111,0611,VISA,$5.00,Purchase,Approved,ET175382,06/06/2010 00:05:09,26,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01
48661,Gina Lollabrigida,############1111,0611,VISA,$5.00,Purchase,Approved,ET140094,06/06/2010 00:05:09,25,,,E-xact Demo,Vital GBS Calgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01

The columns are :

Tag - Transaction Tag (Unique identifier)
Cardholder Name - the cardholder name
Card Number - Masked Card Number
Expiry - Expiry Date on the Card
Card Type - Card Type (VISA, AMEX, MASTERCARD ...)
Amount - Transaction Amount
Code - Transaction Code/Type (Purchase, Refund, Preauth etc)
Status - Status of the transaction (Approved, Declined, Error)
Auth No - Transaction Authorization number
Time - Transaction Time (in the Terminal Time Zone)
Ref Num - Transaction Reference number
Cust. Ref Num - Transaction Customer Reference
Reference 3 - Transaction Reference 3 data
Account Name - E-xact account name
Merchant Name - Merchant Name
Merchant Code - Merchant Code
Terminal Name - Terminal Name
Gateway - Terminal Gateway ID

Result Header

The header Search-CSV contains additional information about the search result :

Search-CSV: Version: 1.0, Offset: 55, Rows: 2, Total: 57, Account: GBS Calgary, User: wilma, Time: Fri Jun 04 11:20:34 -0700 2010

Offset, Rows, Total - Offset is the integer that was passed (defaults to 0) indicating where the rows should be fetched; Rows is the number of Rows in the response, and Total is the total number of rows for the criteria. These values can be used for paginating over the large dataset when the single response limit (10K rows) is exceeded.
User, Account are the information of the requester and the account for which to run the report, the Time indicates when the report was run.

Here is a sample command line service invocation that results in the above headers:

curl -i -u wilma:w_password "https://api.e-xact.com/transaction/search?start_date=2010-04-01&end_date=2010-07-01&offset=55"

Reports (download Transaction Reports in XML format)

The service allows authenticated users to download the Transaction Reports (Activity, Closed Batches, Pending Batches, Declined) for the Account they are associated with. All arguments are optional and provide defaults (see below).

Parameters

account - the optional account id to select (account=123456), defaults to the user default account (set in the user preferences) merchant - the optional merchant id - include only the merchant with the given id (user must be associated with the merchant)
start_date, end_date - date interval criteria (start_date=2010-06- 01%2000:00:00&end_date=2010-06-01%2023:59:59) - defaults to today (beginning of the day, end of the day)
report_type - the report is requested (vt_activity, vt_deposits_closed [Note: no time can be specified for closed deposits, only date], vt_deposits_pending, vt_declined) - defaults to activity
group - group report lines (amounts) by terminal or user_name. The default is the terminal.
inactive_merchants - defaults to false, include (or not) inactive merchants

Examples

Return the activity report for the period

http://api.e-xact.com/transaction/report?start_date=2010-06-01%2000:00:00&end_date=2010-06-01%2023:59:59

Security (Authentication)

Requests are submitted by user accounts. (unlike transaction web service - where the Gateway ID/Password is used). Search and reports are account/user based.
Request may specify non-default account, subject ot the user/account association. If the account is not passed the default account from the user preferences is selected (same behaviour as in RPM).
Only customer roles can use the service (pos, merchant, merchant_admin). E-xact admin, and Paymentech admin roles cannot use the service.
SSL + Auth Basic is the authentication method. Standard HTTP codes are returned for Unauthorized - 401.
Sensitive data (credit card numbers) is filtered out from logs.

Validation, Limits

Download limits (10K) are inherited from the RPM.
400 (Bad Request) is returned for the bad arguments with the explanation line(s).
500 with the Generic message is returned on server error
The service supports GET request and rejects unsupported verbs (POST, PUT etc) with HTTP code 405.
The Date fields are in ISO 8601 format YYYY-MM-DD.

References

Attachments (1)

java

SearchSample.java
911 Bytes