How to use LocalBitcoins to accept Bitcoin in your web store

With the LocalBitcoins API you can easily accept bitcoin as a payment method in your web store. You can specify your prices in any currency because the bitcoin amount is calculated automatically at the time of purchase. When the user wants to pay, the user is re-directed from your web shop to the LocalBitcoins payment page. After the customer has made the payment they are redirected back to your success page. The bitcoins are sent directly to your localbitcoins wallet. From there it is easy to convert to any currency of your choosing.

There are two options to start accepting Bitcoins in your web store using LocalBitcoins API. You can either use an existing plugin for your web store platform or you can code the integration yourself. A list of plugins can be found at the bottom of this page. If you cannot find your web store platform there read on and learn how to code the implementation yourself. Some programming skills are required.

Setting up your account

Register an account with LocalBitcoins. To use the API you need to activate two-factor authentication. Next, create an HMAC access token with read privileges. In order to delete invoices through the API your HMAC access token needs write privileges. Please note that with write privileges you can do significantly more harm than with read privileges. You can create HMAC tokens using LocalBitcoins Apps Dashboard.

Talking with the server

If you are using Python you can use this library we have developed to interface with our API. For other programming languages try searching Github. If you cannot find suitable client library we recommend using our library as reference when writing your own client side code.

API calls for accepting bitcoins

Once customer is ready to pay the order you should create new invoice and redirect customer to the invoice URL that you got as a return when you created the invoice. After customer has made the payment he will be redirected back to your web store if you have provided the return_url. You should always provide the return URL. Otherwise customer will be stuck in our site wondering what he should be doing next. Please note that you should consider the return_url as public and that it is possible that it gets called several times or not at all. Use invoice details call to check the state of the payment.

In pseudocode, when the shopping basket is ready and user wants to pay using BTC:

        invoice_details = localbitcoins_api_call("/api/merchant/new_invoice/",
            {"currency": "USD", "amount": 15, "description": "alpaca socks", "return_url": "https://merchant.com/success"})

        redirect_user_to(invoice_details['url'])
        

Querying the invoice state:

        invoice_details = localbitcoins_api_call("/api/merchant/invoice/15/")

        if invoice_details["state"] == "PAID_CONFIRMED":
            send_product()
            mark_as_handled()
        else:
            # handle different states here
        

That's pretty much all there is that you need to know to get you started implementing bitcoin payments to web store platform of your choosing. Happy coding.

List of plugins

Want more help?