Once you have edited the specific item and are viewing the item tab in the item editor, click on the digital delivery tab.  Scroll down the page to the activation code section, select the "Retrieve real-time" option, and your see the "URL" & "Shared Secret" input fields.  There enter the absolute URL where your CGI is located along with the shared secret that you will use between the two systems.  The shared secret is a password, but we'll explain more about how that actually works further down.

Implementing your CGI

Merchants can choose to write their CGI program in whatever programming they are most comfortable with.  Some languages may be easier to use than orders for parsing and generating XML, but all modern web languages are capable of this.

During the finalize checkout process UltraCart will make a call for each item purchased to the merchant's web server.  UltraCart will post an XML document to the web server that contains important information about the order.  Here is an example request:

<activationCodeRequest> 
  <md5Secret>12F02381C6C6761690E966F2EC7E114E</md5Secret> 
  <merchantId>DEMO</merchantId> 
  <orderId>DEMO-0009000331</orderId> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <address1>12345 Somewhere Rd.</address1> 
  <address2 /> 
  <city>ATLANTA</city> 
  <state>GA</state> 
  <postalCode>30303</postalCode> 
  <country>United States</country> 
  <dayPhone>404-555-1212</dayPhone> 
  <eveningPhone /> 
  <email>johndoe@hotmail.com</email> 
  <itemId>SOFTWARE</itemId> 
  <quantity>1</quantity> 
  <options> 
    <option> 
      <name>existing serial number</name> 
      <value>12345</value> 
  </options> 
  <company>ThisElementOnlyPresentIfCompanyIsPopulated</company>
</activationCodeRequest> 

As we can see form the request it contains the order ID, billing information, item purchased, quantity purchased, and the options of the item.

The CGI program is then response for returning a result.  Below is a positive result:

<activationCodeResponse> 
  <code>Registration Code: ABC-12345</code> 
</activationCodeResponse> 

Note that the request contains the quantity of the item being purchased.  If they purchase 5 of the item then you should return a response like this:

<activationCodeResponse> 
  <code>Registration Code: ABC-1234
Registration Code: ABC-12346 
Registration Code: ABC-12347 
Registration Code: ABC-12348 
Registration Code: ABC-12349</code> 
</activationCodeResponse> 

Simply seperate each code in teh response by a new line character.  You can also issue any other type of text.  For instance some software registration schemes require a customer to enter two different codes.  You can return as many lines of text in the code element as you need within reason.

The CGI can also choose to return an error message.  UltraCart will not prohibit the order from going through, but will simply include the error message on the receipt.  For instance if the existing serial number in teh request was invalid you might want to return something like this:

<activationCodeResponse> 
  <error>Invalid existing serial number.  
Please contact support@mywidgets.com</error> 
</activationCodeResponse> 

Security

Since UltraCart does not require the CGI to be hosted on an HTTPS (SSL) server it was important to utilize an authentication scheme that would still be secure.  So UltraCart utilizes an MD5 hash of the shared secret plus the order ID.  This allows the merchant to write their CGI so that it calculates the hash and then compares what was provided to what was calculated.

So to calculate the hash the first thing to do is understand what data is being hashed.

<shared secret><order id in all caps><shared secret> 

So in the example request above we would calculate the hash of:

supersecretDEMO-0009000331supersecret

So the CGI can take the order ID provided in the request in the request and the known shared secret and calculate the md5Secret.  Then compare it to what was provided in the request.  It's important to note that the md5Secret contained in the xML is represented in hexadecimal format.  If the md5Secrets don't match then return an error XML packet.

If at all possible, host your CGI on an HTTPS (SSL) server.  There is absolutely no harm in adding an additional layer of security to the process.

We also recommend that you reject request that do not come from known UltraCart IP addresses.

 API Documentation in PDF