Skip to main content

Instant Order Search Export (ISE)

Instant Order Search Export (ISE)

Last updated: 15-Oct-2024
Rate this article:

Overview

Export order data for your account from the 2Checkout platform.

Instant Order Search Export (ISE) works as a data portability service designed to let you export order information from your 2Checkout account packaged as either CSV or XML files. 

   Most orders should be available in the search results almost instantly, but there might be situations where it might take up to 15 minutes for an order to be available in search results.

Availability

ISE is available to all 2Checkout accounts.

Method and URL

GET or POST: https://secure.2checkout.com/action/ise?

Parameters for eStore orders

2Checkout captures the parameters you send and exports the data to the client.

Field Description Required Used in HASH validation
MERCHANT Your 2Checkout merchant code. The merchant code and secret key for your account are available here. Required, cannot be empty YES
STARTDATE The start date, in format Y-m-d (ex: 2010-05-22) Required, cannot be empty YES
ENDDATE The end date, in format Y-m-d (ex: 2010-05-22) Required, cannot be empty YES
ORDERSTATUS

The order status:

  • ALL 
  • COMPLETE 
  • REFUND 
  • UNFINISHED
  • COMPLETE_AND_REFUND
  • REVERSED
Required, cannot be empty YES
REQ_DATE

The time of request (UTC), in format YmdHis:

Y = year, 4 digits

m = month, 2 digits

d = day, 2 digits

H = hour, 2 digits

i = minute, 2 digits

s = seconds, 2 digits

Required, cannot be empty YES
PRODUCT_ID Unique, system-generated 2Checkout product identifier Required, can be empty YES
COUNTRY_CODE Two letter country code (download a complete list from via this link) Required, can be empty YES
FILTER_STRING Query value that depends on the value of the FILTER_FIELD. See FILTER_FIELD for more info. Required, can be empty YES
FILTER_FIELD

Filter field designed to lower the search result. Use in conjunction with FILTER_STRING.

Possible values:

  • REFNO (2Checkout order reference) 
  • REFNOEXT (vendor order reference) 
  • NAME (customer name or company) 
  • EMAIL (customer billing email) 
  • COUPONCODE (order coupon code)
  • AFFLIATEID (orders from a specific affiliate)

To search only a particular order, the value of FILTER_FIELD needs to be REFNO, while the value of the FILTER_STRING should be the unique order reference from the 2Checkout system.

Required, can be empty YES
HASH The SHA256 HMAC key for the request Required N/A
SIGNATURE_ALG  The hashing algorithm used to authenticate the request. To use SHA2 or SHA3 for auth, simply pass sha256 or sha3-256 as value for the SIGNATURE_ALG parameter. Required NO
INCLUDE_DELIVERED_CODES Includes delivered codes Optional NO
INCLUDE_FINANCIAL_DETAILS Includes financial details. (Net profit, DIS COST, DIS Profit) Optional NO
INCLUDE_EXCHANGE_RATES Includes exchange rates Optional NO
INCLUDE_PRICING_OPTIONS Includes pricing options (pricing option text, pricing options value) Optional NO
EXPORT_FORMAT

This parameter controls the format of file used for the export process. Possible values:

  • CSV
  • XML
Optional NO
INCLUDE_CLIENTIP Include end user IP address Optional NO
INCLUDE_NETINCOMEPERPRODUCT Include net income per product Optional NO
USE_REPORT_MODE
  • YES - the search process returns orders in accordance with the date when they reached the Finished status. Finish date needs to be within the STARTDATE and ENDDATE interval.
  • NO (default) - the search process returns orders in accordance with the date when they were placed. Place order date need to be within the STARTDATE and ENDDATE interval.
Optional NO
EXPORT_TEST_ORDERS

Possible values:

  • YES - Include test orders along with real order.
  • NO (default) - Do not include test order data and export only details for actual purchases.
  • ONLY - Export only test order data.
Optional NO
EXPORT_TEMPLATE_ID

