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:



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:



SAR_API_USER.png


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’. 


SAR_USER_KEY.png


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 :


  1. Tag - Transaction Tag (Unique identifier)
  2. Cardholder Name - the cardholder name
  3. Card Number - Masked Card Number 
  4. Expiry - Expiry Date on the Card
  5. Card Type - Card Type (VISA, AMEX, MASTERCARD ...) 
  6. Amount - Transaction Amount 
  7. Code - Transaction Code/Type (Purchase, Refund, Preauth etc) 
  8. Status - Status of the transaction (Approved, Declined, Error) 
  9. Auth No - Transaction Authorization number
  10. Time - Transaction Time (in the Terminal Time Zone) 
  11. Ref Num - Transaction Reference number 
  12. Cust. Ref Num - Transaction Customer Reference 
  13. Reference 3 - Transaction Reference 3 data
  14. Account Name - E-xact account name 
  15. Merchant Name - Merchant Name 
  16. Merchant Code - Merchant Code 
  17. Terminal Name - Terminal Name
  18. 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


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article