Payment Buttons
Accept bitcoin on your website in an embedded window

Sample Button

Pay With Bitcoin

Sample embed code

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

<a class="coinbase-button" data-code="4d4b84bbad4508b64b61d372ea394dad" href="https://coinbase.com/checkouts/4d4b84bbad4508b64b61d372ea394dad">Pay With Bitcoin</a>
<script src="https://coinbase.com/assets/button.js" type="text/javascript"></script>

Any bitcoin sent using the sample button will be donated to the Bitcoin Foundation.

Features

  • 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.
  • Callbacks 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 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 (for programmers).

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.

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

For more advanced integrations, it's sometimes necessary to create many buttons with different prices. In these cases you'll want to use the buttons 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:

price_string
the order total such as 178.23
price_currency_iso
the order currency such as USD or BTC
name
a short description of the order such as Acme Widgets Order #ABC123
custom
the order number you'll receive in the callback to mark the order as 'paid', for example ABC123

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

It's worth noting that generating multiple buttons this way is only necessary if you want to set prices dynamically. If you only have a few items with the same price you can generate buttons manually and modify the data-custom attribute to change which value is returned in the callback.

The embed html consists of one script tag referencing https://coinbase.com/assets/button.js 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:

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="https://coinbase.com/checkouts/4d4b84bbad4508b64b61d372ea394dad">Checkout With Bitcoin</a><script src="https://coinbase.com/assets/button.js" type="text/javascript"></script>

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.

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="https://coinbase.com/assets/button.js" type="text/javascript"></script>

<script type="text/javascript">
  $(document).ready(function() {
    $('.my-custom-link').click(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";
    });
  });
</script>

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 was received via the callback to your site. Some merchants prefer to show a 'confirmation' page next that waits for the callback 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.

Custom logo: Default text:
Header_custom Header_default

What's next?
  • Payment Pages - Redirect users to a payment page hosted on coinbase.com.