First Data Payeezy Gateway Search and Reporting API

Avatar
First Data Support (LL)
Follow
The First Data Payeezy Gateway Search & Reporting API allows users to search the Transaction records and to generate standard reports (Activity, Closed Batches, Pending Batches, Declined) . The data is returned in CSV format. The urls (without parameters) are:
  • 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 :

  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, Tagged Refund, Pre-Auth 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 - Payeezy Gateway 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. 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:

  1. ETG Response 
  2. 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

 

 

Powered by Zendesk