Return order search information specific to templates configured for Order Search Export by using their unique IDs. For eStore, navigate to Order search under Orders &customers and make sure that the eStore orders tab is selected. Run a search to identify the orders you're looking for, and on the right hand side of the screen click the Export button, and the Edit templates link in the popup dialog box. The template identifier is visible in the URL as the IdTemplate parameter. 

When using EXPORT_TEMPLATE_ID, you can exclude INCLUDE_DELIVERED_CODES, INCLUDE_FINANCIAL_DETAILS, INCLUDE_EXCHANGE_RATES, INCLUDE_PRICING_OPTIONS, INCLUDE_CLIENTIP and INCLUDE_NETINCOMEPERPRODUCT, if the Order search Export template already contains such information.

Data in the Order Search Export template takes precedence over INCLUDE_DELIVERED_CODES, INCLUDE_FINANCIAL_DETAILS, INCLUDE_EXCHANGE_RATES, INCLUDE_PRICING_OPTIONS, INCLUDE_CLIENTIP and INCLUDE_NETINCOMEPERPRODUCT - this means that these parameters are ignored if they overlap with template fields.

Optional NO
INCLUDE_CHARGEBACKS_STATUS_AND_REASON

Includes the status and reason provided for chargebacks. Available values:

  • YES
  • NO
Optional NO
EXPORT_TIMEZONE_REGION

Controls the timezone provided in STARTDATE and ENDDATE fields. Example: 'Europe/London'. Check the values accepted as strings here.

If not provided, the timezone used is the API timezone set up in Control Panel. If no API timezone is set, the default platform timezone is used. Daylight saving time is considered in the timezone region parameter.

Optional NO

Parameters for Partner orders

Field Description Required Used in HASH validation
MERCHANT Your 2Checkout merchant code. The merchant code and secret key for your account are available here. Required, cannot be empty YES
STARTDATE The start date, in format Y-m-d (ex: 2010-05-22) Required, cannot be empty YES
ENDDATE The end date, in format Y-m-d (ex: 2010-05-22) Required, cannot be empty YES
ORDERSTATUS

The order status:

  • REFUNDED
  • PENDING_APPROVAL
  • CANCELED
  • REJECTED
  • COMPLETE
  • AWAITING_PAYMENT
  • DELIVERY_NEEDS_INFO
Required, cannot be empty YES
REQ_DATE

The time of request (UTC), in format YmdHis:

Y = year, 4 digits

m = month, 2 digits

d = day, 2 digits

H = hour, 2 digits

i = minute, 2 digits

s = seconds, 2 digits

Required, cannot be empty YES
PRODUCT_ID Unique, system-generated 2Checkout product identifier. Required, can be empty YES
PARTNER_CODE Partners codes can be viewed by selecting each partner from here. Required, can be empty. If empty, default is all. Supports multiple codes per message, separated by a comma. NO
SUBSCRIPTION_TYPE

Subscription types:

  • NEW
  • RENEWAL
  • UPGRADE
Required, can be empty. If empty, default is all. NO
SOURCE

Source of the partner order:

  • PARTNER
  • VENDOR
Required, can be empty. If empty, default is all. NO
PRICELIST_CODE Price lists codes can be viewed by selecting each price list from here. Required, can be empty. NO
COUNTRY_CODE Two letter country code (download a complete list from this link) Required, can be empty. YES
FILTER_STRING Query value that depends on the value of the FILTER_FIELD. See FILTER_FIELD for more info. Required, can be empty. YES
FILTER_FIELD

FILTER_FIELD is designed to lower the search result. Use in conjunction with FILTER_STRING.

Possible values:

  • REFNO (2Checkout reference number)
  • PARTNER_REFNO (partner reference number)
  • PARTNER_INVOICE_NUMBER
  • SKU

To search only a particular order, the value of FILTER_FIELD needs to be REFNO, while the value of the FILTER_STRING should be the unique order reference from the 2Checkout system.

