Go Back   vb.org Archive > vBulletin Article Depository > Read An Article > vBulletin 3 Articles
Reload this Page [How-To] Extending the vBulletin Payment Gateway
FAQ Community Calendar Today's Posts Search

Reply
Page 2 of 3 1 2 3
 
Thread Tools
[How-To] Extending the vBulletin Payment Gateway
hambil's Avatar
hambil
Join Date: Jun 2004
Posts: 1,719

 

Seattle
Show Printable Version Email this Page Subscription
hambil hambil is offline 08-30-2006, 10:00 PM
Overview

This tutorial shows you how to add a new payment method to the vBulletin Payment Gateway. It uses my pgStormPay hack as the example.

Step 1: The database

The first thing you need to understand is the paymentapi table in the database.

Code:
Field          Type
-----          ----
Title          varchar(250)
Currency       varchar(250)
Recurring      smallint(6)
Classname      varchar(250)
Active         smallint(6)
Settings       Mediumtext
Title
The title of the payment method, in our case ?StormPay?.

Currency
Comma delimited list of currency types this payment method can accept. StormPay only accepts us dollars, so in our case it?s just ?usd?.

Recurring
Whether or not this payment method can handle recurring payments (monthly, yearly, etc?).

Classname
The name of the class in yourforum/includes/paymentapi that contains the functions needed to use this payment method. This field name is a little deceptive, because it you look in yourforum/payment_gateway.php you see the following:

PHP Code:
require_once(DIR . '/includes/paymentapi/class_' . $api['classname'] . '.php');
$api_class = 'vB_PaidSubscriptionMethod_' . $api['classname']; 
So what this field really represents is the unique part of the filename and the classname. class_classname.php and vB_PaidSubscriptionMethod_classname. Or in our case: class_stormpay.php and vB_PaidSubscriptionMethod_stormpay. So you can see the value of this field for us should be just ?stormpay?.

Active
Is this payment method active? In general you should set this to 0 initially and let the admin activate your payment method from the admincp.

Settings
This is a critical part of the payment method, and needs some explaining. It represents the information the admin must fill in for this payment method to work. It will be different for each payment method. It is an array of arrays, with each inner array representing a field to be filled out. The structure of the inner array is similar to a html input element. It has a type, a value, and how to validate the value. For StormPay, we create four fields, as shown bellow.

PHP Code:
$email = array("type" => "text", "value" => "", "validate" => "string");
$secret_code = array("type" => "text", "value" => "", "validate" => "string");
$md5 = array("type" => "yesno", "value" => "0", "validate" => "yesno");
$test_mode = array("type" => "yesno", "value" => "0", "validate" => "yesno");
$settings = array("secret_code" => $secret_code, "MD5" => $md5, "test_mode" => $test_mode, "email" => $email); 
Putting it into the database
Once you know the values you want for your payment method, you can write them into the database in your install section of your product xml file.

