Tutorial – How To Accept Bitcoin Payments On Your Website

Bitcoin is an attractive payment method for online entrepreneurs mainly due to the fact that its transaction fees are negligible when compared to other popular online payment methods such as wired transfers, payment processors (e.g. Paypal) or credit card transactions. Accordingly, this can lead to a higher profit margin, a more competitive pricing model and the ability to offer services to customers all over the world at convenient costs. Moreover, bitcoin is not formally taxable as it doesn’t present a form of money that is issued by a government. On the other hand, bitcoin payments are pseudo-anonymous and instantaneous, without the need to deal through third party intermediaries, credit card companies or centralized payment processors.

Throughout this tutorial, I will show you how to add bitcoin as a payment method for your e-commerce website. We will use the Blockchain.info Receive Payments API V2 to accept bitcoin payments, as it is simple, highly secure and can be implemented within less than 10 minutes.

Blockchain.info’s API V2:

Blockchain.info’s Receive Payments API V2 is by far the easiest and quickest way to start accepting bitcoin payments from anyone, anywhere in the world. Via a simple HTTP GET request, you can be up and running in no time.

It is worth mentioning that one of the major obstacles associated with accepting bitcoin payments is the need to create a unique bitcoin address for every new user and/or invoice. These generated addresses have to be monitored and stored in a secure manner. The receive payments API is responsible for creation and monitoring of bitcoin addresses. The server will be notified via a simple callback procedure, whenever payments are received.

How to request an API Key?

To be able to use Blockchain.info’s Receive Payments API, you have to fill an application form at:

https://api.blockchain.info/v2/apikey/request/

Note that this API key is only for receiving payments. There is a standard wallet API, that is available in Python, Java, .NET(C#), Ruby, PHP and Node, and can be used to send and receive payments. The standard wallet API is different from the Receive Payments V2 API, as it cannot be used to generate different addresses for different users.

The below image shows the application form for obtaining the Receeive Payments V2 API. You will have to enter your name, email, website url on which you will implement the API and a description of the items you sell or services you offer on your website. In most cases, your application will be reviewed and you will receive a response within 2-3 business days.

Obtaining an Extended Public Key:

This API needs a BIP32 account xPub in order to be able to receive payments.

The simplest way to begin receiving bitcoin payments is to create a blockchain.info wallet at

https://blockchain.info/wallet/#/signup

Inside your wallet, you will have to create a new account to be used exclusively for receiving transactions that are facilitated by the API. When making an API call, use xPub for this account which you can find in (Settings- Accounts and Addresses – More Options – Show xPub code) as shown on the below snapshot:

 

Creating Unique New Addresses for Your Customers:

This will create a new address for each customer to send payment to. An HTTP notification will be sent to you whenever payments are sent to any of the created addresses. Note that every call made to the server will lead to an increment in the “index” parameter to guarantee that no same address is appointed to more than one customer. However, all coins sent to any of the created addresses will be added to the same wallet.

https://api.blockchain.info/v2/receive?xpub=$xpubcallback=$callback_urlkey=$key

As dictated by BIP44, the software of the wallet will not scan more than 20 unused addresses. The API will return an error, refusing to create new addresses, if more than 20 of the previously created addresses were unused. If you are faced with this error, you will have to either move to a new xPub (within the same blockchain.info wallet), or start receiving payments to one of the previously created unused 20 addresses.

This behavior can be optionally controlled via adding the ‘gap_limit‘ as a URL extra parameter. This will not lead to an increase in the number of bitcoin addresses that can be monitored by Blockahin.info’s servers. Adding the ‘gap_limit‘ parameter modifies the maximum allowed gap before which the API will no more generate new addresses.

https://api.blockchain.info/v2/receive?xpub=$xpubcallback=$callback_urlkey=$keygap_limit=$gap_limit

• xpub : your xPub (the destination to which your customers’ payments will be sent).
• callback_url: This is the callback URL address that would be notified whenever a payment is received.
• key: This is your blockchain.info’s Receive Payments V2 API key, that you will receive after your application is successfully accepted.
• gap_limit: This is an optional parameter that determines the number of unused bitcoin addresses allowed before an error is returned.

Via your xPub, create an unused bitcoin address:

curl “https://api.blockchain.info/v2/receive?xpub=xpub6CWiJoiwxPQni3DFbrQNHWq8kwrL2J1HuBN7zm4xKPCZRmEshc7Dojz4zMah7E4o2GEEbD6HgfG7sQid186Fw9x9akMNKw2mu1PjqacTJB2callback=https%3A%2F%2Fmystore.com%3Finvoice_id%3D058921123key=[yourkeyhere]”

 

Now, let your customers send coins to the address returned in the response:

Implementation of Blockchain.info’s Callback:

Whenever a payment is received, blockchain.info’s servers will ping the callback URL you specify. The callback URL is limited to a length of 255 characters.

• transaction_hash: the payment’s hash
• address: the destination address which is a part of the xPub account
• confirmations: the number of confirmations of the transaction.
• value: The value of the received payment in satoshis which is 1/100,000,000 of a bitcoin.
• {custom parameter}: All parameters included within the callback URL will be returned back to the callback URL along the notification. This functionality can be used to add parameters to your callback URL e.g. invoice_id or customer_id to help monitor which payments were made by which customers.

The following represents a PHP example of a callback resulting from the previously presented PHP script:

$real_secret = ‘ZzsMLGKe162CfA5EcG6j’;

$invoice_id = $_GET[‘invoice_id’]; //invoice_id is passed back to the callback URL

$transaction_hash = $_GET[‘transaction_hash’];

$value_in_satoshi = $_GET[‘value’];

$value_in_btc = $value_in_satoshi / 100000000;

//Commented out to test, uncomment when live

if ($_GET[‘test’] == true) {

return;

}

try {

//create or open the database

$database = new SQLiteDatabase(‘db.sqlite’, 0666, $error);

} catch(Exception $e) {

die($error);

}

//Add the invoice to the database

$stmt = $db-prepare(“replace INTO invoice_payments (invoice_id, transaction_hash, value) values(?, ?, ?)”);

$stmt-bind_param(“isd”, $invoice_id, $transaction_hash, $value_in_btc);

if($stmt-execute()) {

echo “*ok*”;

}

 

Callback Response:

To acknowledge that callback was successfully processed, your website’s server has to respond with “ok” (without quotes), in plain text, not HTML. If your server returns any other response, or nothing at all, blockchain.info’s server will resend the callback again for every newly created block, which occurs on average every 10 minutes, for up to 1000 times which would last for 1 week. Callback domains that don’t return any response, or never return the appropriate “ok” response can be blocked entirely from the service.

Checking the Address Gap:

Check the index gap between the last address to which payment was successfully sent and the last address generated via the checkgap endpoint. Use the xPub you wish to check along with your API key via the following:

curl “https://api.blockchain.info/v2/receive/checkgap?xpub=[yourxpubhere]]key=[yourkeyhere]”

{“gap”:2}

Security:

A unique secret parameter has to be added in the callback URL $secret. The secret will be fed back to the callback script when the callback is executed, and should be checked by the code you create for validity. This will prevent malicious users from trying to ping your servers and fraudulently mark an invoice as paid.

Fiat Currency Conversions:

You can use Blockchain.info’s Exchange Rate API to add prices in local fiat currencies in addition to bitcoin.

Expiration of Addresses:

Bitcoin receive addresses will never expire and will be monitored continuously all through the way until an “ok” response is returned within the callback response or the callback URL has been notified 1000 times.

Fair Usage:

There is no upper limit for the number of receiving bitcoin addresses that can be created, provided that the 20 address gap limitation point is not reached, as the service was designed to monitor millions of bitcoin addresses.

As mentioned earlier, callback domains that never return an “ok” response or don’t respond at all i.e. dead domains, will be probably blocked from the service.

This was a concise tutorial to help you add bitcoin payments to your website. We presented an example implementation in PHP, yet it can be done also in Python and Ruby.

If you have any questions, or have any problems while trying to implement the API, feel free to ask in the comments section below.