Coinbase Buy Widget

The Coinbase Buy Widget enables 3rd party developers to embed Coinbase buy functionality into their websites and applications. It allows users to buy bitcoin (BTC), ether (ETH), or litecoin (LTC) directly into addresses provided by the applications.

The Buy Widget is currently limited to customers in the United States using ACH bank accounts, debit or credit cards.

Instant buys using debit and credit cards

With limited KYC, the Buy Widget supports instant buys up to $350 a week using debit or credit cards. Each new user also has a lifetime limit of $500 after which they are asked to set up a full Coinbase account to remove that limit.

Delayed buys using ACH bank accounts

If your integration requires higher than $350/week limits, then you can use the ACH Buy Widget. Users will have the same limits they have on Coinbase and will be able to use their linked bank accounts or add new ones through the widget, directly in your application. Once the ACH transaction clears (usually takes 2-3 days), Coinbase will automatically send BTC or ETH to the address you provided.

You can choose to display one or more payment method types. If you choose to accept more than one payment method, your users will see an option to choose their preferred payment method.

Here are some of our featured developers who have already integrated the Buy Widget into their apps to help their users buy bitcoin or ether:

Implementation guidelines and user flows

To ensure a smooth and good user experience for the Buy Widget, we recommend that you follow these guidelines.

When welcoming a user to buy BTC or ETH with the Buy Widget, it should be clear that the user will be using Coinbase to buy cryptocurrency into your application. If you’re using the Javascript SDK on a website, it will render a buy button which will communicate this for you.

When the user initiates the widget, the user is greeted with an email field. Based on the user’s email, the user is either asked to log in or sign up with Coinbase.

Installing the Buy Widget

To set up the Buy Widget, you have two options:

  • Embed it into your application with our Javascript SDK
  • Using a direct link, open it in a separate web view either in a new browser tab or inside webview on a mobile application

Parameters

Both methods require the same parameters:

  • code - Your Buy Widget code that you will get when you set up your widget.
  • amount - (Optional) Amount to buy in USD
    • Maximum amount is $350 for debit and credit card widgets.
    • For ACH widgets the limits will be the same as the limits on coinbase.com
    • Fee of 3.75% (debit/credit card) or 1% (ACH bank account) will be added to the amount and the breakdown will be shown on the buy confirmation step
  • address - (Optional) Bitcoin or Ethereum address to which the funds will be sent after the buy has been completed. Leaving this blank will mean that the users’ funds will remain in their Coinbase account
  • redirect_uri - (Optional) If the widget was opened in a separate page, the customer will be redirected to this page after they have completed or canceled a purchase. Must begin with either http:// or https://
  • state - (Optional) Developer defined variable that will be passed back via a postMessage after users complete the buy flow. See section Post purchase flow for more details
  • prefill_email - (Optional) Developer can prefill the user’s email. This is validated, so if the email is invalid the field will not be prefilled.

Javascript SDK

The parameters that were described above need to be passed to the widget as data attributes:

  • data-code
  • data-amount (Optional)
  • data-address (Optional)
  • data-state (Optional)
  • data-prefill_email (Optional)

Embed the SDK using the following code:

  <a class="coinbase-widget"
     id="coinbase_widget"
     data-address="{{ address }}"
     data-amount="{{ amount }}"
     data-code="{{ code }}"
     href="">Buy bitcoin using Coinbase</a>
  <script type='text/javascript' id='coinbase_widget_loader' class='coinbase-widget-async-loader'>
    document.currentScript.src ='';
    (function() {
      function asyncLoad() {
        var s = document.createElement('script');
        s.type = 'text/javascript';
        s.async = true;
        var theUrl = "https://buy.coinbase.com/static/widget.js";
        s.src = theUrl+ (theUrl.indexOf("?") >= 0 ? '&' : '?') + 'ref=' + encodeURIComponent(window.location.href);
        var embedder = document.getElementById('coinbase_widget_loader');
        embedder.parentNode.insertBefore(s, embedder);
      }
      if (window.attachEvent) {
        window.attachEvent('onload', asyncLoad);
      } else {
        window.addEventListener('load', asyncLoad, false);
      }
    })();
  </script>

You can direct users to the buy page by passing the parameters as get params. Construct the url as follows:

https://buy.coinbase.com?code=9023urn3f8934hg34&address=1JcssT2Cr2xhnfcYscLL1bZPbojg4rUC2X

Post purchase flow

After customer has completed their purchase, or canceled it, they will return to the host application.

When using the Javascript SDK, the widget will use either use Javascript’s postMessage API to dispatch a message to the parent page or redirect the user to redirect URI if it’s defined.

Both postMessage and redirect URI will return the following values:

  • status - Either buy_completed (user purchased bitcoin) or buy_canceled (user canceled buy or unable to purchase for some reason)
  • address - Bitcoin address for the buy
  • state - Same state that was provided when initializing the widget

When implementing postMessage listeners, one should always check their origin domain and eventually wait for blockchain confirmations for the transactions:

function receiveMessage(event) {
  // Only trust Coinbase with messages
  if (event.origin !== "https://buy.coinbase.com")
    return;
  console.log(event.data);
}

Setting up the Buy Widget

If you would like to add the Buy Widget to your app, please let us know by filling out this application form and we will get back to you.

Security

We take security very seriously at Coinbase, and securing our customers’ information and funds is our top priority. The Buy Widget has been designed in collaboration with and reviewed by Coinbase’s internal security team and it’s also part of Coinbase’s public bug bounty program.