PHP Code:
// add the storm pay record to the paymentapi table
$db->hide_errors();
$db->query_write("
            INSERT INTO " . TABLE_PREFIX . "paymentapi
            (title, currency, recurring, classname, active, settings)
            VALUES
            ('StormPay', 'usd', 1, 'stormpay', 0, '" . $db->escape_string(serialize($settings)) . ')
");
$db->show_errors(); 
Step 2: The template

Next you?ll need to create a template for your payment form. This is the form that is filled out automatically by vBulletin before it submits data to your payment method. In the case of StormPay, we are going to use a simple single item payment, as specified in their integration api: http://www.stormpay.com/stormpay/user/manual.php

Note: I use unit_price instead of amount. It works the same, and seems to clear up some minor bugs.

HTML Code:
<input type="hidden" name="test_mode" value="$settings[test_mode]">
<input type="hidden" name="payee_email" value="$settings[email]">
<input type="hidden" name="product_name" value="$subinfo[title] Subscription">
<input type="hidden" name="description" value="$subinfo[description]">
<input type="hidden" name="unit_price" value="$cost">
<input type="hidden" name="user1" value="$hash">
<input type="hidden" name="require_IPN" value="1">
<input type="hidden" name="return_URL" value="$vboptions[bburl]/payment_gateway.php?method=stormpay">
In the case of StormPay we are telling it we require IPN (Immediate Payment Notification). StormPay will post back to the ?return_URL?, which we set to the payment_gateway.php file and tell it the method is stormpay. No code changes need to be made to the payment_gateway.php as it just uses the method to create an instance of the class we will look at later in this tutorial. Notice we are using some of the settings we created when we added our payment method to the database.

To create this template, vBulletin expects it to have the name subscription_payment_classname. So in our case the template section of the product xml would look like this:

HTML Code:
<templates>
<template name="subscription_payment_stormpay" templatetype="template" date="0" username="Hambil" version="3.6.0">
<![CDATA[?]]>
</template>
</templates>
Step 3: The plugin
This is not the only way to accomplish this step, but it is the way I have chosen. You need to add the StormPay phrase to the vbphrases array, so it can appear on the ?Order Using? button. Since these are service names, and not translated, vBulletin hard codes them in yourforum/payment.php. However, it does provide a hook (paidsub_order_start).

The hook code we need is very simple:

PHP Code:
$vbphrase += array( 'stormpay' => 'StormPay' ); 
The plugins section of your product xml would look like this:

HTML Code:
<plugins>
<plugin active="1" executionorder="5">
<title><![CDATA[StormPay - add 'order using']]></title>
<hookname>paidsub_order_start</hookname>
<phpcode><![CDATA[?]]></phpcode>
</plugin>
</plugins>
Step 4: The phrases

Code:
Global
setting_stormpay_email_desc        This is the email address you want to receive payment (the pay to email address).
setting_stormpay_email_title       Email
setting_stormpay_secret_code_desc  This must be the EXACT secret code value you set in your "Profile" > "IPN Configuration" form in StormPay.
setting_stormpay_secret_code_title Secrect Code
setting_stormpay_test_mode_desc     Enable Test Mode. Transactions in test mode are 'fake' and not charged to an account.
setting_stormpay_test_mode_title   Test Mode
setting_stormpay_MD5_desc          If you enable MD5 encryption you MUST set the list of IPN variables for Hashing in the "IPN Configuration" form of your StormPay Merchant Account to transaction_id; transaction_date; amount; user_id; user1.
setting_stormpay_MD5_title         Use MD5 Encryption
stormpay_order_instructions        To pay for your subscription via StormPay click the button below and follow the onscreen instructions.

Error Messages
stormpay_pending    Your subscription is Pending. Please check the StormPay website.
stormpay_cancel     Your subscription was canceled.
stormpay_error      An error was encountered processing your subscription. You have not been charged.
The phrases section of your product xml would look like this:

HTML Code:
<phrases>
<phrasetype name="GLOBAL" fieldname="global">?</phrasetype>
<phrasetype name="Error Messages" fieldname="error">?</phrasetype>
</phrases>
Step 5: The payment method class

This is the final part, and the real meat of the payment method. It ties everything else together. It extends the vBulletin class vB_PaidSubscriptionMethod, and the easiest thing is probably to copy one of the existing classes and modify it.

It has three functions you need to deal with:

verify_payment() function
This function will depend on what the payment method you are using sends back to the payment_gateway.php file. In general you?ll want to get the variables from the submitted request, check them for successful payment, and return true or false to the payment_gateway.php file. Here is a look at the verify_payment() function for StormPay:

PHP Code:
function verify_payment()
{            
              $this->registry->input->clean_array_gpc('r', array(
                          'secret_code'                => TYPE_STR,
                          'product_name'             => TYPE_STR,
                          'status'                          => TYPE_STR,
                          'unit_price'                    => TYPE_STR,
                          'transaction_id'  => TYPE_NUM,
                          'transaction_date'          => TYPE_STR,
                          'user_id'                                    => TYPE_STR,
                          'user1'                                      => TYPE_STR
              ));
   
              $this->secret_code = $this->registry->GPC['secret_code'];
              $this->product_name = $this->registry->GPC['product_name'];
              $this->status = $this->registry->GPC['status'];
              $this->unit_price = $this->registry->GPC['unit_price'];
              $this->transaction_id = $this->registry->GPC['transaction_id'];
              $this->transaction_date = $this->registry->GPC['transaction_date'];
              $this->user_id = $this->registry->GPC['user_id'];
              $this->user1 = $this->registry->GPC['user1'];
                          
              // Check MD5 hash
              if ($this->settings['MD5'] AND $this->status != 'TEST')
              {
                          $calc_hash_value = MD5($this->transaction_id.":".$this->transaction_date.":".MD5($this->settings['secret_code']). ":".$this->amount.":".$this->user_id.":".$this->user1);
                          $sent_hash_value = rawurldecode($this->secret_code);
              }
   
              if (!$this->settings['Md5'] OR $this->status == 'TEST' OR $calc_hash_value === $sent_hash_value)
              {
                          $this->paymentinfo = $this->registry->db->query_first("
                                      SELECT paymentinfo.*, user.username
                                      FROM " . TABLE_PREFIX . "paymentinfo AS paymentinfo
                                      INNER JOIN " . TABLE_PREFIX . "user AS user USING (userid)
                                      WHERE hash = '" . $this->registry->db->escape_string($this->registry->GPC['user1']) . "'
                          ");
                          // lets check the values
                          if (!empty($this->paymentinfo))
                          {
                                      $sub = $this->registry->db->query_first("SELECT * FROM " . TABLE_PREFIX . "subscription WHERE subscriptionid = " . $this->paymentinfo['subscriptionid']);
                                      $cost = unserialize($sub['cost']);
                                      $this->paymentinfo['currency'] = 'usd';
                                      $this->paymentinfo['amount'] = floatval($this->unit_price);
                                      if ($this->status == 'SUCCESS' OR $this->status == 'COMPLETE' OR $this->status == 'TEST')
                                      {
                                                  $this->type = 1;
                                                  return true;
                                      }
                                      else
                                      {
                                                  if ($this->status == 'PENDING')
                                                              $this->error = fetch_error('stormpay_pending');
                                                  else if ($this->status == 'CANCEL')
                                                              $this->error = fetch_error('stormpay_cancel');
                                                  else
                                                              $this->error = fetch_error('stormpay_error');
                                      }                                  
                          }
              }
              return false;
} 
Note: $this->type defaults to 0, and if the payment is successful you must set it to 1, as well as returning true. A type of 2 is a delete, and handled by vBulletin so you don?t need to worry about it.

test() function
This function is used by the Test Communications link under the Paid Subscriptions menu in the admincp. In general it is just a validation of the specific data (settings) needed by the payment method. In our case, we need a valid email and a ?secret code?. So, or method looks like this:

PHP Code:
function test()
{
  return (!empty($this->settings['secret_code']) AND !empty($this->settings['email']));
} 
generate_form_html() function
This function generates the form that is sent to your payment method, using the template you created earlier. Several variables get passed into the method, and you can also retrieve any values you put into settings. Here is a look at the StormPay function.

PHP Code:
function generate_form_html($hash, $cost, $currency, $subinfo, $userinfo, $timeinfo)
{                      
              $form['action'] = 'https://www.stormpay.com/stormpay/handle_gen.php';
              $form['method'] = 'post';
                          
              // load settings into array so the template system can access them
              $settings =& $this->settings;
   
              $settings['email'] = htmlspecialchars_uni($settings['email']);
              $settings['product_name'] = htmlspecialchars_uni($this->registry->subinfo['title']);
                          
              eval('$form[\'hiddenfields\'] .= "' . fetch_template('subscription_payment_stormpay') . '";');
              return $form;
} 
Feedback
One final thing to be aware of is that in order to display feedback from your payment method payment_gateway.php requires the value ?display_feedback? be set to true. It defaults to false in the vBulletin class you extend. So, you must force it true:

PHP Code:
var $display_feedback = true; 
That?s all!
That?s it folks! Check out the pgStormPay hack if you still need more details.
Reply With Quote
  #12  
Old 03-19-2007, 07:03 AM
rungss rungss is offline
 
Join Date: Jan 2007
Posts: 7
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Quote:
Originally Posted by hambil View Post
it's the same for all hacks
of course, of course..
I was just pointing it out in general.
This thread is not just about this Hack.

It's about learning how to develop a new plugin isn't it.

Thanks a lot for this thread.

I was able to develop my first vB plugin as per the specification because of this thread.
Reply With Quote
  #13  
Old 04-22-2007, 07:36 PM
Champster Champster is offline
 
Join Date: Mar 2006
Posts: 17
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Can this be used to modify an existing payment apt, ccbill specifically?

I need to modify vb CCBill Form Character Code where the form accepts more than just one form code.
Reply With Quote
  #14  
Old 02-20-2008, 08:32 PM
nanaimobar nanaimobar is offline
 
Join Date: Nov 2005
Location: Canada
Posts: 103
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Does your tutorial work for 3.6.7?

Whoops!! I mean 3.7
Reply With Quote
  #15  
Old 06-22-2008, 08:08 PM
Mum Mum is offline
 
Join Date: Jun 2006
Location: New Zealand
Posts: 660
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
I am trying to write a payment api at the moment, and was querying 'Settings
This is a critical part of the payment method, and needs some explaining. It represents the information the admin must fill in for this payment method to work. It will be different for each payment method. It is an array of arrays, with each inner array representing a field to be filled out. The structure of the inner array is similar to a html input element. It has a type, a value, and how to validate the value. For StormPay, we create four fields, as shown bellow.'

how can i work out what my processor (paymex) requires?

--------------- Added [DATE]1214174919[/DATE] at [TIME]1214174919[/TIME] ---------------

I foudn these, but not sure which relates to what http://www.paymex.co.nz/kb.aspx?id=34 hoping that someone can help me, i can pay a small amount.
Reply With Quote
  #16  
Old 11-03-2008, 05:48 AM
imedic's Avatar
imedic imedic is offline
 
Join Date: Mar 2008
Location: Romania
Posts: 178
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
I am looking for a modification of payment api that permit manual payment approved by admin. User pays in various ways, send me confirmation of payment and I validate manually his subscription.

I have a small professional community so total number cannot go above 10k users and some of them are not familiar with electronic payment. They will send money by post, direct payment in bank account (or even pay me cash when we meet ) and I want to take advantage of the subscription system build in VB (reminders for end of subscription, period subscripted) so I don't need to make a separate group and write down each username , and period of subscription.

My alternative for the moment is to make a group user request to join and I approve after receiving the confirmation of payment. This way I need to keep manual track of each user time of subscription ending and name.

I have no coding knowledge but willing to learn or appreciate a helping hand.
Maybe I am lucky and there is a setting I don't know in vb allowing me to do this !

PS I will like to have this additional to electronic payment (for users able to pay this way)
after I manage to integrate my local card processor using this tutorial I am thankful for

Edit:
Found by accident a possible solution. In Subscription management make a valid payed subscription (even if no bank set) and manually add users from drop down menu in Subscription manager page from Admin CP. Hope is useful for some.
Reply With Quote
  #17  
Old 06-29-2011, 12:53 AM
Manoel J?nior Manoel J?nior is offline
 
Join Date: Feb 2009
Location: SP / Brasil
Posts: 778
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Does anyone know if this tutorial works for version 3.8.7?
Reply With Quote
  #18  
Old 07-01-2011, 12:17 PM
Manoel J?nior Manoel J?nior is offline
 
Join Date: Feb 2009
Location: SP / Brasil
Posts: 778
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Anyone?
Reply With Quote
  #19  
Old 07-02-2011, 10:40 AM
DivisionByZero's Avatar
DivisionByZero DivisionByZero is offline
 
Join Date: Dec 2002
Location: South Bend, Indiana
Posts: 485
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Absolutely!
Reply With Quote
  #20  
Old 07-02-2011, 10:46 AM
MentaL's Avatar
MentaL MentaL is offline
 
Join Date: Jan 2003
Posts: 550
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
IF anyone gets 2checkout working with vbulletin I'll pay yoU!
Reply With Quote
  #21  
Old 07-03-2011, 12:22 PM
DivisionByZero's Avatar
DivisionByZero DivisionByZero is offline
 
Join Date: Dec 2002
Location: South Bend, Indiana
Posts: 485
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
I haven't looked in a very long time, but isn't 2CO already built in?
Reply With Quote
Reply
Page 2 of 3 1 2 3

« Previous Thread | Next Thread »

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts
BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Forum Jump


All times are GMT. The time now is 08:33 AM.

Contact Us - Archive - Top

Powered by vBulletin® Version 3.8.12 by vBS
Copyright ©2000 - 2024, vBulletin Solutions Inc.
X vBulletin 3.8.12 by vBS Debug Information
  • Page Generation 0.04876 seconds
  • Memory Usage 2,432KB
  • Queries Executed 26 (?)
More Information
Template Usage:
  • (1)SHOWTHREAD
  • (1)ad_footer_end
  • (1)ad_footer_start
  • (1)ad_header_end
  • (1)ad_header_logo
  • (1)ad_navbar_below
  • (1)ad_showthread_beforeqr
  • (2)bbcode_code
  • (4)bbcode_html
  • (8)bbcode_php
  • (1)bbcode_quote
  • (1)footer
  • (1)forumjump
  • (1)forumrules
  • (1)gobutton
  • (1)header
  • (1)headinclude
  • (1)modsystem_article
  • (1)navbar
  • (4)navbar_link
  • (120)option
  • (1)pagenav
  • (1)pagenav_curpage
  • (2)pagenav_pagelink
  • (11)post_thanks_box
  • (2)post_thanks_box_bit
  • (11)post_thanks_button
  • (1)post_thanks_javascript
  • (1)post_thanks_navbar_search
  • (1)post_thanks_postbit
  • (11)post_thanks_postbit_info
  • (10)postbit
  • (11)postbit_onlinestatus
  • (11)postbit_wrapper
  • (1)spacer_close
  • (1)spacer_open
  • (1)tagbit_wrapper 
Phrase Groups Available:
  • global
  • inlinemod
  • postbit
  • posting
  • reputationlevel
  • showthread
Included Files:
  • ./showthread.php
  • ./global.php
  • ./includes/init.php
  • ./includes/class_core.php
  • ./includes/config.php
  • ./includes/functions.php
  • ./includes/class_hook.php
  • ./includes/modsystem_functions.php
  • ./includes/functions_bigthree.php
  • ./includes/class_postbit.php
  • ./includes/class_bbcode.php
  • ./includes/functions_reputation.php
  • ./includes/functions_post_thanks.php 
Hooks Called:
  • init_startup
  • init_startup_session_setup_start
  • init_startup_session_setup_complete
  • cache_permissions
  • fetch_threadinfo_query
  • fetch_threadinfo
  • fetch_foruminfo
  • style_fetch
  • cache_templates
  • global_start
  • parse_templates
  • global_setup_complete
  • showthread_start
  • showthread_getinfo
  • forumjump
  • showthread_post_start
  • showthread_query_postids
  • showthread_query
  • bbcode_fetch_tags
  • bbcode_create
  • showthread_postbit_create
  • postbit_factory
  • postbit_display_start
  • post_thanks_function_post_thanks_off_start
  • post_thanks_function_post_thanks_off_end
  • post_thanks_function_fetch_thanks_start
  • fetch_musername
  • post_thanks_function_fetch_thanks_end
  • post_thanks_function_thanked_already_start
  • post_thanks_function_thanked_already_end
  • post_thanks_function_fetch_thanks_bit_start
  • post_thanks_function_show_thanks_date_start
  • post_thanks_function_show_thanks_date_end
  • post_thanks_function_fetch_thanks_bit_end
  • post_thanks_function_fetch_post_thanks_template_start
  • post_thanks_function_fetch_post_thanks_template_end
  • postbit_imicons
  • bbcode_parse_start
  • bbcode_parse_complete_precache
  • bbcode_parse_complete
  • postbit_display_complete
  • post_thanks_function_can_thank_this_post_start
  • pagenav_page
  • pagenav_complete
  • tag_fetchbit_complete
  • forumrules
  • navbits
  • navbits_complete
  • showthread_complete