[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:
hook: paidsub_list_availablebit
PHP:
=================================================
=================================================

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:

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.

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

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.

so much sophisticated
yet wonderful work !

Thank you.

Great effort distinct
Thank you JulianD :)

Hi and SOS!
I'm trying to solve the problem of adding new currency in my forum (Vb 4.2.1)
I made 3 steps but on the forth step a new currency didn't appear in the Supported currency.
And then I can't find a place where to make changes in steps 5 and 6 :(
I have not much experience in vb so my questions may seem silly - sorry for that :S

Hello, this solution doesn't add a new currency but instead, it takes an unused currency and rename it to our desired currency.

You should choose a currency that you're not currently using (in my case it was the GBP currency) and follow the guide to rename it to a new currency (again, in my case I wanted to rename it to COP).

The advantage of this guide is that no file needs to be hard coded.

there is a possibility to put the Brazilian currency? (Brazilian Real = BRL)

I thank the help

:up:Solved added a subscription_payment_paypal model line
<input type="hidden" name="currency_code" value="BRL">

I'm glad you got it working

Hello Julian, can you explaine please where the location of files, you mention in Step 5 (html code) and Step 6 (php code).

I have exact problems with PayPal, did the first steps and still have GBP at payment system.

Thank you.