Payment Buttons

Coinbase’s Merchant Tools product will be retired on April 30th 2018. Learn more.

Accept bitcoin on your website in an embedded window

Sample Button

Donate Bitcoins

Sample embed code

When you create a payment button, it will give you code like this example.

<a class="coinbase-button" data-code="2b30a03995ec62f15bdc54e8428caa87" href="">Pay With Bitcoin</a>
<script src="" type="text/javascript"></script>

Any bitcoin sent using the sample button will be donated to Khan Academy.


  • Payment buttons allow you to accept bitcoin on your website.
  • Great for personal payments, shopping cart integration, or donations.
  • Users never need to leave your site - the payment flow happens in an embedded window.
  • Prices can be shown in bitcoin or your local currency. Notifications can be sent to your website when an order completes.
  • Bitcoins can be automatically cashed out daily to any bank account.
  • Allows first time users to purchase bitcoin if they don’t own any. Create payment buttons dynamically via the Coinbase API.

How to Create a Payment Button

Payment buttons can be generated via our button generator (shown below) or the button API.

The button generator is the easiest way to get started:

Merchant Tools

The only required paramaters are a name and price. The rest can be set when you create the button or later via the data-* attributes in the embed HTML. data-* attributes will override any attributes you set in the button generator.

Once a button is generated, you’ll be given a few lines of HTML code to copy and paste into your website. This will add the button to your page.

Buttons can be thought of as disposable (they are just a way to hard code a name and price into a code attribute) so if you mess up you can always start over with a new button.

Due to current US regulations, we require you to fill out a small amount of required information to create buttons via the web or API.

Integration Details

A separate bitcoin address is generated for each order and user. This ensures order totals don’t build up at a single bitcoin address.

If a user is already signed in to a Coinbase account, they can complete the checkout in two clicks - this is the fastest method of payment. For users without a Coinbase account the default option is to send payment to a bitcoin address. This method supports all bitcoin clients. A QR code with an embedded bitcoin URI is included for mobile wallets. Users who are new to bitcoin can also learn how to purchase their first bitcoins from within the payment widget.

Advanced Options

Using the Checkouts API

For more advanced integrations, it’s sometimes necessary to create payment buttons for different customers or orders. In these cases you’ll want to use the Checkouts API.

For example, let’s say you wanted to create a “Pay With Bitcoin” button for your e-commerce site. Each order will have a different total so you’ll need to create a new payment button for each order.

In this case you would generate a new button using the following params:

Type Description
amount the order total such as 178.23
currency the order currency such as USD or BTC
name a short description of the order such as Acme Widgets Order #ABC123
metadata the order number you’ll receive in the callback to mark the order as ‘paid’, for example ABC123

The checkouts API will return a new checkout object with a code param which you can use to generate the embed HTML (described below). For further details visit the checkouts API reference page.

Customizing the Embed HTML

The embed html consists of one script tag referencing and an element with class coinbase-button that includes a data-code parameter.

You can have one or more elements with class coinbase-button on the page (if you’re including multiple buttons), but only one script tag is ever needed.

It’s a good idea to use an a tag so that a plain link can also be included in environments where javascript is disabled, but this is not a requirement and other elements (such as a plain div) will also work.

After adding the coinbase-button class, the only required parameter is data-code which hard codes the name, price, and description fields (these are set at the time the button is created and cannot be changed later). The other params can be updated after the button is created by setting data-* attributes on the element. This makes it easy to update fields without having to create a new button.

The div can have the following params:

Field Description
data-code Required unique identifier of the button, this is used to hard code the name, price, and description and is provided for you via the button generator or API.
data-button-style Optional param, one of buy_now_large, buy_now_small, donation_large, donation_small, subscription_large, subscription_small, custom_large, custom_small, or none. These different button styles can be previewed in the button generator and the default is buy_now_large.
data-button-text Optional param, allows you to change the button text (only works with button-styles custom_large and custom_small)
data-custom Optional param, allows you to set any text to link the payment back to your website - usually an order, user, or product ID that you want to mark as “paid” in your database. This parameter gets included in callbacks to your website.
data-width Optional param, can be used to customize the width of the button iframe. The default is 195 pixels.
data-height Optional param, can be used to customize the height of the button iframe. The default is 46 pixels.

Sample button code utilizing the above customizations:

<a class="coinbase-button" data-code="4d4b84bbad4508b64b61d372ea394dad" data-button-style="custom_large" data-button-text="Checkout With Bitcoin" data-custom="order1234" href="">Checkout With Bitcoin</a>
<script src="" type="text/javascript"></script>

Using Your Own Button And Custom Javascript Events

You can also trigger the payment modal using your own button, and bind to a custom javascript event when a payment completes.

First, by setting the data-button-style attribute to none and using an empty div, the default Coinbase button will not be shown on the page.

Next, you’ll want to trigger a custom coinbase_show_modal Javascript event. This event requires the code string to be passed in to determine which modal to show (you can have multiple buttons/modals on a page).

Once a payment completes, a coinbase_payment_complete javascript event will be fired along with a code param referencing the same button/modal. This can be used, for example, to redirect the user to a 'confirmation’ page where you wait for the callback to reach your site.

When the user sends the wrong amount, a coinbase_payment_mispaid event will be fired instead.

If 30 minutes has passed, the button will expire and a coinbase_payment_expired event will be fired.

Here is a jQuery example which uses custom javascript events and a custom link to trigger the payment modal:

<a href='#' class='my-custom-link'>Show Me The Modal!</a>

<div class="coinbase-button" data-code="6ad16caf532b5d802a1141766ee4d823" data-button-style="none"></div>
<script src="" type="text/javascript"></script>

<script type="text/javascript">
  $(document).ready(function() {
      $(document).trigger('coinbase_show_modal', '6ad16caf532b5d802a1141766ee4d823');
      return false;

    $(document).on('coinbase_payment_complete', function(event, code){
      console.log("Payment completed for button " + code);
      window.location = "/confirmation.html";

    $(document).on('coinbase_payment_mispaid', function(event, code) {
      console.log("Payment mispaid for button " + code);
      window.location = "/try-again.html";

    $(document).on('coinbase_payment_expired', function(event, code) {
      console.log("Payment expired for button " + code);
      window.location = "/maybe-later.html";

It’s important to note that the coinbase_payment_complete event does not guarantee a payment has arrived successfully (any user could trigger this javascript event on the page). It is just a convenient way to move to the next step in your checkout. You should always verify the payment via the API or subscribe to notifications. Some merchants prefer to show a 'confirmation’ page next that waits for the notification to reach their site before showing the 'success’ page.

You can optionally upload a logo from the merchant settings page. This will be used in the header of your payment modal (as well as on payment pages).

Once you upload a logo, it will replace the default text that is normally shown in the header.