Documentation

Bitcoin eCommerce Payment Provider Documentation

Documentation last updated: Thursday May 14h 2015

Purpose of this Add On:

This Add On makes it easy for a merchant to accept the digital currency Bitcoin using the official Concrete5 ecommerce addon

Requirements:

You must have the official Concrete5 ecommerce addon and a Bitcoin Wallet. If you want to get up and running quickly, we recommend getting a free wallet at blockchain.info to get you started.

This plugin must be installed on a live domain in order for the callback function to work. The blockchain.info API will try to make a callback to your web site when a transaction is confirmed and it will not be able to do so if you are using 'localhost' or '127.0.0.1' as your domain.

Installation

Installation is very straightforward.

Watch Installation and Setup Video at https://www.youtube.com/watch?v=UCmWoLwbXx0

Download the plugin from the Marketplace.
Login to your site as admin
Go to the Dashboard
Click on Install from the bottom panel on the dashboard (Extend concrete5 – Install, update or download more themes and add-ons.)
Click on Install on Bitcoin eCommerce Payment Provider
Return to your Dashboard
In the Ecommerce Panel of the Dashboard -> Select Payment & Sales Tax
You should see Bitcoin Method as an option.
Click on Bitcoin Method to enable it and configure it.

The following steps are optional.

These steps allow you to see more information about the transaction in the order details page. It involves adding an extra attribute to billing or shipping table called 'ds_order_notes'. If the plugin detects the presence of the 'ds_order_notes' attribute, it will populate it with more information about the transaction such as the exchange rate at the time, whether the site was in test or live mode and the Bitcoin Wallet Addresses used for the transaction.

Go to Dashboard -> ECOMMERCE Settings -> Order Attributes
At the bottom of the page, "Add Attribute", add an attribute of type "textarea"
On the following page, give it the handle "ds_order_notes" (all lower case)
Sadly this block is added to a visible area of the ordering process, so you will need to decide whether to include it in the shipping or billing phase of the checkout. The checkboxes are optional but if you select 'required when checking out' the customer will need to enter something to proceed with the order. You could use this to add notes such as "How did you hear about us?" or other information you would like the customer to enter at checkout.
There are no further steps....
The Bitcoin plugin can now detect this - and will use this field to display extra information about the transaction in the order details pages of the Ecommerce addon..

Configuring the module

To configure the module you will need your Receiving Bitcoin Wallet Address and Encryption Password. Do not attempt to activate the module until you have these available.

Name:

This is the name displayed to customers where the module is called. ie .. "Click here to pay by {Name}" so you may want to change this to "Bitcoin" so that the messages in the front end of the site say "Click here to pay by Bitcoin".

Enabled:

To make the Bitcoin Payment Method available to customers on your site, this must be set to YES.

Receiving Address

This is the address that you will use to receive Bitcoin transactions. As we are using the blockchain.info API, the system will create other receiving addresses but ultimately all transactions will be received in your Receiving Address.

Test Mode:

As all transactions using Bitcoin need to be authenticated on the Blockchain, you need to send real Bitcoins. By enabling Test Mode it sets the transaction value to a nominal BTC 0.0005 (approx $0.12) - If you set your receiving address to the same one as you send from, your BTC 0.0005 will just reappear in your account once you've sent it.

Currency:

The currencies supported are USD, JPY, CNY SGD, HKD, CAD, NZD, AUD, CLP, GBP, DKK, SEK, ISK, CHF, BRL, EUR, RUB, PLN, THB, KRW, TWD. These exchange rates are available for real-time calculations using the blockchain.info API.

Confirmations:

This defines the number of blockchain confirmations you want to see before you change the transaction from Pending to Authorised.

Known Issues & Bug Reporting

Please report any bugs, issues or general feedback.

Additional Information / Database Structure:

The following information may be useful to more technical customers who want more information in terms of what the plugin is doing and are happy to hack the core eCommerce module to display extra information regarding the transaction. We could not include this information easily within the plugin as the Core eCommerce Addon does not have a notes field that we could use to include this information (although you can create a ds_order_notes textarea attribute to display it in the order table) .

The Bitcoin eCommerce Payment Provider addon adds a table to your Concrete5 database: DatasouthBlockchainTransactionLog This table is added to log incoming data from the blockchain so that you can diagnose faults.

coreOrderID

coreInvoice

000003

bcTransactionHash

6df811dfac5d7bb756fc6982ed71b7c6e9c6279a6363e7086f75abda4ddcc17b

bcCallbackUrl

{This is the long URL to call the Blockchain API}

bcAmount

0.07682131 {Note this does not account for test transactions at 0.0005}

bcResponse

{Response from the Blockchain API}

bcAddressTemp

{This is the temporary address that was assigned by the blockchain API}

bcAddressStore

{This is the Receiving address that you defined in the Payment Setup}

bcStatus

*ok* {Final Status of the transaction from Blockchain}

coreStatus

coreCustomer

{Name of Customer}

coreEmail

{Email Address of Customer}

orderAmount

{Value of Order in Commerce Native Currency}

dateAdded

{Date this row was added to the database}

lastUpdated

{Date this row was last updated - ie. when confirmation is received and order is switched to Authorised}