Payment (and other module) Documentation

[zizzor.com]

I have looked all over the oscommerce site and I have started scouring this site as well.

I need to write a custom payment module. I have encountered MANY other people saying "Can somebody point me to some documentation" regarding this subject. Nobody ever even responds.

If there is a specification for this and other modules, I should be able to find it. Why would they be called MODULES if there is no specification for user designed ones?

Yes, I know, I can spend hours digging around in other people's code. I can try to hack though all of the crap that is all just a hack of one module. There is little rhyme or reason to some of the payment modules because they just hacked somebody else's code. I don't want to hack code until it works, I want some documentation.

[jpf]

There is no OSC documentation anywhere on how to create a module....that is cause each module could be totally diffenet. Each shipping method or PAYMENT gateway requires differnet things and processes it differnet ways. The only way it to take a simple existing module then using PHP PROGRAMING to create your interface.

It is like your asking: "I want to create a custom application for Windows/Lunix/OSX/Java(or other platform) that does (insert your discription of new application here) - where is there a step-by-step guide to do exactly what I want?" there is not such thing - FOR ANY PROGRAMING LANGUAGE. Sure there is books that show you how to make a certain (small) application - but I would guest that is not the application you acually want to make.

Every type of module in OSC has a SAMPLE that shows the basic API (if you could call it that) that gets and send the required data TO AND FROM OSC. It does not go over the number of differnet ways it can connect to and talk to OTHER software/gateways/websites etc... (as that would require ESP and/or combing the internet on everthing on php/.net/java/C#/CSS/html etc...). You would have to look at the payment gateway's API or what ever they provide and then MAKE/program your OWN interface/conversion in PHP to do what you want for OSC.

Assuming you have some basic programing skills - Suggested reading:

Web Database Applications with PHP & MySQL from O'Reilly & Associates

Other books:
Web Application Development with PHP 4.0 - Contains Official Zend API Documentation - New Riders Publishing
PHP 4 Developer's Guide - Osborne McGraw-Hill
PHP Cookbook - O'Reilly & Associates


If you have no programing background then I would suggest taking a 'INTRO TO PROGRAMING' (even if it is Basic, C+/C# or just therory) cource at your local night school/collage/academy or even online or one of the "For Dummies" series (like "Beginning Programming for Dummies", "PHP & MySQL for Dummies" or "PHP 5 for Dummies " - all from John Wiley & Sons) would be a good start.


I am not saying that PHP is hard to modify - just that if you want to do some heavy programing (say a new payment/shipping module) - you have to know some programming and learn how PHP AND HTML works. PHP is easy to make small modifications for the novice or begginer - However for advaced user the API is shown and can demotrated how it works - but the rest is up to you. This is NORMAL for ANY API (I have worked with Crystal Report's API, Accpac's API, Adagio's API - which at best give you a basic application and list the variable that can be passed). All the rest is up to the PROGRAMER and the language in use.

Even if you have a command discription(anything in the php language and MySQL commands) or variable list (which would be all variable in OSC and many thing stored in MySQL) handy for the API - it would still not help you program something.

If you have a specific question on how to use a coomand or what variable name is then I or others could help abit better.

Sorry that this is a bit long and maybe a bit off topic - just tired of people asking such a broad question and not knowing the scope of it. I hope this may help you and others that ask the same or simular questions.


Short version:

Question: How do I program in PHP and MySQL within OSC

Answer: Learn PHP and MySQL and follow the examples in OSC

There is nothing like the naked truth.

[zizzor.com]

Wow, what a long-winded informational, and completely useless (to me) reply.

I am a developer. I ABSOLUTELY did NOT ask for any help in writing code, I did not ask a stupid question like "How do I make my gateway thingy work?"

What I asked for was the OSCommerce module specification, (Because I know there is no API)

There has to be a module specification even if it is not documented because the modules are not stand alone code, they are intimately conneced to OSCommerce's shopping cart code.

Even a simple flowchart outlining at what stage which functions are called and what oscommerce expects to get back from them would be enough to start with.

Naked Truth be told, I have been asked to retract what I think of your post.

[michael_s]

Here is the phpxref for osCommerce: http://www.oscdox.com/crossx/nav.html?index.php.html

That should get you started. Take a look at some of the payment modules. Also look at the checkout process files. You will see the wide array of constuction methods used by the modules.

[zizzor.com]

Thank you for the pointer.

Sadly, I already read those class definitions. They provide even less information than examining the actual module code.

Yes, I am *****y, but I'm willing to do my share to make this stuff right. Criticism that leads to change is just as much of a contribution as code.

I will do my part, is there a development effort toward documentation I can join? Documenting these methods (with help from the authors) will give me all the information I'm looking for and contribute to all the other people asking the same questions I have.

[michael_s]

zizzor.com, the docs are an open Wiki. Click the oscdox guide link in the left column of this site.

If you want to add to it, all you have to do is make a new page and start typing. I welcome any documentation that you can add to the project.

[zizzor.com]

Alright...... now that we've established where the incomplete docs are and how I can contribute to them........

Who is willing to help me understand the way payment modules are tied to the OSC code so I don't have to keep reverse engineering the whole shopping cart?

Any voulenteers?

Any leads?

Should I start shoulder tapping contribution authors?

[EDD2225]

I have been looking into this.

Here are my newbie thoughts, please be constructive.

<?php
/*
  THIS IS EXAMPLE CODE ONLY!!!  
I have never programmed in PHP and this is 'best guess only' hack.

  $Id: EMOcorp.php,v 0.1beta 2004/03/25 19:57:15 hpdl Exp $

  osCommerce, Open Source E-Commerce Solutions
  http://www.oscommerce.com


  Released under the GNU General Public License

Goal is to take the following web form and convert it into a web payment modual for oscommerce.

<form action="https://www.emocorp.com/s/action/PaymentAction" method="post"> 
<input type="hidden" name="merchant_email" value="sales@MyWebAddress.com">
<input type="hidden" name="merchant_name" value="My Business Name"> 
<input type="hidden" name="amount" value="34.39">
<input type="hidden" name="reference" value="2 face decals Plus S & H">
<input type="hidden" name="return_url" value="http://www.MyWebAddress.com">
<input name="" type="image" src="https://www.emocorp.com/resources/ui/skins/default/images/pay_emo.gif">
</form>



We are modifying the paypal payment modual for our interface.

Here are some variables being used below.
MODULE_PAYMENT_PAYPAL_STATUS             		switch used to turn modual on and off.
MODULE_PAYMENT_PAYPAL_ID				email address used by paypal
MODULE_PAYMENT_PAYPAL_CURRENCY			currency you are paid in
MODULE_PAYMENT_PAYPAL_ZONE				Shipping zone variable
MODULE_PAYMENT_PAYPAL_ORDER_STATUS_ID		Sounds like a pending ID variable or final
MODULE_PAYMENT_PAYPAL_SORT_ORDER			Determins where in list this payment option sets.
The above variables are set into the database by the install function below.

I would suggest modifying the word PAYPAL in the above variable to some other Payment processors name.
For my purpose EMOCORP should work.


*/


// References to paypal need to be changed
// I could be wrong on the terminology but this seems to be setting up some structured variable.
// Reminds me of C language.
//Probably change 'paypal' to 'emocorp'
  class paypal {
    var $code, $title, $description, $enabled;


// class constructor
// This seems to be defining the variables in the structure.  
//Probably change 'paypal' to 'emocorp'
// again change PAYPAL to EMOCORP

    function paypal() {
      global $order;

      $this->code = 'paypal';
      $this->title = MODULE_PAYMENT_PAYPAL_TEXT_TITLE;
      $this->description = MODULE_PAYMENT_PAYPAL_TEXT_DESCRIPTION;
      $this->sort_order = MODULE_PAYMENT_PAYPAL_SORT_ORDER;
      $this->enabled = ((MODULE_PAYMENT_PAYPAL_STATUS == 'True') ? true : false);

      if ((int)MODULE_PAYMENT_PAYPAL_ORDER_STATUS_ID > 0) {
        $this->order_status = MODULE_PAYMENT_PAYPAL_ORDER_STATUS_ID;
      }


      if (is_object($order)) $this->update_status();

// This is the link that will need to be changed to...
// 'https://www.emocorp.com/s/action/PaymentAction' to process transaction.
      $this->form_action_url = 'https://secure.paypal.com/cgi-bin/webscr';
    }

// class methods
    function update_status() {
      global $order;

// again change PAYPAL to EMOCORP
      if ( ($this->enabled == true) && ((int)MODULE_PAYMENT_PAYPAL_ZONE > 0) ) {
        $check_flag = false;
        $check_query = tep_db_query("select zone_id from " . TABLE_ZONES_TO_GEO_ZONES . " where geo_zone_id = '" . MODULE_PAYMENT_PAYPAL_ZONE . "' and zone_country_id = '" . $order->billing['country']['id'] . "' order by zone_id");
        while ($check = tep_db_fetch_array($check_query)) {
          if ($check['zone_id'] < 1) {
            $check_flag = true;
            break;
          } elseif ($check['zone_id'] == $order->billing['zone_id']) {
            $check_flag = true;
            break;
          }
        }

        if ($check_flag == false) {
          $this->enabled = false;
        }
      }
    }

    function javascript_validation() {
      return false;
    }

    function selection() {
      return array('id' => $this->code,
                   'module' => $this->title);
    }

    function pre_confirmation_check() {
      return false;
    }

    function confirmation() {
      return false;
    }


// This is where the magic happens.  When customer clicks to submit payment, the will be redirected to payment companies web site.

    function process_button() {
      global $order, $currencies, $currency;

// this appears to be for compatibility of multiple currencies.
      if (MODULE_PAYMENT_PAYPAL_CURRENCY == 'Selected Currency') {
        $my_currency = $currency;
      } else {
        $my_currency = substr(MODULE_PAYMENT_PAYPAL_CURRENCY, 5);
      }
      if (!in_array($my_currency, array('CAD', 'EUR', 'GBP', 'JPY', 'USD'))) {
        $my_currency = 'USD';
      }


// these are the strings and variables to be passed to the payment website
      $process_button_string = tep_draw_hidden_field('cmd', '_xclick') .
                               tep_draw_hidden_field('business', MODULE_PAYMENT_PAYPAL_ID) .
                               tep_draw_hidden_field('item_name', STORE_NAME) .
                               tep_draw_hidden_field('amount', number_format(($order->info['total'] - $order->info['shipping_cost']) * $currencies->get_value($my_currency), $currencies->get_decimal_places($my_currency))) .
                               tep_draw_hidden_field('shipping', number_format($order->info['shipping_cost'] * $currencies->get_value($my_currency), $currencies->get_decimal_places($my_currency))) .
                               tep_draw_hidden_field('currency_code', $my_currency) .
                               tep_draw_hidden_field('return', tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL')) .
                               tep_draw_hidden_field('cancel_return', tep_href_link(FILENAME_CHECKOUT_PAYMENT, '', 'SSL'));

      return $process_button_string;
    }

/*
sample paypal html web form for comparison purpose
<form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="me@mybusiness.com">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="item_name" value="Teddy Bear">
<input type="hidden" name="amount" value="12.99">
<input type="image" src="http://www.paypal.com/en_US/i/btn/x-click-but01.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">

</form> 

Looking above we can see that 'input type="hidden" ' lines are converted into tep_draw_hidden_field commands().

The question is how does the script know where to send the tep_draw_hidden_field commands()to.  

The answer should be "https://www.paypal.com/cgi-bin/webscr".
This can be found up at the top defined in the line '$this->form_action_url' 


*/



// Theory is that this is used to process the payment before sending payment??
    function before_process() {
      return false;
    }

// Theory is that this is used to handle payment clean up details such as notifying shopping cart payment is confirmed(If possible).
    function after_process() {
      return false;
    }

// Probably to detect failed pament transaction of some sort.
    function output_error() {
      return false;
    }

    function check() {
      if (!isset($this->_check)) {
        $check_query = tep_db_query("select configuration_value from " . TABLE_CONFIGURATION . " where configuration_key = 'MODULE_PAYMENT_PAYPAL_STATUS'");
        $this->_check = tep_db_num_rows($check_query);
      }
      return $this->_check;
    }


// This is obviously setup configuration in the administration
    function install() {
// again change PAYPAL to EMOCORP
      tep_db_query("insert into " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) values ('Enable PayPal Module', 'MODULE_PAYMENT_PAYPAL_STATUS', 'True', 'Do you want to accept PayPal payments?', '6', '3', 'tep_cfg_select_option(array(\'True\', \'False\'), ', now())");
      tep_db_query("insert into " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, date_added) values ('E-Mail Address', 'MODULE_PAYMENT_PAYPAL_ID', 'you@yourbusiness.com', 'The e-mail address to use for the PayPal service', '6', '4', now())");
      tep_db_query("insert into " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) values ('Transaction Currency', 'MODULE_PAYMENT_PAYPAL_CURRENCY', 'Selected Currency', 'The currency to use for credit card transactions', '6', '6', 'tep_cfg_select_option(array(\'Selected Currency\',\'Only USD\',\'Only CAD\',\'Only EUR\',\'Only GBP\',\'Only JPY\'), ', now())");
      tep_db_query("insert into " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, date_added) values ('Sort order of display.', 'MODULE_PAYMENT_PAYPAL_SORT_ORDER', '0', 'Sort order of display. Lowest is displayed first.', '6', '0', now())");
      tep_db_query("insert into " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, use_function, set_function, date_added) values ('Payment Zone', 'MODULE_PAYMENT_PAYPAL_ZONE', '0', 'If a zone is selected, only enable this payment method for that zone.', '6', '2', 'tep_get_zone_class_title', 'tep_cfg_pull_down_zone_classes(', now())");
      tep_db_query("insert into " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, use_function, date_added) values ('Set Order Status', 'MODULE_PAYMENT_PAYPAL_ORDER_STATUS_ID', '0', 'Set the status of orders made with this payment module to this value', '6', '0', 'tep_cfg_pull_down_order_statuses(', 'tep_get_order_status_name', now())");
    }

// Obviously to remove this payment option once installed.
    function remove() {
      tep_db_query("delete from " . TABLE_CONFIGURATION . " where configuration_key in ('" . implode("', '", $this->keys()) . "')");
    }

// Unknown??  
    function keys() {
// again change PAYPAL to EMOCORP
      return array('MODULE_PAYMENT_PAYPAL_STATUS', 'MODULE_PAYMENT_PAYPAL_ID', 'MODULE_PAYMENT_PAYPAL_CURRENCY', 'MODULE_PAYMENT_PAYPAL_ZONE', 'MODULE_PAYMENT_PAYPAL_ORDER_STATUS_ID', 'MODULE_PAYMENT_PAYPAL_SORT_ORDER');
    }
  }
?>

[zizzor.com]

The function process_button() actually creates a completed web form ready for posting to $action_url and returns it to checkout_confirmation.php

So when you click "confirm order" the form data prepared in process_button() is then submitted to the $action_url

The biggest problem I am having is that my transaction server returns a text string that needs to be processed. My browser just stops at the action url displaying it's return string. Other payment modules seem to capure that data, and redirect to checkout_confirmation.php with it, but I haven't figured out how yet.

[zizzor.com]

Okay, I figured out (by looking at many modules process_button() ) that there is nothing mysterious here, the form post is passing a url to the transaction server that tells it where to send it's results to. ( checkout_process.php )

Time to dig into the transaction server specs.

Now my next question is what format do the return values to checkout_process.php need to be? Do I need to make an intermediate file for parsing that redirects to checkout_process.php when it's done?