Transaction Lookup
This transaction searches for previous Sale, Pre-Auth, Refund, and Void transactions.
Code Samples
CWS
Request
Property | Description |
---|---|
method string | required | searchPaymentTransaction |
requestId string | required | Transaction Request ID |
targetType string | required | paymentGatewayConverge |
parameters JSONObject | required | All relevant parameters for searching transactions |
paymentGatewayId string | required | Payment Gateway ID Unique payment gateway identifier as returned in the openPaymentGateway transaction response. |
creditCard string | optional | Full Credit Card Number The complete credit card number to search. Important: You can combine this parameter with beginDate and/or endDate |
last4CC string | optional | Last 4 Digits The last 4-digits of the credit card number to search. Important: You can combine this parameter with beginDate and/or endDate |
beginDate string | optional | Start Date The beginning date of the date range search criteria. Format: YYYYMMDD Important: - The date range must not exceed 31 days. - You can combine this parameter with creditCard or last4CC . |
endDate string | optional | End Date The end date of the date range search criteria. Format: YYYYMMDD Important: - The date range must not exceed 31 days. - You can combine this parameter with creditCard or last4CC . |
transId string | optional | Transaction ID Unique identifier of the transaction to search. Important: This parameter must be combined with utcDate . |
utcDate string | optional | UTC Date The universal coordinated time of transaction authorization. Format: yyyy/MM/dd hh:mm:ss Important: This parameter must be supplied if transId is also included. |
merchantTransactionReference string | optional | Merchant Transaction Reference Unique merchant reference code or ID associated with a transaction. Important: This parameter must be combined with one or more of beginDate , endDate , last4CC , or creditCard . |
Response
Property | Description |
---|---|
requestId string | Transaction Request ID As specified in the request. |
statusDetails string | Request Status |
data JSONObject | Object holding various responses. |
transactionSearchResults JSONObject | Transaction Search Results An array of transaction objects. |
transaction JSONObject | Transaction Details |
id string | Transaction ID Unique identifier of the transaction. |
transactionType string | Transaction Type |
tenderType string | Tender Type Valid value: CARD |
cardScheme string | Card Brand Code Example: VISA or MC |
cardType string | Card Type Valid values: - CREDIT - DEBIT |
date string | Transaction Date Format: YYYY/MM/DD HH:MM:SS |
amount JSONObject | Transaction Amount “amount”:{“value”:2000, “currencyCode”:“USD”}, |
authCode string | Authorization Code |
maskedPAN string | Masked Card Number |
voidable string | Is Voidable Valid values - Y - N |
amountRefunded string | Refund Amount Only applicable to Sale transactions. “amount”:{“value”:1000, “currencyCode”:“USD”}, |
Example
Request
{
"method" : "searchPaymentTransaction",
"requestId" : "19183388",
"targetType" : "paymentGatewayConverge",
"version" : "1.0",
"parameters" : {
"first6CC" : null,
"creditCard" : null,
"utcDate" : null,
"paymentGatewayId" : "fa4742cc-f370-425f-92b7-35010a05c0ef",
"transId" : null,
"endDate" : "20160307",
"last4CC" : "4243",
"beginDate" : "20160307",
"note" : ""
}
}
Response
{
"requestId" : "19183388",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"paymentGatewayCommand" : {
"completed" : true,
"eventQueue" : [ ],
"transactionSearchResults" : {
"transactions" : [ {
"id" : "070316A15-55BFC2A6-5210-4641-BE1E-B3D06259C3DD",
"transactionType" : "PRE_AUTH",
"tenderType" : "CARD",
"cardScheme" : "VISA",
"cardType" : "CREDIT",
"date" : "2016/03/07 13:08:16",
"amount" : {
"value" : 3800,
"currencyCode" : "USD"
},
"authCode" : "******",
"maskedPan" : "******",
"currencyCode" : null,
"note" : null,
"tax" : {
"value" : 0,
"currencyCode" : "USD"
},
"expDate" : "02/2017",
"firstName" : "******",
"lastName" : "******",
"voidable" : "N",
"resultMessage" : "APPROVED",
"cardEntryType" : "SWIPE",
"iccAppName" : null,
"iccAid" : null,
"iccTvr" : null,
"iccTsi" : null,
"iccCvmr" : null,
"signatureBitmap" : null,
"gratuityAmount" : {
"value" : 0,
"currencyCode" : "USD"
}
}, {
"id" : "070316A15-E1F66058-445C-4B86-B7E7-5F80B421D690",
"transactionType" : "LINKED_REFUND",
"tenderType" : "CARD",
"cardScheme" : "VISA",
"cardType" : "CREDIT",
"date" : "2016/03/07 12:59:38",
"amount" : {
"value" : 2700,
"currencyCode" : "USD"
},
"authCode" : "******",
"maskedPan" : "******",
"currencyCode" : null,
"note" : null,
"tax" : {
"value" : 0,
"currencyCode" : "USD"
},
"expDate" : "02/2017",
"firstName" : "******",
"lastName" : "******",
"voidable" : "Y",
"resultMessage" : "APPROVED",
"cardEntryType" : "SWIPE",
"iccAppName" : null,
"iccAid" : null,
"iccTvr" : null,
"iccTsi" : null,
"iccCvmr" : null,
"signatureBitmap" : null,
"gratuityAmount" : {
"value" : 0,
"currencyCode" : "USD"
}
}, {
"id" : "070316A15-770CF503-2A1B-467F-BDF1-95E137FCA6F4",
"transactionType" : "VOID",
"tenderType" : "CARD",
"cardScheme" : "VISA",
"cardType" : "CREDIT",
"date" : "2016/03/07 12:38:32",
"amount" : {
"value" : 8800,
"currencyCode" : "USD"
},
"authCode" : "******",
"maskedPan" : "******",
"currencyCode" : null,
"note" : null,
"tax" : {
"value" : 0,
"currencyCode" : "USD"
},
"expDate" : "02/2017",
"firstName" : "******",
"lastName" : "******",
"voidable" : "N",
"resultMessage" : "APPROVED",
"cardEntryType" : "MANUALLY_ENTERED",
"iccAppName" : null,
"iccAid" : null,
"iccTvr" : null,
"iccTsi" : null,
"iccCvmr" : null,
"signatureBitmap" : null,
"gratuityAmount" : {
"value" : 0,
"currencyCode" : "USD"
}
}, {
"id" : "070316A15-0A81D9AD-6700-4E07-A82D-DF17E41F91A6",
"transactionType" : "SALE",
"tenderType" : "CARD",
"cardScheme" : "VISA",
"cardType" : "CREDIT",
"date" : "2016/03/07 12:21:25",
"amount" : {
"value" : 2500,
"currencyCode" : "USD"
},
"amountRefunded" : {
"value" : 1000,
"currencyCode" : "USD"
},
"authCode" : "******",
"maskedPan" : "******",
"currencyCode" : null,
"note" : null,
"tax" : {
"value" : 0,
"currencyCode" : "USD"
},
"expDate" : "02/2017",
"firstName" : "******",
"lastName" : "******",
"voidable" : "Y",
"resultMessage" : "APPROVED",
"cardEntryType" : "SWIPE",
"iccAppName" : null,
"iccAid" : null,
"iccTvr" : null,
"iccTsi" : null,
"iccCvmr" : null,
"signatureBitmap" : null,
"gratuityAmount" : {
"value" : 0,
"currencyCode" : "USD"
}
} ]
"status" : "SUCCESS",
"messages" : [ ]
}
}
}
}
Java
For all transaction searches, create a transaction search criteria instance.
ECLTransactionSearchCriteriaInterface searchCriteria = account.getHistorian().transactionSearchCriteria();
To search for a specific transaction, indicate the transaction ID and date. This is commonly used to retrieve more information about one transaction after searching for a range of transactions. Letu s assume you have a list of transactions in aECLTransactionSearchResults
object named results
and want to get more information on the first object in the list.
searchCriteria.setTransactionIdentifier(results[0].getIdentifier(), results[0].getUtcDateTime());
To search for all transactions in a date range, set the from
and to
property on the criteria. By default, these properties will have today’s date in to
and a week ago in from
. The date range cannot be greater than the maximumNumberOfDaysInDateRange
, which 31. You can use the validDateRange:to method
to check the validity of the date range. To set the date range from a week ago to today:
Calendar toDate = Calendar.getInstance();
toDate.set(Calendar.HOUR, 23);
toDate.set(Calendar.MINUTE, 59);
toDate.set(Calendar.SECOND, 59);
Calendar fromDate = toDate;
fromDate.add(Calendar.DATE, -7);
searchCriteria.setFrom(fromDate.getTime());
searchCriteria.setTo(toDate.getTime());
To search for credit card transactions, provide the last 4 digits of the credit card number. When provided, the from
, to
, transactionIdentifier
, and cardNumber
properties are set to nil. For example, to search for transactions where the card number ended in ‘0123’ we would do the following:
searchCriteria.setLastFourDigitsOfCardNumber("0123");
There are other properties you can set on the search criteria when not searching for a specific transaction. To see what is available, you can call the availabilityOfSearchingFor....
method and look at the result. For Converge the following are available:
- First name
- Last name
- Note
- Minimum amount
- Maximum amount
- Card type
- Card short description (card brand abbreviation)
- Transactions with tax
- Transactions with gratuity
Besides the search criteria, you also need a search listener that implements the ECLTransactionSearchListener
interface.
ECLTransactionSearchListener searchListener = new ECLTransactionSearchListener()
{
@Override
public void transactionSearchDidSucceed(ECLTransactionSearchCriteriaInterface criteria, List<ECLTransactionSearchResult> results)
{
for (ECLTransactionSearchResult result: results)
{
// Do something with the result
}
}
@Override
public void transactionSearchDidFail(
ECLTransactionSearchCriteriaInterface eclTransactionSearchCriteriaInterface,
ECCError eccError)
{
log.debug(eccError.getFullDisplayCode());
}
};
After setting all the properties for the search criteria, create our delegate and tell Commerce to start the search.
account.getHistorian().search(searchCriteria, searchListener);
Objective-C
For all transaction searches, you need to create a transaction search criteria instance:
id<ECLTransactionSearchCriteriaProtocol> searchCriteria = [account.historian transactionSearchCriteria];
If you want to search for a specific transaction you need to set the id and date to search for. Most likely case where you use this is if you have already searched for a range of transactions and want more information on one transaction. So lets assume you have a list of transactions in aECLTransactionSearchResults
object named results
and want to get more information on the first object in the list.
[searchCriteria setTransactionIdentifier:results[0].identifier dateTime:results[0].utcDateTime];
If you want to search for all transactions in a date range, you need to set the from
and to
property on the search criteria. By default, these properties will have todays date in to
and a week ago in from
. The date range cannot be more than the maximumNumberOfDaysInDateRange
(which is 31). You can use the validDateRange:to
method to see if your range is valid. Here is how you would set the date range from a week ago to today:
NSCalendar *calendar = [[NSCalendar alloc] initWithCalendarIdentifier:NSGregorianCalendar];
[calendar setTimeZone:[NSTimeZone systemTimeZone]];
NSDateComponents *todayComponents = [calendar components:(NSYearCalendarUnit| NSMonthCalendarUnit | NSDayCalendarUnit) fromDate:[NSDate date]];
[todayComponents setSecond:59];
[todayComponents setMinute:59];
[todayComponents setHour:23];
searchCriteria.to = [calendar dateFromComponents:todayComponents];
searchCriteria.from = [self.to dateByAddingTimeInterval:(-(3600 *24 *7)) + 1];
If you want to search for transactions that were used for a credit card you must provide the last 4 digits of the card. When you set this, the from
, to
, transactionIdentifier
, and cardNumber
properties are set to nil. To search for transactions where the card number ended in ‘0123’ we would do the following:
searchCriteria.lastFourDigitsOfCardNumber = @"0123";
There are other properties you can set on the search criteria when not searching for specific transaction. To see what is available you can call the availabilityOfSearchingFor....
method and look at the result. For Converge the following are available:
- First name
- Last name
- Note
- Minimum amount
- Maximum amount
- Card type
- Card short description (card scheme abbreviation)
- Transactions with tax
- Transactions with gratuity
Besides the search criteria you also need a search delegate that implements the ECLTransactionSearchDelegate
protocol.
/* In your header */
@import <Commerce-Converge/ECLTransactionSearchDelegate.h>
@interface SearchDelegate : NSObject<ECLTransactionSearchDelegate>
@end
/* In your m file */
@implementation SearchDelegate
/* transaction search succeeded! */
- (void)transactionSearchDidSucceed:(id<ECLTransactionSearchCriteriaProtocol>)criteria results:(ECLTransactionSearchResults *)results {
/* show search results */
ECLTransactionSearchResult *result;
for (int i = 0; i < results.count; i++ ) {
result = results[i];
/* Do something with the result */
}
}
/* transaction search failed! */
- (void)transactionSearchDidFail:(id<ECLTransactionSearchCriteriaProtocol>)criteria error:(NSError *)error {
NSLog(@"search failed %@", error.debugDescription);
}
@end
After you have set all the properties you want on the search criteria, you can create our delegate and tell Commerce to start the search.
[account.historian search:_searchCriteria delegate:[[SearchDelegate alloc] init]];
C#
CWS’s transaction search returns transactions as objects defined below:
public class Transaction
{
public string id { get; set; }
public string transactionType { get; set; }
public string tenderType { get; set; }
public string maskedPan { get; set; } /* nn**********nnnn */
public string cardScheme { get; set; }
public string cardType { get; set; }
public string date { get; set; }
public Money amount { get; set; }
public string authCode { get; set; }
public string note { get; set; }
public Money tax { get; set; }
public Money discount { get; set; }
public string expDate { get; set; }
public string firstName { get; set; }
public string lastName { get; set; }
public string voidable { get; set; }
public string iccAppName { get; set; }
public string iccAid { get; set; }
public string iccTvr { get; set; }
public string iccTsi { get; set; }
public string iccCvmr { get; set; }
public string iccMode { get; set; }
public string resultMessage { get; set; }
public string cardEntryType { get; set; }
public signatureBitmap signatureBitmap { get; set; }
public Money gratuityAmount { get; set; }
}
Request
TransactionSearchArgs tsa = new TransactionSearchArgs();
tsa.backEndId = m_BackEndId;
if (complete)
tsa.creditCard = tb_CreditCard.Text;
else if (last4)
tsa.last4CC = tb_CreditCard.Text;
else if (first6)
tsa.first6CC = tb_CreditCard.Text;
DateTime ?beginDate = dp_StartDate.SelectedDate;
if (beginDate.HasValue)
tsa.beginDate = beginDate.Value.ToString("yyyyMMdd");
DateTime ?endDate = dp_EndDate.SelectedDate;
if (endDate.HasValue)
tsa.endDate = endDate.Value.ToString("yyyyMMdd");
TransactionSearchResults tsr = m_CWS.TransactionSearch(tsa, null); /* Search */
Response
TransactionSearchData tsd = tsr.getTransactionSearchData();
if (null != tsd)
{
Transaction[] trans = tsd.transactions;
if (null != trans)
{
foreach (Transaction tran in trans)