|
[How-To] Use a new currency on your custom payment gateway
by
26 May 2012
Rating:
 (1 vote
- 5.00 average) 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
================================================= ================================================= 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.
================================================= ================================================= 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('£', 'COP$', $subscription_cost);
PHP: PHP Code:
$subscription['cost'] = str_replace('£', '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>">
================================================= ================================================= 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. **/
================================================= 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. |