The Interface
Quick Start Guide
Creating Pages
Opening and Editing Pages
Uploading and Managing Files
Menu Display System
Site Templates
Shopping Cart & eCommerce
Event Calendar
eNewsletter Module
Database Table Manager
Secure Users
Site Data Tables
Photo Album
Site Statistics
Blog Manager
Webmaster Menu
Custom Web Forms
Custom PHP Includes
Programming structure
Custom HTML and PHP within the Page Editor
Custom Shipping Include
Custom Gateway Included
Custom Invoice Include
Custom Template Include
Custom Detail Page Include
Resources for Help
Search Engine Optimization
Useful Web Resources
Default Style Sheet File
Built-In Javascript Functions
Frequently Asked Questions (FAQs)
Online Users Manual Search Manual for:  
Custom PHP Includes
Custom Gateway Included

Payment gateways are very complex and their operations will vary from vendor to vender. The Pro Edition already supports the Verisign™ Payflow Link™ gateway system. It also provides the ability to be integrated with any gateway system that you or your client choose to use.

REMEMBER: Building a custom gateway include does NOT mean your web site is secure. You will need to add a SSL Certificate to your web server.

Innovative Merchant Services (http://www.innovativegateway.com)

Innovative Merchant Services is a recommended gateway system for the Soholaunch Pro Edition program. In our opinion, for small to mid-size businesses, they truly offer the most for the money. In this example, we are going to create a Gateway Include that runs test transactions through the Innovative Merchant Services gateway system.

NOTE: The script included here is for instructional purposes only, some modification may be required in order to display and function as needed for your application. This customization also requires access to your web server via FTP or Telnet to finalize.

Once again, there is a specific set of session variables that we need to know before we start authoring our gateway script. Generally Speaking, gateway systems are interested in only one thing; how much to charge to the credit card. However, some require specific information regarding the client such as the name on the credit card and zip codes for address verification. With our Gateway example, we want to pass all of the billing information through our gateway so that Innovative Merchant Services will log this data for us to reference on their site in case of a customer dispute.

The personal billing information of our customer is available via registered session variables that correspond to the input fields filled out during the customer billing and shipping address form. As well, the system has registered the final “total sale” amount, tax charges (if any) and shipping charges.

It is also important to note that at the point this include is executed, an invoice number has been assigned to our customer. This invoice number is also the Primary Key field in our “invoice” database table and is how we reference this customer within the Pro Edition from this point forward. This is important because in some instances, your gateway script may temporarily leave your site for processing (like Payflow Link™) and we must make sure that the invoice number is returned to the system in some fashion.

This include will be executed from the pgm-payment_gateway.php module within the /shopping directory. This script receives the choice of payment from our customer at the “verify order” step of checkout process. This information is either check/money order or credit card. If we are utilizing our custom gateway script, the pgm-payment_gateway.php script will execute our include for its processing at that time. But first, it will insert our customer into the “cart_invoices” database table and assign this order an Invoice Number.

!IMPORTANT! Unlike previous examples, this include does not allow a form to post to itself. It is a one-time “display” include. We’ll cover this more in a moment.

So, what does our include need to do? It needs to stop and wait for input from our customer regarding his/her credit card information. Once submitted, invoke the gateway to verify the credit card and charge it. Then, if the transaction is accepted, send our customer to the “Final Invoice” step of the checkout process. In tandem, the script also needs to send our customer back to the credit card entry form if the transaction is declined. With this in mind, remember the form can NOT post back to itself so a little more creative approach is required.

Session Variables Available to the Include:

Variable Name
Value
Description
$BFIRSTNAME
Mike

Customer Bill To First Name

$BLASTNAME
Morrison Customer Bill To Last Name
$BCOMPANY
Soholaunch.com, Inc. Customer Bill To Company
$BADDRESS1
123 Mockingbird Lane
Customer Bill To Address (1)
$BADDRESS2
Apt 3c Customer Bill To Address (2)
$BCITY Atlanta Customer Bill To City
$BSTATE
GA - Georgia Customer Bill To State/Province
$BZIPCODE
90210 Customer Bill To Zip Code
$BCOUNTRY
USA Customer Bill To Country

Also available or customer shipping data using the same variables with an “S” prefix in place of the above displayed “B” prefix.

$ORDERTOTAL
59.62
Full total to charge customer
$ORDER_NUMBER
10245
System Assigned Invoice Number
$BEMAILADDRESS
tech@Soholaunch.com Customer Bill To Email Address

Now that we know our variable data, let’s build the first of two scripts we will use to complete our process:

<?PHP
###########################################################
### PROCESS STEP 1: Get customers credit card data from
### input form before processing. It is important to note
### that this is the first of TWO includes we must program
### to make this gateway work.
###########################################################

// ----------------------------------------------------------
// DISPLAY CHECKOUT ROUTINE IN HEADER STEPS FOR REFERENCE // BY CUSTOMER
// ----------------------------------------------------------

$THIS_DISPLAY .= "<TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0 WIDTH=100%
CLASS=text STYLE='border: 1px inset black;'>\n";
$THIS_DISPLAY .= "<TR>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 1:<BR>Customer Sign-in</B>\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 2:<BR>Billing & Shipping<BR>Information\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 3:<BR>Shipping Options\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 4:<BR>Verify Order<BR>Details\n";
$THIS_DISPLAY .= "</TD>\n";
$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=BLACK>\n";
$THIS_DISPLAY .= "<B>Step 5:<BR>Make Payment\n";
$THIS_DISPLAY .= "</TD>\n";
$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 6:<BR>Print Final<BR>Invoice\n";
$THIS_DISPLAY .= "</TD>\n";
$THIS_DISPLAY .= "</TR></TABLE><BR>\n";

// ----------------------------------------------------
// Now let’s present the Form for our customer to fill
// out his/her credit card information
// You will want to modify this example script to have
// the expiration month and year be selection boxes
// with values of two and four digit numbers respectively
//
// NOTICE WE ARE POSTING DATA TO A PROGRAM CALLED// “PGM-MYGATEWAY.PHP”. This is a PHP script that we
// will create outside of the tool and place in the
// “doc_root/shopping” directory of our website
// ----------------------------------------------------$THIS_DISPLAY .= “<FORM METHOD=POST ACTION=\”PGM-MYGATEWAY.PHP\”>\n”;

// The following hidden variables are required by the system

$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=\"customernumber\" VALUE=\"$customernumber\">\n";
$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=\“ORDER_TOTAL\“
VALUE=\“$ORDER_TOTAL\">\n";
$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=\“ORDER_NUMBER\“
VALUE=\“$ORDER_NUMBER\">\n";

$THIS_DISPLAY .= “Name on Credit Card: <INPUT TYPE=TEXT SIZE=30 NAME=“CC_NAME”>\n”;
$THIS_DISPLAY .= “<BR>”;

// You should modify this form for visual consistency in the “real-world”

$THIS_DISPLAY .= “Credit Card Type: <SELECT NAME=“CC_TYPE”>\n”;
$THIS_DISPLAY .= “ <OPTION VALUE=‘VISA’>Visa</OPTION>\n”;
$THIS_DISPLAY .= “ <OPTION VALUE=‘AMEX’>American Express</OPTION>\n”;
$THIS_DISPLAY .= “</SELECT>\n”;
$THIS_DISPLAY .= “<BR>”;
$THIS_DISPLAY .= “Credit Card Number: <INPUT TYPE=TEXT SIZE=30 NAME=“CC_NUM”>\n”;
$THIS_DISPLAY .= “<BR>”;
$THIS_DISPLAY .= “Expiration Month: <INPUT TYPE=TEXT SIZE=30 NAME=“CC_MONTH”>\n”;
$THIS_DISPLAY .= “<BR>”;
$THIS_DISPLAY .= “Expiration Year: <INPUT TYPE=TEXT SIZE=30 NAME=“CC_YEAR”>\n”;
$THIS_DISPLAY .= “<BR>”;$THIS_DISPLAY .= “<INPUT TYPE=SUBMIT VALUE=\”Complete Checkout\”></form>\n”;

?>

Ok, that concludes the actual include script that we will set for our “Gateway Include” within the shopping cart. Because of security reasons, we can NOT re-post to the pgm-payment_gateway.php script. Therefore, we are going to write a “processing” script that handles our actual transaction processing routines. This script will be called “PGM-MYGATEWAY.PHP” in this example. You can name this script whatever you wish. Just remember to change the name in the form post in the previous code as well.

Now, let’s write our new script that does the cool processing part:

<?PHP
###########################################################
### Script Name: PGM-MYGATEWAY.PHP###
### Innovative Merchant Services Gateway Processing
### Interface
###########################################################

// Very important to have the next line included here. If we
// do not start our session, all session data will be LOST
// and that will kind of defeat the whole project

session_start();

// Insert the actual “processing” function for our system to execute.
// IMPORTANT – YOU MUST BE RUNNING “CURL” FOR THIS TO WORK. IN MOST// EVERY INSTALL OF PHP, CURL IS INCLUDED AND ITS FREE!

function GetGatewayResult($cardtype,$ccnum,$month,$year, $fulltotal,$ccname,$baddress1,$baddress2,$bcity,
$bstate,$bzip,$bcountry,$email) {

// The UPGI version we are currently using

$version = "1.1";

// URL for posting to Innovative Gateway Solutions
$Gateway_url = "https://transactions.innovativegateway.com/ servlet/com.gateway.aai.Aai";

// build the data string that contains the
// credit card info and customer data

$data = "target_app=WebCharge_v5.06&";
$data .= "response_mode=simple&";
$data .= "response_fmt=delimited&";$data .= "upg_auth=zxcvlkjh&";
$data .= "cardtype=$cardtype&";
$data .= "delimited_fmt_field_delimiter=~&";
$data .= "delimited_fmt_include_fields=true&";
$data .= "delimited_fmt_value_delimiter=|&";
$data .= "connection_method=POST&";
$data .= "delimited_response=Y&";

$data .= "notifyemail=no&";
$data .= "receiptemail=no&";
$data .= "include_extra_field_in_response=N&";

// Add vars for testing only, during actual process,
// you will need to insert your own UN/PW and re-comment
// out the "test_override_errors" line

$data .= "pw=GatewayTest&";
$data .= "username=Gateway2000&";

// Uncomment this line to test APPROVAL status
// $data .= "test_override_errors=X&";

// Continue normal variable settings

$data .= "trantype=sale&";
$data .= "ccnumber=$ccnum&";
$data .= "month=$month&";
$data .= "year=$year&";
$data .= "fulltotal=$fulltotal&";
$data .= "ccname=$ccname&";

$data .= "baddress=$baddress1&";
$data .= "baddress1=$baddress2&";

$data .= "bcity=$bcity&";
$data .= "bstate=$bstate&";
$data .= "bzip=$bzip&";
$data .= "bcountry=$bcountry&";
$data .= "email=$email";

$data = eregi_replace(" ", "+", $data);

// Setup data string to pass to CURL so that PHP doesn't
// have a heart-attack

$myTrans = "\"$data\" $Gateway_url";

// Execute Curl Command Now

exec("curl -d $myTrans", $return_string) || DIE ("Unable to Connect to Secure
Socket, Please user your back button and try again."); // split up the results into name=value pairs

$tmp = explode("|", $return_string[0]);
$tmpc = count($tmp);

for ($a=0;$a<=$tmpc;$a++) {
$thisvar = explode("~", $tmp[$a]);
${$thisvar[0]} = $thisvar[1];
}

$card_status[0] = "0";
$card_status[1] = "$error";
$card_status[2] = "";

if ($approval) {
$card_status[0] = "1";
$card_status[1] = "$approval";
$card_status[2] = "$anatransid";
}

return $card_status;

} // END FUNCTION

// ----------------------------------------------------------
// We should have received the credit card data from the
// gateway include script, so let’s combine that with
// the data from our session and pass the proper data
// to our “processing” function above.
// ----------------------------------------------------------

$CCTYPE = strtolower($CCTYPE);
$CC_NUM = ltrim($CC_NUM);
$CC_NUM = rtrim($CC_NUM);

$TRESULT = GetGatewayResult("$CC_TYPE","$CC_NUM","$CC_MONTH",
"$CC_YEAR","$ORDER_TOTAL","$CC_NAME","$BADDRESS1","$BADDRESS2", "$BCITY","$BSTATE","$BZIP","$BCOUNTRY","$BEMAILADDRESS");

// $TRESULT will return an array to us that is either approved or declined
// with an error result

If ($TRESULT[0] != “1”) {

// This transaction was declined! Display the reason
// to the customer and END processing now!

echo $TRESULT[1];
echo “<BR><BR>Please use your back button to re-enter your data.”;
exit; // IMPORTANT TO EXIT HERE NOW!

} // End if result NOT equal to 1

// If we have gotten this far in our script, then the transaction has
// been approved! NOW we must re-format our data slightly and pass it
// to the pgm-show_invoice.php program module.
// ---------------------------------------------------------------------

$TRANSACTION_ID = $TRESULT[2];

// Tell our invoice script that we are custom… let us in!

$Verisign_CONFIRM = 0;
$OFFLINE_FLAG = 0;

// Build String to send via HTTP header

$rstring = “TRANSACTION_ID=$TRANSACTION_ID&”;
$rstring .= “PAY_METHOD=MERCHANT_GATEWAY&”;
$rstring .= “ORDER_NUMBER=$ORDER_NUMBER&”;
$rstring .= “Verisign_CONFIRM=0&”;
$rstring .= “OFFLINE_FLAG=0”;

// Redirect end-user to final invoice display. If we
// have done our job right, this process is seamless// NOTE: Remember you Session Management, it is important
// to have the SID var at the end of your string here

header(“Location: pgm-show_invoice.php?$rstring&”.SID);
exit;

// Make sure there are absolutely NO extra carriage returns
// after the PHP close tag; else that will send a malformed
// header to the browser and cause the script to bomb!

?>

Save this script inside your /shopping directory (created by the system off of your document root directory). Within this directory you should see the “pgm-” files that have been mentioned in this section. Once in place, you are ready to start your testing.

For troubleshooting with these scripts, check the FAQ sections at http://www.innovativegateway.com