Transaction Lookup

This transaction searches for previous Sale, Pre-Auth, Refund, and Void transactions.

Code Samples

CWS

Request

Response

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)