Screen: ShopSite > Orders

Automatic XML Orders Download

You can use a merchant-supplied program to automatically download a store’s orders as an XML-formatted text file. This help page describes the programmatic interface; the XML DTD is described on Orders Download XML Format.

Your orders download program must send a request to a ShopSite Authorization CGI program (authorize.cgi) and provide authentication to receive a token that can authorize a request to a ShopSite Download CGI program (db_xml.cgi) to start the download. To keep order information secure, the ShopSite CGI program must be invoked through a secure connection (https). If the connection is not secure, customer credit card information will not be included in the download.

The db_xml.cgi program can accept these optional parameters:

• version - The order database format, based off the ShopSite version. You may need to specify an earlier version for compatibility with third-party applications. If a version is not specified, ShopSite will default to the version selected in the Order Download configuration screen, or the version of the original ShopSite installation (not the current version). Available versions are: 6.3, 7.0, 7.1, 8.0, 8.1, 8.2, 8.3, 9.0, 10.0, 10.1, 10.2, and 11.0.
• startorder - The order number of the first order to include in the download. If not specified, the download starts with the oldest order.
• endorder - The order number of the last order to include in the download. If not specified, all orders after startorder will be included, or until maxorder is reached.
• startdate - The date of the oldest orders to download, in mm/dd/yyyy format. The date is based on server time.
• enddate - The date of the newest orders to download, in mm/dd/yyyy format. The date is based on server time.
• maxorder - The maximum number of orders to download.
• pay - Include payment information (credit card details) in the download. The recommended value for this parameter is "yes". If this parameter is not included in the command line or if a secure connection is not used, the download will not include payment information.

  Note:

  CVV2 information is only stored by ShopSite when the store is accepting credit cards for manual processing. This information is purged from ShopSite when orders are viewed or downloaded. Sometimes it is necessary to download the order information before authorizations occur, such as when using order managing software. For example, let's say that you manually authorize your credit card transactions and have an order manager that automatically downloads information from ShopSite. When those orders are downloaded to the order manager, the CVV2 information is purged from ShopSite, even if it is not used by the order manager. By setting the value for the "pay" parameter to "no_cvv" ( pay=no_cvv ), the CVV2 information will remain in ShopSite until the order is viewed or downloaded through the back office.

• html - Display downloaded orders as HTML output in the browser window.
• dkey - The URL encoded key used to decrypt payment information if merchant key encryption is used. If the merchant is using merchant key encryption, the key must be read into a buffer from a file on the merchant's client, URL encoded (keys may include carriage returns, line feeds, and plus characters that must be converted to their hexadecimal codes, %0D, %0A, and %2B respectively), and transmitted securely to the server as the value for the dkey attribute, or else encrypted payment information will not be readable.

While it is possible to use startorder and endorder or startdate and enddate to download a specific set of orders, you do not have to use both the start and end value. You could, for example, use startdate without enddate to download all the orders that have come in since the last time you downloaded orders.

The db_xml.cgi will output the following line, followed by the XML order information:

Content-type: application/x-www-form-urlencoded\n\n

Example Program

This example program functions as though the client has already entered the appropriate information on the Application screen of the back office and relies heavily on the sample OAuth source code provided here.

From the back office:

• client id = B9D3299B
• authorization code = MTQxMDZ8ZGViYmllfDJ8
• secret key = CCAB-DFB5-C73A-5228

Generated by the OAuth sample code:

• nonce for token request = 80026bc7
• nonce for download request = 503bb763
• client credentials (client id:nonce for token) = B9D3299B:80026bc7
• encoded credentials (base64 encoded client credentials) = QjlEMzI5OUI6ODAwMjZiYzc=
• token = MTMwMjA5NjAyOHxkZWJiaWV8MnxCYWlsZXl8MjU2fA==
• timestamp = 1302101084
• signature for token request (encoded credentials, signed with secret key, then base64 encoded) = rfw0k21l9YdXl0r240Uw+3aa9A4=
• signature for download request (request URL and query string, signed with secret key, then base64 encoded) = LXIUwI9RSLqzd19GpOJnbO0hTQg=

This example uses a non-secure connection to request order information, starting with order number 1962. Because the CGI directory on the server requires authentication, the program first requests a token from ShopSite, passing the authentication keys set up on the Application screen in the back office. It then passes the token as authentication for the order information request. This program does not process the XML, so it does not test the response values (Success or Failure).

if ((msg_socket = getconnection("mystore.com",80)) == -1)
{
  printf("Big trouble, no socket connection\n");
  exit(1);
}

    /* create the HTTP header for authentication request */
sprintf(send_msg,
  "POST /cgi-bin/ss/authorize.cgi HTTP/1.1\n"
  "Host: mystore.com:80\r\n"
  "Content-Type: application/x-www-form-urlencoded"
  "grant_type=authorization_code&code=MTQxMDZ8ZGViYmllfDJ8&client_credentials=QjlEMzI5OUI6ODAwMjZiYzc=&signature=rfw0k21l9YdXl0r240Uw+3aa9A4=");
    /* send the HTTP header for authentication request */
resource = send(msg_socket, send_msg, strlen(send_msg),0);

    /* create the HTTP header for download */
sprintf(send_msg,
  "POST /cgi-bin/ss/db_xml.cgi?startorder=1962 HTTP/1.1\n"
  "Host: mystore.com:80\r\n"
  "Content-Type: application/x-www-form-urlencoded"
  “clientApp=1&dbname=orders&version=11.0&token=MTMwMjA5NjAyOHxkZWJiaWV8MnxCYWlsZXl8MjU2fA==&timestamp=1302101084&nonce=503bb763&signature=LXIUwI9RSLqzd19GpOJnbO0hTQg=”);

    /* send the HTTP header for download */
count = send(msg_socket, send_msg, strlen(send_msg),0);

    /* loop to receive order info */
while (count = recv(msg_socket, buf, 2048, 0))
{
  buf[count] = '\0';
  printf("%s",buf); /* since just testing write the order info to the screen */

    /* Here is where you would create a buffer /*
    /* containing all the order info */
    /* and then process that information */
}

close(msg_socket);

The getconnection() function creates a socket link to the specified host on port 80. Once the socket connection has been established the program will "send" the HTTP header that specifies the CGI to be invoked along with any parameters (in this case startorder=1962 for the starting order to download), the Host and the Authorization which is needed because the CGI is in a oAuth protected web server directory.

ShopSite Help and Resource Center Last updated: March 01, 2010 Give Feedback

ShopSite Shopping Cart Software