Example client/server implementing of the Bitcoin Payment Protocol (BIP70)

I’ve been experimenting with different possibilities to integrate Bitcoin payments into applications and websites. I believe payments must become easier and bitcoin provides some great possibilities there. 

In the following post looks into the Bitcoin Payment Protocol (BIP70) and shows some code for a simple server implementation (in Ruby) and a client/wallet implementation (in Java). 

What is the Payment Protocol? 

The Payment Protocol, described in Bitcoin Improvement Proposal 70, is a protocol for communicating between the customer’s Bitcoin wallet/client and the merchant’s server application. It greatly improves the checkout experience for the user. The user does not have to deal with bitcoin addresses but simply opens his wallet with a Payment Request from the merchant (for example by clicking on a link) the wallet gets the needed information for the payment from the merchant’s server. The user confirms the payment and the wallet notifies the server about the payment. 

Besides optimizing the user experience the Payment Protocol also describes a process for refunds or exchanging additional data or notes. 

Payment Protocol sequence diagram

Wallet implementation

I am using bitcoinj for most apps working with the bitcoin protocol. It has pretty good support for BIP70.

We will give the wallet a BIP72 bitcoin URL which contains the URL of th payment request (see server implementation). Once received we parse and validate the request. The validation is done using a X.509 certificate.

When the user has confirmed the payment we create one or more transactions to fulfull the payment request and send these back to the merchant. The merchant validates the transaction, publishes them to the Bitcoin network and sends a confirmation (ACK) back to the user.

The code might be a bit hard to read on the blog here, have a look at the BIP70 example GitHub repo. And have a look a the comments for code explanation.

Let's get to the wallet code!


Server implementation

Now let's look on the merchant side of things. Here I am using Ruby, but the code is pretty straight forward and should look pretty similar in your favorit language.

We basically need two endpoints:
One for generating the payment request which is requested by the wallet in the first step.
And a second one for accepting the payment and the payment ack.

Protocol buffers are used for the communication. In our example we use the gem "protocol_buffers" for parsing and generating these (have a look in the BIP for the details)

OK, let's look at the code:


You find all sources in the GitHub repository.


The BIP 70 Payment Protocol improves the user experience for payments and solves the issue that the user sees who whe is paying and that he gets an immediete response from the merchant if he received the payment.
Most Bitcoin Payment Service Provides support the protocol. But experiment with it! It is easy to implement in your application/website to accept payments.

Update: btw. here is a good BIP70 introduction video