Required, can be empty. In conjunction with FILTER_STRING. YES
HASH The SHA256 HMAC key for the request. Required N/A
SIGNATURE_ALG  The hashing algorithm used to authenticate the request. To use SHA2 or SHA3 for auth, simply pass sha256 or sha3-256 as value for the SIGNATURE_ALG parameter. Required NO
EXPORT_FORMAT

This parameter controls the format of file used for the export process. Possible values:

  • CSV
  • XML
Optional NO
USE_REPORT_MODE
  • YES - the search process returns orders in accordance with the date when they reached the Finished status. Finish date needs to be within the STARTDATE and ENDDATE interval.
  • NO (default) - the search process returns orders in accordance with the date when they were placed. Place order date needs to be within the STARTDATE and ENDDATE interval.
Optional NO
PARTNER_INVOICE_DATE The date in format Y-m-d (ex: 2010-05-22). It filters the results and returns orders in accordance with the date when a partner invoice was generated for these orders. Optional  NO
EXPORT_TEMPLATE_ID

Return order search information specific to templates configured for Order Search Export by using their unique IDs. For Partner Orders, navigate to Order search under Orders &customers and make sure that the Partner orders tab is selected. Run a search to identify the orders you're looking for, and on the right hand side of the screen click the Export button, and the Edit templates link in the popup dialog box. The template identifier is visible in the URL as the IdTemplate parameter. 

 

When using EXPORT_TEMPLATE_ID, you can exclude INCLUDE_DELIVERED_CODES, INCLUDE_FINANCIAL_DETAILS, INCLUDE_EXCHANGE_RATES, INCLUDE_PRICING_OPTIONS, INCLUDE_CLIENTIP, and INCLUDE_NETINCOMEPERPRODUCT, if the Order search Export template already contains such information.

Data in the Order Search Export template takes precedence over INCLUDE_DELIVERED_CODES, INCLUDE_FINANCIAL_DETAILS, INCLUDE_EXCHANGE_RATES, INCLUDE_PRICING_OPTIONS, INCLUDE_CLIENTIP and INCLUDE_NETINCOMEPERPRODUCT - this means that these parameters are ignored if they overlap with template fields.

Optional NO
CHANNEL_TYPE

Specifies if the ISE should return eStore orders or Partner orders. Possible values:

  • ECOMMERCE (default)
  • PARTNER
Optional  NO

Requirements

HASH validation

  • To validate the SHA256 hash signature, you're required to include all mandatory parameters. 2Checkout throws an error if one of these parameters is missing.
  • Include PRODUCT_ID and COUNTRY_CODE. Use empty values to return all results. 
  • The interval between STARTDATE and ENDDATE can not be greater than 45 days (for performance purposes).
  • Use UTC for the time zone of REQ_DATE. The difference between the value of REQ_DATE and the moment when you send the request to 2Checkout must be smaller than 5 minutes, or 2Checkout will respond with the 'Request expired' error message. 

Authentication

Authenticate requests using:

  • HASH. This ia a SHA256 Hash-based message authentication code (HMAC) that you create using your account's secret key and the parameters marked as mandatory for HASH validation.  To build the HMACSHA256{}  source string, prepend each value with its own length in bytes. Use 0 for null or empty values without prepending their length. However, when the value is 0 (zero), you do need to prepend its length (1). Note that for UTF-8 characters the length in bytes can be longer that the string length.
  • REQ_DATE. Use UTC time zone. 

Optional: the authentication can be restricted by IP or range of IPs from firewall (Accounts settings ->User access -> Firewall) for the special service user. If the IP from where you make the request is not configured in 2Checkout, the authentication fails.

Response

Provided that your request is valid, you will receive the information in line, in the requested format (parameter EXPORT_FORMAT), with HTTP code 200.

Errors

2Checkout returns errors in XML format. This includes authentication errors and no results after a search message. 2Checkout throws errors with a 400 HTTP error code for the result page. Sample response XML:

<EPAYMENT> 
<RESPONSE_CODE>1</RESPONSE_CODE> 
<RESPONSE_MSG>Request has expired</RESPONSE_MSG> 
<RESPONSE_DATE>20110209144927</RESPONSE_DATE> 
<HASH>2f69dda102b2a29e077452f64f4dca1f</HASH> 
</EPAYMENT>

The XML can be validated using the same SHA256 HMAC signature algorithm, using these fields: RESPONSE_CODE, RESPONSE_MSG, RESPONSE_DATE and using the account hash key.

Field Description
RESPONSE_CODE The response code (two digits)
RESPONSE_MSG A more explanatory response message
RESPONSE_DATE

The time of response (UTC), in format YmdHis:

Y = year, 4 digits

m = month, 2 digits

d = day, 2 digits

H = hour, 2 digits

i = minute, 2 digits

s = seconds, 2 digits

 

Possible error codes and values:

Message code Message description Resolution
0 No result found for the searched criteria Check search filters.
1 Request has expired Check REQ_DATE.
2 Not all the mandatory variables are present See required fields above.
3 The selected interval is greater than 45 days Check STARTDATE and ENDDATE.
4 MERCHANT is missing or incorrect Check MERCHANT value.
5 ORDERSTATUS is missing or invalid Check ORDERSTATUS value.
6 Ip not allowed by firewall Check firewall rules for special service user.
7 HASH is missing or invalid Double check how SHA256 hash signature is calculated.
8 REQ_DATE is missing or invalid REQ_DATE is missing or not in the right format.
9 FILTER_FIELD is invalid Check possible values of FILTER_FIELD.
10 FILTER_STRING is missing or invalid FILTER_FIELD is set to limit search. Check FILTER_STRING value.
11 Module is not active for your account Instant Search Export service is not active for your account. Please contact account manager.
12 EXPORT_TEMPLATE_ID is invalid Check the EXPORT_TEMPLATE_ID value.
13 Country code is incorrect. Provide a valid country code.
14 Provided time zone region is incorrect Check EXPORT_TIMEZONE_REGION value.
15 PARTNER_CODE is invalid Check “Partner code” in View partner section in cPanel.
16 PRICELIST_CODE is invalid Check “Price list code” in Edit price list section in cPanel.

 

Code sample for eStore orders

<?php
/*
 Name: Example for Instant Search Export in Avangate (www.avangate.com)
 GET OR POST SENT
*/

$secret_key = 'SECRET_KEY'; //secret key is available on this page https://secure.2checkout.com/cpanel/account_settings.php
$base_link = 'http://secure.avangate.local/action/ise.php';
$proxy_user = 'PROXY_USER_IF_NEEDED';
$proxy_pass = 'PROXY_PASSWORD_IF_NEEDED';
date_default_timezone_set('UTC');


//*********SETTING PARAMETERS*********
$link_params = array();
$algo = 'sha256'; // or sha3-256
$not_in_hash = array(
    'HASH',
    'INCLUDE_DELIVERED_CODES',
    'INCLUDE_FINANCIAL_DETAILS',
    'INCLUDE_EXCHANGE_RATES',
    'INCLUDE_PRICING_OPTIONS',
    'EXPORT_FORMAT',
    'EXPORT_TIMEZONE_REGION',
    'SIGNATURE_ALG',
);

//REQUIRED, CANNOT BE EMPTY:
$link_params['MERCHANT'] = 'MALWARQO'; //merchant code is available on this page https://secure.2checkout.com/cpanel/account_settings.php
$link_params['STARTDATE'] = date(
    "Y-m-d",
    strtotime('-1 month', strtotime(date('Y') . '/' . date('m') . '/01' . ' 00:00:00'))
); //first day from last month
$link_params['ENDDATE'] = date(
    "Y-m-d",
    strtotime('-1 second', strtotime(date('Y') . '/' . date('m') . '/01' . ' 00:00:00'))
); //last day from last month

