Advice and answers from the BitPay Team

The freely downloadable Magento Community Edition version 1.9.x is a powerful and flexible open source ecommerce platform. Accepting customer payments in Bitcoin is easy with the BitPay Magento plugin. This howto guide will take you step by step through the process and explain some commonly experienced caveats along the way. Let's get started!

Prerequisites

  • You'll need a Linux server running the LAMP (Linux, Apache, MySQL, PHP) stack. Windows and Mac servers are not officially supported production environments although they will function for local testing purposes. Just keep that in mind if you need Magento support later on: a Linux server is required! If your business already has a website, you probably meet this requirement but double check with your web hosting provider. (A complete and official list of Magento requirements can be found here: http://magento.com/resources/system-requirements)
  • Your website will need an SSL certificate for encrypted communication with the BitPay network. These certificates allow you to protect customer information and is required for use with BitPay. Your web hosting provider may sell these and install them directly, so contact them first for more information. If you can reach your website using an https:// URL then you already have an SSL certificate installed and you meet this requirement.
  • If you have not done so, you'll need to apply for a BitPay merchant account to generate an API key for use with the payment plugin. This is easy and only takes a few minutes on the BitPay website: https://bitpay.com

Installation

Download and Unzip the Plugin

Once you have Magento CE 1.7 installed, download the official BitPay plugin here:https://github.com/bitpay/magento-plugin/archive/master.zip

Note:This link will always point to the most updated version so it's best to check periodically to ensure you are using the most current version!

Inside this Zip archive, you will find a collection of files and folders. Unzip this archive and copy these files to the location of your Magento installation on your web server. For Ubuntu-based servers, the default location for website files is the /var/www folder. Your web hosting provider may use a different location so check with them if this folder does not exist or your Magento files are not there.

Most web hosting accounts have a graphical, web-based control panel for your server. This is the easiest method for copying the BitPay plugin files. If your provider has one of these control panels, log into your hosting account and move the files using that tool. However, if that is not an option and you can only access your web server using a shell account via SSH, open a new connection and issue these commands:

bitpay@bitpay:~$ unzip magento-plugin-master.zip
bitpay@bitpay:~$ cd magento-plugin-master
bitpay@bitpay:~$ cp -R ./* /location/of/your/magento/installation/

Note: You may need to have superuser privileges to copy files to /var/www on Ubuntu-based servers. If you receive "Permission denied" errors when using the cp command above, use sudo before the cp command and specify the superuser password when asked:

bitpay@bitpay:~$ sudo cp -R ./* /location/of/your/magento/installation/
[sudo] password for (username):

Verify the Plugin Files

Verify the files have been copied correctly by checking your Magento installation location for one or more of them. For example, I'm going to check for the PaymentMethod.php file but you can choose to check for any of the files present in the BitPay plugin archive. The file I'm looking for in this example should be in the /var/www/magento/app/code/community/Bitpay/Bitcoins/Model directory along with the Ipn.php file:

bitpay@bitpay:~$ ls -l /var/www/magento/app/code/community/Bitpay/Bitcoins/Model/
total 24
-rw-r--r-- 1 root root 3097 Mar 25 14:06 Ipn.php
-rw-r--r-- 1 root root 10786 Mar 25 14:06 PaymentMethod.phpd
rwxr-xr-x 3 root root 4096 Mar 25 13:54 Resourced
rwxr-xr-x 2 root root 4096 Mar 25 13:54 Source

If the files were copied correctly and are present in the directory, you should see the files listed when you issue the ls command. If you do not see any files listed, try the cp command again to retry the copying procedure. However, if you still do not see any files listed or you receive an error copying the files, contact your web hosting support for assistance.

Create Your API Key

Now that you have the plugin files correctly installed, create your BitPay API key. Open your web browser, go to http://bitpay.com, and log into your merchant account:

You can create a new API key by clicking My Account -> API Access Keys -> Add New API Key. The new key should be a 32-character alphanumeric string that looks something like: k4pY8yD9hpYy3FLuK3OXYnA5tFmw0NXqxzW4uyzJQ4. This is the string that you will need to copy into the Magento control panel settings for the BitPay payment plugin.

Note: Protect your API key(s). They should be treated like passwords, as they allow services to access and perform actions on your account. Also be careful not to accidentally include them in screenshots (like these).

Configure Magento

Log into your Magento CE 1.7 administration panel and click on Configuration under the System menu.

Scroll down to the Sales menu on the left side of the window and click on Payment Methods. You should now see the entire list of payment methods your Magento store can use. The Bitcoins configuration section is at the bottom of this list. Click the grey bar to expand the section.

Copy the API key from your BitPay merchant dashboard and paste it into the API key text box on the Bitcoins payment method configuration screen. You can also change any other option while you are on this screen.

Available Options

  • The Enabled option determines whether this payment method will be offered to your customers when they checkout. The default is Yes.
  • The Title option specifies what you want this payment method to be called. The default is Bitcoins.
  • Fullscreen invoice specifies if you want the BitPay invoice to be embedded into your checkout page or redirected to our site during the payment process. The default option is No which embeds the BitPay invoice in your payment page.
  • The API key field is where you enter your BitPay merchant API key found in your merchant dashboard. You cannot use this plugin without specifying an API key.
  • Transaction speed refers to how quickly you receive a Bitcoin payment confirmation. The options are explained here in the configuration speed and the default setting is Low which is the safest option for merchants to ensure a payment is fully confirmed.
  • The Currencies accepted by BitPay field specifies the various currencies our payment service can handle.
  • Sort Order refers to the placement of the Bitcoins option on the payment page. This field is blank by default but you can specify a number here to move the placement of the payment option higher or lower on your checkout page.
  • The Set order complete with "complete" IPN option specifies if you want our plugin to mark the order complete when this Instant Payment Notification message is received from BitPay. If you want to retain the control to manually change an order from a processing state to complete state, leave this option set to the default No setting.

When you have added your API key and made any other required changes to the payment method settings, click on the orange Save Config button at the top of the page. The page will refresh and you should see a green box at the top of the page informing you that your configuration has been saved.

Congratulations! Your customers can now pay for your products with Bitcoin. If you would like to test the process, create an inventory item with a price of $0.01 and complete the checkout process with Bitcoin.

Advanced Configuration

There are some available internal parameters for this plugin that are not exposed in the administrative configuration screen that require familiarity with the PHP programming language to use. Inside the PaymentMethod.php file are a series of boolean variables that can be changed to alter certain characteristics. Most of these variables should not be touched and can break or disable the payment gateway, however two options are safe to modify and provide two additional options for the merchant:

/*
*
* Can use this payment method in administration panel?
*/
protected $_canUseInternal = false;

