- search - https://api.globalgatewaye4.firstdata.com/transaction/search
- reports - https://api.globalgatewaye4.firstdata.com/transaction/report
Search (download Transaction Records in CSV format)
The Service allows authenticated users to download the Transaction Records for the Account they are associated with. All arguments are optional and provide defaults (see below).
Parameters
Parameter Name | Description |
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 First Data Payeezy Gateway Real-time Payment Manager (RPM)). To obtain associated account id values please contact First Data. |
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 First Data. |
terminal | The optional integer terminal id, returns 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.globalgatewaye4.firstdata.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.globalgatewaye4.firstdata.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,,,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,,,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,,,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,,,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,,,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,,,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,,,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,,,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,,,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, Tagged Refund, Pre-Auth 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 - Payeezy Gateway 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. In this case, an offset value of "10000" can be used to retrieve results not obtained in the first dataset. This offset value can be incremented by values of 10000 to retrieve subsequent result sets.
- 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.globalgatewaye4.firstdata.com/transaction/search?start_date=2010-04-01&end_date=2010-07-01&offset=55"
API v3
API v3 adds two additional columns:
- ETG Response
- Bank Response
Examples
Return the transactions for the given period and default account
curl -i -u wilma:w_pass -H 'Accept: text/search-v3+csv' "https://api.globalgatewaye4.firstdata.com/transaction/search?start_date=2014-03-01&end_date=2014..."
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,ETG Response,Bank Response
48669,Bill Simpson,############1111,0611,VISA,$5.00,Purchase,Approved,ET103159,06/06/2010 00:05:10,33,,,Demo,Vital GBSCalgary 2300003,2300003,VIT GBS Calgary MBatch 001,AD0007-01,00,100
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
Parameter Name | Description |
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, 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.globalgatewaye4.firstdata.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. NOTE: User Passwords expire every 60 days on Payeezy Gateway. An expired user password will generate a 401 – Unauthorized response code. Currently, there is no process for Payeezy Gateway to notify a user when their specific password or a password utilized as part of a search/reporting request will expire. This monitoring is completely the responsibility of the Payeezy Gateway merchant.
- Request may specify non-default account, subject to the user/account association. If the account is not passed the default account from the user preferences is selected (same behavior as in RPM).
- Only customer roles can use the service (pos, merchant, merchant_admin). First Data 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.
- To retrieve soft descriptor data in a transaction search, pass "Accept: text/search-v2+csv" as an HTTP header
Fraud Detect
It is possible to use the API to search for Fraud Detect information.
Example of the API Request (not showing authentication)
GET "/transaction/search?start_date=2007%2F01%2F24&end_date=2007%2F01%2F24&search=123676
Example of a Response CSV
Tag,Cardholder Name,Card Number,Expiry,Card Type,Amount,Transaction Type,Status,Bank Response,ETG Response,Auth No,Time,Ref Num,Cust. Ref Num,Reference 3,Account Name,Merchant Name,Merchant Code,Terminal Name,Gateway,DBA Name,Street,City,Region,Postal Code,Country,MID,MCC,Merchant Contact Info,Amex Fraud,Fee,Fraud Detect Score,Fraud Detect Recommendation,Fraud Detect Explanation 1 Type,Fraud Detect Explanation 1 Description,Fraud Detect Explanation 2 Type,Fraud Detect Explanation 2 Description,Fraud Detect Explanation 3 Type,Fraud Detect Explanation 3 Description,Fraud Detect Explanation 4 Type,Fraud Detect Explanation 4 Description,Fraud Detect Explanation 5 Type,Fraud Detect Explanation 5 Description
50,Vern Macadamia,############1111,1117,VISA,"$3,000.00",Purchase,Approved,000,00,ET0515,09/24/2017 16:05:15,123676,"","",GBS Calgone,GBS Calgone 1300002,1300003,GBS Calgone 004,AD0009-01,"","","","","","","","","",0.0,"","","","","","","","","","","",""
150,Benny Samsonac,############1431,1218,VISA,"$120.50",Purchase,Approved,000,00,ET7525,09/24/2017 16:02:15,123676,"","",GBS Calgone,GBS Calgone 1300003,1300003,GBS Calgone 004,AD0009-01,"","","","","","","","","",0.0,139,approve,rule,PTR_123 The request included reference_3 as FDS-810-3,rule,INFO_123 The terminal has score threshold 750,"","","","","",""
253,Kyle Junjun,############1121,0819,MASTERCARD,"$3,300.00",Purchase,Approved,000,00,ET9444,09/24/2017 16:05:15,123676,"","",GBS Calgone,GBS Calgone 1300003,1300003,GBS Calgone 004,AD0009-01,"","","","","","","","","",0.0,789,decline,rule,PTR_123 Decription Number 1,model,Description Number 2,rule,PTR_124 Description Number 3,model,Description Number 4,rule,PTR_125 Description Number 5