Transaction Query - txnquery

This section describes the message parameters for End of Day Transaction Query processing, which you can submit using the XML API integration method. Refer to the Integration Methods section for more information.

The txnquery transaction searches for a transaction based on a date range, card data, or combination of both.

In this section:

Permissions

To use txnquery, the user whose ssl_user_id is being passed must have the Batches - View user right. Take the following steps to grant this user right:

  1. Open the Converge User Interface.
  2. Click the USER tab.
  3. Click Edit User Rights.
  4. Under the Virtual Terminal - Batch, check the box for the Batches - View. image
  5. Save the selected changes.

Request

error_outline

note

Search only allows the use of a single card information, a date range or a single card information and date range. Search does not allow multiple card information data on a single request.

ssl_merchant_id
15 | numeric | required
Merchant ID
Elavon-assigned Converge account ID.
ssl_user_id
15 | alphanumeric | required
Converge User ID
The user ID with Hosted Payment API User status that can send transaction requests through the terminal.
ssl_pin
64 | alphanumeric | required
Terminal ID
Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway.
Important: The ssl_user_id sending the transaction request must be associated with the terminal that will process the request.
ssl_transaction_type
20 | alphanumeric | required
Transaction Type
Value: txnquery
[Transaction ID]
Important: This parameter cannot be used with the Card Data and Date Range parameters.
ssl_txn_id
46 | alphanumeric | conditional
Transaction ID
Unique identifier of the original transaction.
[Additional Search Filter]
 
ssl_include_signature
- | alphanumeric | optional
Include Signature Indicator
Indicates whether to include transactions with signature images to the transaction query results.
Valid values:
  • TRUE - Include transactions with signature images
  • FALSE - Exclude transactions with signature images
[Card Data]
Use the appropriate card data parameter for the transaction.
Important: One of these parameters can be used as the search criteria or used with the Date Range parameters.
ssl_card_number
18 | numeric | conditional
Card Number
Card Number as it appears on the credit card.
ssl_track_data
76 | alphanumeric | conditional
Raw Track I and/or II Data
Track data captured from the card's magnetic stripe. The data includes beginning and ending sentinels, card's expiry date, cardholder's first name, and the cardholder's last name.
ssl_card_suffix
4 | numeric | conditional
Last 4 Digits
 
[Date Range]
Important: These parameters can be used as the search criteria or used with one of the Card Data parameters.
ssl_search_start_date
10 | alphanumeric | conditional
Search Filter - Start Date
Start date for the transaction date range. If you submit a start date without an end date, Converge sets the value of ssl_search_end_date to ssl_search_start_date plus 31 days.
Default: End date - 31 days
Format: MM/DD/YYYY
ssl_search_end_date
10 | alphanumeric | optional
Search Filter - End Date
End date for the transaction date range. If you submit an end date without a start date, Converge sets the value of ssl_search_start_date to ssl_search_end_date minus 31 days.
Default: Start date + 31 days
Format: MM/DD/YYYY
[Additional Search Filters]
Important: These parameters can only be used with the Card Data and Date Range parameters.
ssl_search_first_name
20 | alphanumeric | optional
Search Filter - First Name
Retrieve transactions based on the first names sent in the original transactions.
ssl_search_last_name
30 | alphanumeric | optional
Search Filter - Last Name
Retrieve transactions based on the last names sent in the original transactions.
ssl_search_description
255 | alphanumeric | optional
Search Filter - Merchant-defined Transaction Description
Retrieve transactions based on the merchant's custom transaction description.
ssl_search_transaction_type
20 | alphanumeric | optional
Search Filter - Transaction Type
Retrieve transactions based on transaction types.
ssl_search_min_amount
11 | numeric | optional
Search Filter - Minimum Amount
Minimum value for the transaction amount range. Values must be equal to or less than ssl_search_max_amount.
ssl_search_max_amount
11 | numeric | optional
Search Filter - Maximum Amount
Maximum value for the transaction amount range. Values must be greater than ssl_search_min_amount.
ssl_search_card_type
10 | alphanumeric | optional
Search Filter - Payment Type
Retrieve transactions based on payment types.
Valid values: CASH,  CREDITCARD,  DEBITCARD,  FOODSTAMP,  GIFTCARD,  LOYALTY
ssl_search_card_short_description
- | alphanumeric | optional
Search Filter - Card Short Description
Retrieve transactions based on card brands.
Valid values:
  • AMEX - American Express
  • CUP - China Union Pay
  • DISC - Discover
  • MC - MasterCard
  • PP - PayPal
  • VISA - Visa
ssl_search_taxed
1 | alphanumeric | optional
Search Filter - Taxed Transaction
Retrieve transactions based on sales taxes.
Valid values:
  • T - Search transactions with sales taxes
  • F - Search transactions without sales taxes
ssl_search_tipped
1 | alphanumeric | optional
Search Filter - Tipped Transaction
Retrieve transactions based on tip amounts.
Valid values:
  • T - Search transactions with tip amounts
  • F - Search transactions without tip amounts

Response

error_outline

note

  • Converge lists the query result in descending date/time order.
  • When the query is based on Transaction ID, the query result contains one single unique transaction or lists all the product line items for Level 3 transactions.
  • When the query is based on a Card Data parameter, Converge retrieves transactions from the Open and Settled batches that are within the last two months.
  • When the query is based on Card Data and Date Range parameters, Converge retrieves transactions from the Open and Settled batches that match the specified date range.
  • When the query returns more than a single transaction, the detailed response of each transaction will contain the original response along with the Transaction Status (ssl_trans_status).
ssl_user_id
15 | alphanumeric
Converge User ID
The user ID that submitted the query request.
ssl_result_message
 
Transaction Result Message
Refer to the Transaction Query Response Codes section for an extensive list of possible returned messages.
ssl_txn_id
 
Transaction ID
Unique identifier of the transaction.
ssl_txn_time
 
Processing Date and Time
Indicates when Converge processed the transaction.
Format: MM/DD/YYYY hh:mm:ss AM/PM
Example: 03/18/2010 10:34:10 AM
ssl_approval_code
 
Transaction Approval Code
Unique code returned that indicates the approval status of the transaction.
ssl_txn_count
 
Transaction Count
Number of transactions matching the search criteria.
Important:
  • Returned when the query is based on Card Data and/or Date Range.
  • The result can only show a maximum of 1000 unique transactions at one time.
ssl_next_txn_time
 
Transaction Timestamp
Timestamp of the transaction in the next set when the ssl_txn_count in the batch exceeds 1000.
Important:
  • Returned when the query is based on Card Data and/or Date Range.
  • The point-of-sale application can use this timestamp to request the next set of 1000 transactions.
ssl_trans_status
 
Transaction Transaction Status
Valid values:
  • PEN - Pended
  • OPN - Unpended / Release / Open
  • REV - Review
  • STL - Settled
  • PST - Failed Due to Post-Auth Rule
  • FPR - Failed Due to Fraud Prevention Rules
  • PRE - Failed Due to Pre-Auth Rule
ssl_card_type
 
Card Type
Payment method used for the transaction.
Valid values: CREDITCARDDEBITCARDFOODSTAMPCASHBENEFITELECTRONICCHECKGIFTCARDLOYALTYCASH
ssl_transaction_type
 
Transaction Type
 
ssl_card_number
 
Masked Card Number
Converge only returns the first 2 or last 4 digits of the regular PAN, or the last 4 digits of the actual card number if it is an association token (example, ApplePay).
ssl_entry_mode
2 | numeric
Transaction Entry Indicator
Indicates how the track data was captured.
Valid values:
  • K - Hand-Keyed
  • S - Swiped
ssl_avs_response
 
Address Verification Response Code
Refer to the AVS Response Codes section for a complete list of AVS response codes.
ssl_cvv2_response
 
Card Verification Response Code
Refer to the CVV2/CVC2 Response Codes section for a complete list of CVV/CVC2 response codes.
ssl_amount
 
Total Authorized/Approved Transaction Amount
Returned based on merchant setup.
ssl_invoice_number
 
Invoice Number
The invoice number or ticket number sent in the original request.
Returned based on merchant setup.
ssl_salestax
8 | alphanumeric | optional
Sales Tax
 
ssl_description
 
Merchant-defined Transaction Description
Short and custom text to describe the transaction.
[Card Data/Date Range]
Returned when query is based on Card Data and/or Date Range parameters.
ssl_card_short_description
 
Short Card Brand Name
 
ssl_tip_amount
 
Tip Amount
 
[Transaction ID]
Returned when query is based on Transaction ID parameters.
ssl_avs_address
 
Address Line 1
Commonly the house number and street name on the cardholder's / customer's account or billing address.
Returned based on merchant setup.
ssl_address2
 
Address Line 2
Apartment or condominium unit number and floor number on the cardholder's or customer's account or billing address.
ssl_address3
 
Address Line 3
 
ssl_company
 
Company Name
Company name on the cardholder's / customer's account or billing address.
ssl_city
 
City
City name on the cardholder's / customer's account or billing address.
ssl_state
 
State Code
State or province code on the cardholder's / customer's account or billing address.
ssl_avs_zip
 
Postal or ZIP Code
Postal or ZIP code on the cardholder's or customer's account or billing address.
ssl_country
 
Country ISO Code
Country ISO code on the cardholder's / customer's account or billing address.
ssl_cardholder_currency
 
Cardholder Currency
 
ssl_terminal_currency
 
Terminal Currency
 
ssl_cardholder_amount
 