$link_params['ORDERSTATUS'] = 'ALL'; // replace with any of  ALL, COMPLETE, REFUNDED, UNFINISHED
$link_params['REQ_DATE'] = date('YmdHis');

//CAN BE EMPTY:
$link_params['PRODUCT_ID'] = '';
$link_params['COUNTRY_CODE'] = '';
$link_params['FILTER_STRING'] = '';
$link_params['SIGNATURE_ALG'] = $algo;

//REQUIRED, CAN BE EMPTY:
$link_params['FILTER_FIELD'] = ''; // EMPTY OR: REFNO, REFNOEXT, NAME, EMAIL, COUPONCODE

//REQUIRED:
$link_params['HASH'] = '';

//OPTIONAL:
$link_params['INCLUDE_DELIVERED_CODES'] = '';
$link_params['INCLUDE_FINANCIAL_DETAILS'] = '';
$link_params['INCLUDE_EXCHANGE_RATES'] = '';
$link_params['INCLUDE_PRICING_OPTIONS'] = '';
$link_params['EXPORT_FORMAT'] = 'XML'; //possible values CSV or XML -    if you’re using this sample, please specify the desired export format
$link_params['EXPORT_TIMEZONE_REGION'] = 'Europe/London';

//*********GET Base string for HMAC_SHA256 calculation:*********
$result = '';
foreach ($link_params as $key => $val) {
    $$key = $val;
    /* get values */
    if (!in_array($key, $not_in_hash)) {
        if (is_array($val)) {
            $result .= ArrayExpand($val);
        } else {
            $size = strlen(StripSlashes($val));
            $result .= $size . StripSlashes($val);
        }
    }
}


//*********Calculated HMAC_SHA256 signature:*********
$hash = hash_hmac($algo, $result, $secret_key);
$link_params['HASH'] = $hash;

$get_vars = http_build_query($link_params, '', '&');


//*********MAKE POST CALL to get ISE results*********
$ch = curl_init($base_link . '?' . $get_vars);
curl_setopt($ch, CURLOPT_POSTFIELDS, null);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
//**use the following 3 lines only if you have a proxy set!**
//curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, 1);
//curl_setopt($ch, CURLOPT_PROXY, 'YOUR_PROXY_ADDRESS:PORT');
//curl_setopt($ch, CURLOPT_PROXYUSERPWD, $proxy_user.':'.$proxy_pass);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // RETURN THE CONTENTS OF THE CALL
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
$responseData = curl_exec($ch);
$headerCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
//echo 'Curl error: '.curl_error($ch);
curl_close($ch);


//*********PROCESS RESULTS*********
if ($headerCode == 200) {
    // do something with the csv or xml received
    //the format of the export file is set using $link_params['EXPORT_FORMAT']
    $exportType = strtolower($link_params['EXPORT_FORMAT']);
    $headerType = 'Content-type: application/' . $exportType . ';charset=UTF-8';
    $headerDisposition = 'Content-Disposition: attachment; filename="ise.' . $exportType . '"';
    header($headerType);
    header($headerDisposition);
    echo $responseData;
} else {
    //no valid answer received: request period is too big, etc.
    if (strpos($contentType, 'xml') === false) {
        echo 'Header returned: ' . $headerCode;
        echo $responseData;
    } else {
        //YOUR CODE HERE AFTER RECEIVING the xml with one of the codes from Instant Search Export Handbook
        $xml = $responseData;
        $xml = simplexml_load_string($xml);
        $response = array();
        $i = 0;
        foreach ($xml->children() as $child) {
            $response[$i] = $child;
            $i++;
        }
        echo $xml->asXML();
    }
}

//*********FUNCTIONS FOR HMAC*********
function ArrayExpand($array)
{
    $retval = "";
    foreach ($array as $i => $value) {
        if (is_array($value)) {
            $retval .= ArrayExpand($value);
        } else {
            $size = strlen(StripSlashes($value));
            $retval .= $size . StripSlashes($value);
        }
    }

    return $retval;
}
Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo