Bitcoin Payment Processing with BitPay

What is Bitcoin?

So you may have heard about Bitcoin, some of you might be quite familiar with it - but for those who aren't, it is a digital currency - a form of electronic cash which can be used to make online payments, transfer money to friends - in theory, anything that you can do with traditional money, you can equally do with Bitcoin.

Bitcoin uses many of the ideas initially developed for peer-to-peer file sharing networks to create a decentralized system, ie: one that is not controlled and cannot be manipulated by any person, organization or government. The software it runs on is open source and can be viewed by anyone, and so in this sense, it is very much considered to be in the public domain, both in terms of the network itself, and the software running on it.

I hope that is an ok explanation for the purposes of this post - but for those who'd like to find out more, there are some links below to some good sources who can explain it much better and in a bit more detail than I can:

• Bitcoin Simplified - http://bitcoinsimplified.org
• Bitcoin Wiki - https://en.bitcoin.it
• Bitcoin 101 - https://www.youtube.com/channel/UCgo7FCCPuylVk4luP3JAgVw

So What is BitPay Then?

BitPay is a payment processing service for Bitcoin payments - they are kind of aiming to be the Paypal of the Bitcoin world. Whilst Bitcoin is a public network, and you can theoretically broadcast transactions to the network yourself without having to rely on a third-party to do that for you (we are working on a payment processor for that too, but more on that coming soon), it requires a lot of setup, your own server, a fair bit of background knowledge - it's probably not for most people.

So BitPay aims to simplify the process of accepting Bitcoin payments by providing a gateway interface similar to any other payment processor. It's worth noting there are plenty of alternative payment processing providers for Bitcoin payments out there, but BitPay is one of the most popular, and it's the one we've decided to implement for now.

Installation

You can currently get hold of the extension from the Github url below - although we'll make it available through the public extensions directory once it's been better tested and is considered stable:

https://github.com/circleinteractive/uk.co.circleinteractive.payment.bitcoin

Place that in your extensions directory (either by cloning through git, or by downloading the zip file), and then enable the extension. This will make two new payment processors available - 'Bitcoin' and 'BitPay'. Ignore the 'Bitcoin' one for now.

Also, be sure to configure your extension resource URL (will try to add a warning for that in due course), as the extension will not work correctly if this is not done.

To add the BitPay processor, go to Administer -> System Settings -> Payment Processors and click 'Add New Payment Processor', then select 'BitPay' on the next page.

You should see a screen like the one below:

All you should need to do is name your processor, enter an optional description, and enter your BitPay api key. An API key can be generated through your account dashboard on the BitPay site.

You may also see the following warning:

See the section below marked 'Payment Notifications' for more info on this, but in short, we have designed the processor to work with or without SSL, so if you get this warning, you should make sure cron is running, and configure it to run as often as you think sensible - we would recommend at least every 15 minutes, but preferably every 5-10 minutes to ensure payments are completed as promptly as possible after confirmation is received.

Overview

So here is a test event page with the BitPay processor enabled, along with some others:

You'll see it converts the prices to BTC at the current exchange rate when you have BitPay selected as the processor. So you set the prices in your local currency, and the price in BTC is calculated at the time of signing up. And that is also displayed on the confirmation screen before checking out, here:

Payment

To make payment, the user will be redirected to the following page on the site:

You can make payment either by using a mobile wallet app to scan the QR code, clicking the 'Pay with Bitcoin' button - this will open up a wallet app on your computer which is configured to handle Bitcoin links, with the amount prefilled - or you can manually send the amount on the invoice to the address at the bottom.

For now, we're going to use a mobile wallet app to demonstrate - so scanning the QR code with your app prefills the receiving address and amount, like so:

Then all that is required is to click the 'Send Payment' button. When you've done that, the on-screen invoice should display a status of paid:

.. and then redirect to the usual 'Thankyou' page which we're all familiar with.

Confirmations

There will be a delay before the transaction is fully completed, as at the moment, the processor uses the default behaviour of requiring 6 network confirmations before considering the transaction as completed, at which point the contribution will be marked as complete in Civi, and confirmations emails sent (if configured).

This is to guard against fraud and something known as 'double spending', and is quite important when exchanging Bitcoin for physical goods, as you don't want to be in a situation where you've sent out the goods, then later discover the transaction to be fraudulent.

However, with the type of transactions Civi handles (contributions, event registrations, memberships), it is not so important, as with contributions, you don't generally get anything in return - and with memberships and event registrations, these are things that can be revoked or cancelled if the confirmation process subsequently fails.

So we will probably introduce an additional setting for this on the payment processor configuration page, whereby you can choose to complete the transaction immediately, as soon as it is marked as paid - however, you should be aware of the potential dangers of doing this.

In short though, there is currently a delay of 30 mins to 1 hour while confirmations are received, before the transaction is marked as complete in Civi.

Payment Notifications

For security reasons, BitPay will only send payment notifications to an SSL (https) url - this is when the BitPay site contacts your site to provide updates on the status of the invoice - basically, whether the payment has gone through or has failed.

So if your site has an SSL certificate installed, you shouldn't need to read any further - everything should just work as if by magic. Just be sure to check that anonymous users have the 'Profile listings and forms' permission, which I think is the case for all processors that implement payment notifications.

However, we're aware that the majority of CiviCRM sites don't have SSL certificates, and thought this might be a bit of a drawback for a lot of users / potentially limit the audience somewhat, so have designed in a fallback system for those cases.

There is a Scheduled Task (cron job) which should enable itself automatically if it detects you don't have an SSL certificate - all you need to do is configure cron to run as often as you can. Be careful with this, as it does have a potential impact on the performance of your site - but as stated above, at least every 15 minutes would be good, every 5-10 minutes would be better, but it's up to you to decide what's best for your use case - the less often it runs, the longer payments will take to be marked as complete in Civi after BitPay has received the necessary confirmations.

That is all

I hope the extension proves useful - please try it out, let me know about any bugs or problems. There is a forum thread here for the moment where you can do that, although I will probably start a new one just for this extension if it proves popular / if there are a lot of issues.

Also, many thanks to Circle Interactive, who let me spend a fair bit of work time doing this. It wasn't written for any particular client - we just did it because we wanted to, and thought it might be a nice addition to Civi.