If you would like to have the ability to process Bitcoin payments in the administration panel, change this variable from false to true.

and

/*
*
* BitPay - create shipment automatically after completing order?
*/
protected $_bpCreateShipment = false;

This option, as the comment implies, activates conditional code that will automatically create shipments for you when the complete IPN is received.

Note:Both of these options are disabled by default and care should be taken when editing any source code files. Always make a backup of the files before any modifications are made to ensure you can always revert your changes should your modifications break the plugin.

Installation tips for Magento CE 1.8.x

In some instances for merchants using Magento CE version 1.8.x, the BitPay Bitcoins payment plugin might not appear in the Payment Methods configuration section even though all plugin files have been correctly installed. To resolve this issue, log into your admin control panel and choose the System -> Cache Management configuration screen. Click the checkbox next to the Configuration cache type and choose the Disable action from the Actions drop-down list box. Click the Submit button to disable this cache.

Next, click both the Flush Magento Cache and Flush Cache Storage buttons (Clicked "Ok" when the pop-up box is displayed) to remove the stale configuration cache files.

Finally, log completely out of the administrative control panel and then log back in. The Bitcoins option is now correctly displaying under Payment Methods in the configuration screen. The BitPay plugin parameters are exactly the same on Magento CE 1.8.x as on older Magento CE releases.

Troubleshooting

The official BitPay support website should always be your first reference for troubleshooting any problems you may encounter: https://support.bitpay.com

The official Magento Community Edition support website might also be helpful if the problem you are experiencing is not directly related to the payment plugin:https://www.magentocommerce.com/support/ce/

Try These First

  1. Ensure a valid SSL certificate is installed on your server. Also ensure your root CA cert is updated. If your CA cert is not current, you will see curl SSL verification errors.
  2. Verify that your web server is not blocking POSTs from servers it may not recognize. Double check this on your firewall as well, if one is being used.
  3. Check the bitpay.log file for any errors during BitPay payment attempts. If you contact BitPay support, they will ask to see the log file to help diagnose the problem.
  4. Check the version of this plugin agains the official plugin repository to ensure you are using the latest version. Your issue might have been addressed in a newer version!
  5. If all else fails, send an email describing your issue in detail to support@bitpay.com
Did this answer your question?