Cardholder Amount
Total amount in the cardholder's billing currency.
ssl_tip_amount
 
Tip Amount
 
ssl_cardholder_tip_amount
 
Tip Amount
Tip amount in the cardholder currency.
ssl_is_voidable
 
Void Indicator
 
ssl_account_balance
 
Account Balance
Available balance on the card.
ssl_departure_Date
 
Travel Departure Date
 
ssl_completion_Date
 
Travel Completion Date
 
ssl_ship_to_first_name
 
Ship To First Name
 
ssl_ship_to_last_name
 
Ship To Last Name
 
ssl_ship_to_company
 
Ship To Company Name
 
ssl_ship_to_address1
 
Ship To Address Line 1
 
ssl_ship_to_address2
 
Ship To Address Line 2
 
ssl_ship_to_address3
 
Ship To Address Line 3
 
ssl_ship_to_city
 
Ship To City
 
ssl_ship_to_state
 
Ship To State Code
 
ssl_ship_to_zip
 
Ship To Postal or ZIP Code
 
ssl_ship_to_country
 
Ship To Country ISO Code
 
ssl_signature_image
 
Signature Image
Digital version of the cardholder's signature.
ssl_image_type
 
Signature Image Format
File format of the signature image.
Valid values: GIF, TIF, JPG, PNG
[Error]
Returned only if an error occurs. Refer to the Error Codes section for more information.
errorCode
 
Error Code
Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field.
errorMessage
 
Error Message
Detailed explanation of the error. This field may be changed based on merchant configuration in the user interface.
errorName
 
Error Name
Error name or reason for the error.

Examples

error_outline

important

  • In these examples, you will have to change the data values, such as my_merchant_id, my_user_id, my_pin, and transaction data to match your Converge account and meet the needs of your website.
  • Code samples provided are for demonstration only and should not be used for live transactions. All sensitive merchant data, including transaction amounts and your Converge credentials, should be placed in server side code.

Query Based on Transaction ID

Request

<txn>
    <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_test_mode>false</ssl_test_mode>
    <ssl_transaction_type>txnquery</ssl_transaction_type>
    <ssl_txn_id>AA786F-4CEC21A7-B70A-4584-AC8C-5040C0297354</ssl_txn_id>
</txn>

Response

<txn>
    <ssl_txn_id>AA786F-4CEC21A7-B70A-4584-AC8C-5040C0297354</ssl_txn_id>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_trans_status>STL</ssl_trans_status>
    <ssl_card_type>CREDITCARD</ssl_card_type>
    <ssl_transaction_type>CCSALE</ssl_transaction_type>
    <ssl_txn_time>12/18/2013 09:13:24 AM</ssl_txn_time>
    <ssl_first_name>George P.</ssl_first_name>
    <ssl_last_name>Burdell</ssl_last_name>
    <ssl_card_number>00**********0000</ssl_card_number>
    <ssl_exp_date>1216</ssl_exp_date>
    <ssl_entry_mode>K</ssl_entry_mode>
    <ssl_avs_response />
    <ssl_cvv2_response />
    <ssl_amount>5.00</ssl_amount>
    <ssl_invoice_number />
    <ssl_result_message>APPROVAL</ssl_result_message>
    <ssl_approval_code>N29032</ssl_approval_code>
</txn>

Query Based on Date Range

Request

<txn>
    <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_transaction_type>txnquery</ssl_transaction_type>
    <ssl_search_start_date>04/30/2015 09:34:36 AM</ssl_search_start_date>
    <ssl_search_end_date>04/30/2015 09:34:36 PM</ssl_search_end_date>
</txn>

Query Based on Card Number

Request

<txn>
    <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
    <ssl_user_id>my_user_pin</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_test_mode>false</ssl_test_mode>
    <ssl_transaction_type>txnquery</ssl_transaction_type>
    <ssl_card_number>[Full Card Number]</ssl_card_number>
</txn>

Response

