Skip to main content

Instant Order Search Export (ISE)

Instant Order Search Export (ISE)

Last updated: 15-Mar-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. In order to use SHA2 or SHA3 for auth, simply pass SHA2 or SHA3 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,Backup Media Cost,Backup Media 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. In order to use SHA2 or SHA3 for auth, simply pass SHA2 or SHA3 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