Question

How do I create an HTML form to allow the user to change their iTransact (itransact.com) subscription settings?

Eg: 1) Opt out of automatic subscription renewal:

• the form needs to change the ‘recur_reps’ value to 0

Eg: 2) Change their subscription type:

• the form needs to change the values of ‘recur_total’ and ‘recur_desc’

(ie: what is the URL to post the form to and what form fields do I need to post to it?)

Answer 1

According to an iTransact support technician there is no way to create an HTML form to allow the user to change their iTransact (itransact.com) subscription settings. However, there is an XML API that allows this to be done.

Since the code to send an XML request to iTransact’s XML API is not simple and intuitive, I decided to post a working sample program to Stack Overflow since it might be useful as a reference to others, especially since their is no example like it in the iTransact.com documentation.

The following sample program sends a request to get the details of an existing transaction.

<?php

define('ITRANSACT_API_UPDATE_URL', 'https://secure.itransact.com/cgi-bin/rc/xmltrans2.cgi');
define('ITRANSACT_API_GATEWAY', '12345'); // vendor account number
define('ITRANSACT_API_USERNAME', 'fdfsdfksafdsafdsafdsafdsafdsa'); // vendor API username
define('ITRANSACT_API_KEY', 'fdsfdsafdsafdsfdsfdsfds'); // vendor API key

/**
 * iTransact's XML API requires us to encrypt the XML command with a 
 * special key known only to us and iTransact. This is to ensure that the 
 * request cannot be modified after leaving our server. 
 *
 * A keyed hash value is generated using the HMAC-SHA1 algorithm and then 
 * encoded with base-64 MIME.
 *
 * @param string $strXMLCmd: xml for the command operation
 *
 * @returns string: the base64-encrypted HASH_SHA1 payload Signature 
 *                  for the command
 */
function getITransactPayloadSignagureForCommand($strXMLCmd){

  $key = ITRANSACT_API_KEY;

  #Using built in PHP5 functions:
  $digest = hash_hmac('sha1', $strXMLCmd, $key, true);
  $strPayLoadSignature = base64_encode($digest);

  #Using PEAR module:
  #require_once 'Crypt/HMAC.php';
  #$hmac = new Crypt_HMAC($key,"sha1");
  #$digest = pack("H40", $hmac->hash(trim($payload)));
  #$actual_signature = base64_encode($digest);

  return $strPayLoadSignature;
}

/** 
 * Constructs the XML request in the iTransact format for the request
 * including login credentials
 *
 * @param string $strXMLCmd: specific xml for the operation command
 */
function construct_itransact_xml($strXMLCmd){

  $strPayLoadSignature = getITransactPayloadSignagureForCommand($strXMLCmd);

  $strXML  = '<?xml version="1.0"?>';
  $strXML .= '<GatewayInterface>';

  // Login credentials:

  $strXML .=   '<APICredentials>';
  $strXML .=     '<Username>'.ITRANSACT_API_USERNAME.'</Username>';
  $strXML .=     '<PayloadSignature>'.$strPayLoadSignature.'</PayloadSignature>';
  $strXML .=     '<TargetGateway>'.ITRANSACT_API_GATEWAY.'</TargetGateway>';
  $strXML .=   '</APICredentials>';

  $strXML .=   $strXMLCmd; // Unique part of every command

  $strXML .= '</GatewayInterface>';

  return $strXML;
}

/**
 * Sends an XML request to iTransact.
 *
 * @param string $xml: the XML to send to iTransact
 *
 * @returns string: the XML responde from iTransact
 */
function post_xml_to_iTransact($xml) {

  $url = ITRANSACT_API_UPDATE_URL;

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HEADER, true);
  curl_setopt($ch, CURLINFO_HEADER_OUT, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, Array("Content-Type: text/xml; charset=utf-8"));
  curl_setopt($ch, CURLOPT_POST, 0);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

  $result = curl_exec($ch);
  $info = curl_getinfo($ch);

  curl_close($ch);

  return $result;
}

// *** MAIN ***

// construct XML command:

$strXID = '12345'; // transaction_id we wish to get details of
$strXMLCmd = '<RecurDetails><OperationXID>'.$strXID.'</OperationXID></RecurDetails>'; // command we wish to send
$strXML = construct_itransact_xml($strXMLCmd); 

// send XML command:

$strReturnedXML = post_xml_to_iTransact($strXML); // send request and fetch result
echo 'Response XML from iTransact: '.var_export(htmlspecialchars($strReturnedXML), TRUE);

?>

Note: Requests to update/cancel an existing recurring subscription would have a similar format but would use the “recurUpdate” command instead of the “recurDetails” command (for full details of all possible commands see: http://www.itransact.com/downloads/PCDeveloperGuide.pdf)