<txnlist>
    <ssl_txn_count>2</ssl_txn_count>
    <txn>
        <ssl_txn_id>AA786F-4CEC21A7-B70A-4584-AC8C-5040C0297354</ssl_txn_id>
        <ssl_user_id>my_user_id</ssl_user_id>
        <ssl_trans_status>STL</ssl_trans_status>
        <ssl_card_type>CREDITCARD</ssl_card_type>
        <ssl_transaction_type>CCSALE</ssl_transaction_type>
        <ssl_txn_time>12/18/2013 09:13:24 AM</ssl_txn_time>
        <ssl_first_name>George P.</ssl_first_name>
        <ssl_last_name>Burdell</ssl_last_name>
        <ssl_card_number>00**********0000</ssl_card_number>
        <ssl_exp_date>1216</ssl_exp_date>
        <ssl_entry_mode>K</ssl_entry_mode>
        <ssl_avs_response />
        <ssl_cvv2_response />
        <ssl_amount>5.00</ssl_amount>
        <ssl_invoice_number />
        <ssl_result_message>APPROVAL</ssl_result_message>
        <ssl_approval_code>N29032</ssl_approval_code>
    </txn>
    <txn>
        <ssl_txn_id>AA786F-4CEC21A7-B70A-4584-AC8C-5040C0297354</ssl_txn_id>
        <ssl_user_id>my_user_id</ssl_user_id>
        <ssl_trans_status>STL</ssl_trans_status>
        <ssl_card_type>CREDITCARD</ssl_card_type>
        <ssl_transaction_type>CCSALE</ssl_transaction_type>
        <ssl_txn_time>12/18/2013 09:13:24 AM</ssl_txn_time>
        <ssl_first_name>George P.</ssl_first_name>
        <ssl_last_name>Burdell</ssl_last_name>
        <ssl_card_number>00**********0000</ssl_card_number>
        <ssl_exp_date>1216</ssl_exp_date>
        <ssl_entry_mode>K</ssl_entry_mode>
        <ssl_avs_response />
        <ssl_cvv2_response />
        <ssl_amount>5.00</ssl_amount>
        <ssl_invoice_number />
        <ssl_result_message>APPROVAL</ssl_result_message>
        <ssl_approval_code>N29032</ssl_approval_code>
    </txn>
<txnlist>

Query Based on Track Data

Request

<txn>
    <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_test_mode>false</ssl_test_mode>
    <ssl_transaction_type>txnquery</ssl_transaction_type>
    <ssl_track_data>[Track Data]</ssl_track_data>
</txn>

Query Based on Last 4 Digits of a Card Number

Request

<txn>
    <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_test_mode>false</ssl_test_mode>
    <ssl_transaction_type>txnquery</ssl_transaction_type>
    <ssl_card_suffix>3003</ssl_card_suffix>
</txn>

Transaction Query with Line Item

Request

<txn>
  <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
  <ssl_user_id>my_user_id</ssl_user_id>
  <ssl_pin>my_pin</ssl_pin>
  <ssl_transaction_type>BITXNQUERY</ssl_transaction_type>
  <ssl_transaction_type>txnquery</ssl_transaction_type>
  <ssl_txn_id>061118MB-1CEEFA33-03E3-4439-A2CE-6118F519390E</ssl_txn_id>
</txn>

Response

<txn>
  <ssl_txn_id>061118MB-1CEEFA33-03E3-4439-A2CE-6118F519390E</ssl_txn_id>
  <ssl_user_id>my_user_id</ssl_user_id>
  <ssl_trans_status>OPN</ssl_trans_status>
  <ssl_card_type>CREDITCARD</ssl_card_type>
  <ssl_card_short_description>VISA</ssl_card_short_description>
  <ssl_transaction_type>CCSALE</ssl_transaction_type>
  <ssl_txn_time>11/06/2018 02:33:39 PM</ssl_txn_time>
  <ssl_card_number>40**********0002</ssl_card_number>
  <ssl_exp_date>1221</ssl_exp_date>
  <ssl_entry_mode>K</ssl_entry_mode>
  <ssl_amount>5.00</ssl_amount>
  <ssl_result_message>APPROVAL</ssl_result_message>
  <ssl_approval_code>902740</ssl_approval_code>
  <ssl_transaction_language>en</ssl_transaction_language>
  <ssl_cardholder_currency>CAD</ssl_cardholder_currency>
  <ssl_terminal_currency>CAD</ssl_terminal_currency>
  <ssl_is_voidable>TRUE</ssl_is_voidable>
  <ssl_account_balance>0.00</ssl_account_balance>
  <lineItemProducts>
    <product>
    <ssl_line_Item_description>Product-169</ssl_line_Item_description>
    <ssl_line_Item_product_code>PRO-169</ssl_line_Item_product_code>
    <ssl_line_Item_commodity_code>10000169</ssl_line_Item_commodity_code>
    <ssl_line_Item_quantity>1</ssl_line_Item_quantity>
    <ssl_line_Item_unit_of_measure>EC</ssl_line_Item_unit_of_measure>
    <ssl_line_Item_unit_cost>5.00</ssl_line_Item_unit_cost>
    <ssl_line_Item_discount_indicator>N</ssl_line_Item_discount_indicator>
    <ssl_line_Item_discount_amount>0.00</ssl_line_Item_discount_amount>
    <ssl_line_Item_tax_Indicator/>
    <ssl_line_Item_tax_rate/>
    <ssl_line_Item_tax_amount/>
    <ssl_line_Item_tax_type/>
    <ssl_line_Item_extended_total>5.00</ssl_line_Item_extended_total>
    <ssl_line_Item_total>5.00</ssl_line_Item_total>
    </product>
  </lineItemProducts>
</txn>