GuidesAPI Reference
DocumentationLog In

Add payment button

Embedding a payment button on your website is a quick and easy way to start accepting cryptocurrency payments, whether it’s to accept donations for an open source project or to sell tickets to your event. Let's start.

Whitelist your website

Before embedding a payment button, you’ll need to first whitelist your website. You can do this by navigating to Settings and adding your website under the Whitelisted domains section by clicking on Whitelist a domain.

You’ll be asked to enter your website domain; enter your website and click Save. Note that at this time we only allow https domains.

Create a payment button

To create a payment button click on the Accept payments button within the dashboard.

To make it easy to accept payments without developing a custom integration, we’ve made it possible to choose between two basic payment types:

Once you’ve gone through the flow you’ll be given a link to a hosted page where you can immediately start accepting cryptocurrency payments. On the Embed tab you’ll find a code snippet that can be used to embed a payment button on your website.

Embed your payment button

Now all you need to do is add the code snippet to your website and you’re all set to start accepting cryptocurrency payments!

Testing payment buttons

Best practice is to test before deploying. Here’s a quick way to test your payment button before pushing it to the world.

First you should whitelist localhost or, if you’re using a service like ngrok, the forwarding URL. You can whitelist localhost by adding http://localhost:8000 as a whitelisted domain by taking the steps mentioned earlier.

Second, create a simple HTML file with the button code embedded so you can serve the file locally. At the command line create an empty folder along with an empty index.html file:

$ mkdir payment-button && cd payment-button && touch index.html

Now simply add the payment button code snippet to your index.html file using your preferred editor. The contents of your file should look something like this:

  <a class="donate-with-crypto"
    <span>Donate with Crypto</span>
  <script src="">

From within the payment-button directory, run python’s SimpleHTTPServer (this assumes you already have python installed):

$ python -m SimpleHTTPServer

Next navigate to http://localhost:8000 in your browser. You should see your payment button rendered in the browser.

Congratulations! In just a few minutes you’re up and running able to start accepting cryptocurrency on the web.

Callback Functions (Advanced)

The embedded button exposes the following callbacks:


An onload query parameter specified in the script source will be called by the script once it has

<script src=""/>

Event Callbacks

Once the BuyWithCrypto class has been instantiated, multiple event callbacks can be registered with it:

BuyWithCrypto.registerCallback('onSuccess', function(e){
    // Charge was successfully completed

BuyWithCrypto.registerCallback('onFailure', function(e){
    // Charge failed

BuyWithCrypto.registerCallback('onPaymentDetected', function(e){
    // Payment has been detected but not yet confirmed

When triggered, the callbacks will be called with the following event object:

    buttonId: "unique id for this embeddable button",
    code: CHARGE_CODE,
    event: "charge_failed" OR "charge_confirmed" OR "payment_detected"

The CHARGE_CODE is the code of the created charge, and can be found here.


Custom metadata can be passed to the associated checkout with a data-custom prop. It can be seen in use here:

  <a class="buy-with-crypto" data-custom="MY_CUSTOM_DATA" href="">
    <span>This is a button.</span>
  <script src=""></script>


By default, Coinbase Commerce will cache the state of transactions in case a user accidentally navigates away from the page in the middle of their payment.
This behaviour can be disabled with a data-cache-disabled prop as seen here:

   <a class="buy-with-crypto" data-cache-disabled="true" href="">
     <span>This is a button.</span>
   <script src=""></script>