pgStormPay - Adds StormPay to the payment gateway.
Mod Version: 1.0.0, by hambil
This thread is in the Modification Graveyard.
| vB Version: 3.6.0 | Rating:  (0 vote - 0 average) |
Installs: 5 |
| Released: 31 Aug 2006 | Last Update: Never | Downloads: 31 |
 Not Supported
 Uses Plugins
Template Edits
Additional Files
|
||
Keywords: payment gateway, stormpay, payment api
Description:
Adds http://www.stormpay.com/ to the vBulletin payment gateway.
Features:
, detailing what I learned writing this hack.
Description:
Adds http://www.stormpay.com/ to the vBulletin payment gateway.
Features:
- Fully Phrased.
- Fully Integrated.
- Test mode.
- Supports MD5 encryption.
- Download the pgStormPay_1.0.0.zip file.
- Unzip and upload the files in the upload directory to your forum root.
- Import the product file in your admincp.
- Enable and setup StormPay in Paid Subscriptions section of your admincp.
Spoiler (click to open)
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.
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 its 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:
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.
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.
Step 2: The template
Next youll 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.
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:
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:
The plugins section of your product xml would look like this:
Step 4: The phrases
The phrases section of your product xml would look like this:
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 youll 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:
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 dont 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:
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.
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:
Thats all!
Thats it folks! Check out the pgStormPay hack if you still need more details.
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
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 its 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'];
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);
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();
Next youll 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">
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>
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' );
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>
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.
HTML Code:
<phrases> <phrasetype name="GLOBAL" fieldname="global"> </phrasetype> <phrasetype name="Error Messages" fieldname="error"> </phrasetype> </phrases>
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 youll 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;
}
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']));
}
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;
}
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;
Thats it folks! Check out the pgStormPay hack if you still need more details.
Close
Download
This modification cannot be downloaded.
Screenshots