Transaction Lookup

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

Code Samples

CWS

Request

PropertyDescription
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

PropertyDescription
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)