vb.org Archive - [How-To] Use a new currency on your custom payment gateway

vBulletin offers the ability to create new payment gateways but you have to use one of the hard coded currencies that are currently on the system. The available currencies are USD, GBP, EUR, CAD and AUD.

If you want to offer a new currency on your payment gateway you have two options:

1) Modify the source code to add new currencies (see includes/class_paid_subscriptions.php around line 182 and admin/subscriptions.php for that task)
or
2) Follow this guide.

This guide is not an optimal solution to this problem but it can serve as a work around for most of the users that doesn't want to make file edits.

Prerequisite

vBulletin 4.x (i think this might work for vB3.x but I'm not sure)
You need to create a new payment gateway. This task is out of the scope of this tutorial but here is a great guide to accomplish it: [How-To] Extending the vBulletin Payment Gateway.
Some vBulletin experience. Programming experience is a plus.

=================================================
=================================================

Step 1 - Choose one currency that you don't need:

What we will do is to replace one of the supported currencies with the one you need for your payment gateway. Choose one that you don't need on your site. In this tutorial I am going to choose Pound Sterling (GBP) and I am going to replace it with Colombian Pesos (COP). Remember that these values are my own. Yours can be completely different and you need to type your own values throughout this guide.

=================================================
=================================================

Step 2 - Edit phrases that make reference to the currency you want to replace
Use the phrase manager to change the name of the currency you chose to replace and type the name of the new currency. In my case I should search for Pounds Sterling. The other currencies are U.S. Dollars, Euros, Australian Dollars and Canadian Dollars. You should find a phrase whose variable, in my case, is pounds_sterling. Edit that phrase and translate it to the name of the currency you want to add. In my case it would be Colombian Pesos.

Go to Admin > Language & Phrases > Search in Phrases > Search for text: Pounds Sterling
Edit the phrase under the Subscription Tools Phrases section that contains the name of the currency you chose
Translate it to the name of the new currency you want to add.

=================================================
=================================================

Step 3 - Add two plugins
vBulletin make use of currency symbols when it needs to display the cost of the subscriptions.

The following is the list of symbols for each one of the supported currencies in vBulletin:

US Dollars => US$
Pounds Sterling => £
Euros => €
Canadian Dollars => CA$
Australian Dollars => AU$

This is used wherever the system needs to display money representations. When you are paying for a subscription in US Dollars, the cost of the subscription will appear like US$10. If you're paying in Euros, it would appear like €10 and so on. We need to replace those symbols to the symbol of our new currency. In my case, I need to search for £ and replace it to COP$. To do this we need to create two plugins. Remeber to modify those plugins with the currency symbols that you're using.

hook: paidsub_order_start
PHP:

PHP Code:


		
			
$subscription_cost = str_replace('&pound;', 'COP$', $subscription_cost);

hook: paidsub_list_availablebit
PHP:

PHP Code:


		
			
$subscription['cost'] = str_replace('&pound;', 'COP$', $subscription['cost']);

=================================================
=================================================

Step 4 - Modify the options of your payment gateway

Go to Paid Subscriptions > Payment API Manager and edit your new payment gateway.

Make sure that the currency you decided to replace (in my case it was GBP) is listed on the 'Supported currency' textbox.

=================================================
=================================================

Step 5 - Modify the form to be submitted. (optional)
If you created your payment gateway using the guide I provided to you, in step 2 of that guide, the author instructed you to create a new template that contains the form that is submitted to your new payment processor. This form usually includes the order number, product name, price and other vital information required by your payment processor. This step is necessary if your processor requires that you include the currency in this form. If this is the case, you can't use the $currency variable provided by vBulletin because it will include the original currency symbol. If your new payment gateway supports only one currency, you can simply hard code the new currency symbol on this template. On the other hand, if your new payment gateway supports several currencies (in my case, my gateway supports USD and COP) you need to cope with this requirement. I use this conditional in order to fix this:

HTML Code:

<input name="moneda" type="hidden" value="<vb:if condition="$currency == 'USD'">USD<vb:else />COP</vb:if>">

This will include the code USD when the user selects USD in the paid subscription page. If the user chooses any other currency, the template will simply include COP. You need to modify this conditional if you support more than two currencies.

=================================================
=================================================

Step 6 - Other considerations (optional)
We are almost over. Please take a minute to review the code of the class of your new payment gateway and identify if your gateway needs the currency of the transaction to generate any secret key or other similar methods. In my case, my processor requires a special MD5 hash to validate the communication between servers. This hash is created out of several values, including the currency of the transaction. If this is your case, you need to modify that piece of code to include (again, in my case) USD, or COP instead of GBP.

PHP Code:


		
			
/** This piece of code is merely an example. You need to decide if your payment gateway requires something like this to be included. **/

$currency = $currency == 'USD' ? 'USD' : 'COP'; //if you look closely, this piece of code is very similar to the conditional on the template above.

$secret_key = make_key($item, $cost, $currency);

=================================================
=================================================

Final thoughts
I hate PHP sometimes because it allows me to do this kind of stuff. This is a nasty hack that can save you from a couple of file edits but it still feels bad when you need to do this kind of stuff. vBulletin should make an interface that allows us to add more currencies. If they don't see this suitable, at least they should include hooks in proper places that allows us to create those new currencies using plugins. It is a very simple thing to do that would save us from hacks like this.

I hope this guide helps someone out. While I was researching trying to figure out how to add currencies, I found a lot of people with the same problem than me and thus I decided to create this guide.

This is an alpha guide. I haven't tested it deeply and a lot of errors might appear. This was created with vB4.2 in mind but it might work in previous versions. If I find things that needs to be fixed, I will be updating this guide accordingly.

Note to the moderator: Please feel free to fix any grammatical error I could've made on this guide. English is not my primary language and thus I often make many mistakes when trying to communicate in english.

X vBulletin 3.8.12 by vBS Debug Information
Page Generation 0.01306 seconds Memory Usage 1,785KB Queries Executed 10 (?)
More Information
Template Usage: (1)ad_footer_end (1)ad_footer_start (1)ad_header_end (1)ad_header_logo (1)ad_navbar_below (1)bbcode_html_printable (3)bbcode_php_printable (5)bbcode_quote_printable (1)footer (1)gobutton (1)header (1)headinclude (6)option (1)post_thanks_navbar_search (1)printthread (12)printthreadbit (1)spacer_close (1)spacer_open Phrase Groups Available: global postbit showthread	Included Files: ./printthread.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/class_bbcode_alt.php ./includes/class_bbcode.php ./includes/functions_bigthree.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 printthread_start bbcode_fetch_tags bbcode_create bbcode_parse_start bbcode_parse_complete_precache bbcode_parse_complete printthread_post printthread_complete
Messages: