• Quickstart
  • Guides
  • Integrations
  • Libraries
  • SDKs
  • Quickstart

    Cryptocurrencies have dramatically lowered the barrier to accepting payments on the web. Coinbase Commerce makes it easier than ever to accept cryptocurrency in the way cryptocurrencies were designed to be accepted: in a truly peer-to-peer fashion.

    Introduction

    Coinbase Commerce allows you to be your own bank with all the benefits of a hosted service. It's no longer necessary to build and maintain infrastructure to monitor the blockchain; stay focused on running your business and leave the rest to us. Using public keys created on signup for each cryptocurrency, we're able to generate payment addresses on your behalf and continuously monitor the blockchain to detect when payments are made.

    Customers can now pay you directly from their computer or mobile device using the blockchain as the settlement network. With cryptocurrencies you no longer need to collect and store payment credentials or sensitive customer information.

    Using the Commerce API

    Accepting cryptocurrency payments with the Coinbase Commerce API is fast and easy. After you've signed up and created an API key, which only takes a few minutes, you just need to create a charge to receive a payment.

    Create a charge

    Use the Coinbase Commerce API to dynamically create charges. When you create a charge, we generate payment addresses on your behalf for each cryptocurrency that’s enabled and provide you with a hosted page you can send to customers to complete the payment. Here’s an example of dynamically creating a charge:

    curl -X POST https://api.commerce.coinbase.com/charges/ \
    -H "Content-Type: application/json" \
    -H "X-CC-Api-Key: YOUR_API_KEY" \
    -H "X-CC-Version: 2018-03-22" \
    -d "@data.json"
    


    Where data.json is simply a JSON object:

    {
      "name":"The Human Fund",
      "description":"Money For People",
      "pricing_type":"no_price"
    }
    


    A charge object is returned with payment addresses for each currency as well as a URL to a hosted page where a customer can complete their payment. Since we didn’t specify a price in our example, the customer is able to send any amount.

    Receive a payment

    Unlike credit cards where merchants must obtain payment credentials in order to charge a customer, cryptocurrencies are more like digital cash and rely on the customer explicitly sending money to the merchant.

    After creating a charge, Coinbase Commerce will continuously monitor each blockchain network for a payment. Since cryptocurrencies are push payments, we set an expiration time for the charge which is currently 1 hour after the creation date. If the customer does not make a payment within that timeframe, we consider the charge to be expired.

    Once a payment has been sent, we will update your Dashboard with the payment information. To get more information about the payment, simply retrieve the charge by supplying the unique charge code that was returned when the charge was created. Here’s an example of retrieving a charge:

    curl https://api.commerce.coinbase.com/charges/2E8YCQWQ \
    -H "X-CC-Version: 2018-03-22"
    


    A charge object is returned with specific information about the payment including, but not limited to, the transaction hash and the number of confirmations that have been received. Learn more

    Not a developer?

    It’s easy to accept cryptocurrency payments with Coinbase Commerce even if you’re not a developer.

    Embed payment buttons

    Payment buttons allow you to accept cryptocurrency on your website with minimal coding and users never need to leave your site to make a payment. Learn more

    Create hosted pages

    Hosted pages are publicly accessible checkout pages that can be shared with anyone. Hosted pages are a serverless solution for accepting cryptocurrency payments.

    Get started with Shopify

    If you have a Shopify store, you can get started accepting payments right away by adding Coinbase Commerce as an alternative payment method from within Shopify. Learn more

    Use a shopping cart plugin

    Soon you’ll be able to accept cryptocurrency using one of our shopping cart plugins. Integration with a shopping cart plugin is simple and doesn’t require any custom integration.

    Guides

    Payment buttons

    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.

    Accept payments button

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

    Checkout options

    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 snippet

    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 https://localhost:8000 as a whitelisted domain by taking the steps mentioned earlier.

    Whitelist localhost

    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:

    <div>
      <a class="donate-with-crypto"
         href="https://commerce.coinbase.com/checkout/6da189f179bc31">
        <span>Donate with Crypto</span>
      </a>
      <script src="https://commerce.coinbase.com/v1/checkout.js">
      </script>
    </div>
    


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

    $ python -m SimpleHTTPServer
    


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

    Donate with Crypto button

    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:

    Initialization

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

    <script src="https://commerce.coinbase.com/v1/checkout.js?onload=SOME_CALLBACK_FUNCTION"/>
    

    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.

    Metadata

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

    <div>
      <a class="buy-with-crypto" data-custom="MY_CUSTOM_DATA" href="https://commerce.coinbase.com/checkout/6da189f179bc31">
        <span>This is a button.</span>
      </a>
      <script src="https://commerce.coinbase.com/v1/checkout.js"></script>
    </div>
    

    Caching

    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:

     <div>
       <a class="buy-with-crypto" data-cache-disabled="true" href="https://commerce.coinbase.com/checkout/6da189f179bc31">
         <span>This is a button.</span>
       </a>
       <script src="https://commerce.coinbase.com/v1/checkout.js"></script>
     </div>
    

    Using React

    The embeddable button is also available as a React component.

    Usage and Installation

    First, whitelist your website and create a checkout with the API. Once your checkout has been created, keep track of the ID that was returned.

    The component can be installed using Yarn or NPM:

    npm i -S react-coinbase-commerce
    # OR
    yarn add react-coinbase-commerce
    

    Next, import the component and its corresponding CSS. Finally, add your checkout ID:

    import CoinbaseCommerceButton from 'react-coinbase-commerce';
    import 'react-coinbase-commerce/dist/coinbase-commerce-button.css';
    
    const App = () => {
      return (
        <CoinbaseCommerceButton checkoutId={'My checkout ID'}/>
      )
    };
    

    Props

    The CoinbaseCommerceButton component passes any extra props to its underlying button component, but also accepts a few custom props:

    Prop Name default required type
    styled false no boolean
    checkoutId nil If no chargeId, yes string
    chargeId nil If no checkoutId, yes string
    onLoad nil no ()=>void
    onChargeSuccess nil no (MessageData)=>void
    onChargeFailure nil no (MessageData)=>void
    onPaymentDetected nil no (MessageData)=>void
    onModalClosed nil no ()=>void
    disableCaching false no boolean
    customMetadata nil no string

    Warning: If disableCaching is set to true, users that accidentally close their payment windows will be unable to see their transaction's status upon reopening.

    Message Data

    type MessageData = {
      event: 'charge_confirmed' | 'charge_failed' | 'payment_detected',
      code: <CHARGE_CODE>
    }
    

    Using Shopify

    Accept multiple cryptocurrencies on your Shopify store with Coinbase Commerce within just a few minutes.

    Signup for Coinbase Commerce

    Sign up for a Coinbase Commerce account and follow the instructions to get started. After verifying your email address, adding two-factor authentication, and securely storing your recovery phrase, you’re ready to start accepting cryptocurrency payments.

    Create a Coinbase Commerce API Key

    First navigate to your Settings page which can be accessed using the left hand navigation menu:

    Dashboard settings

    Within Settings you’ll find an API Keys section. Click on Create an API Key to create a new API key that will be used to connect your Shopify store to your Coinbase Commerce account:

    Api keys

    Click Reveal to see the entire API Key but remember to keep this secret as it gives programmatic access to your account!

    Add Coinbase Commerce in Shopify

    To start accepting multiple cryptocurrencies using Coinbase Commerce first go to Settings and select Payment providers from within Shopify.

    Shopify payment

    Under Alternative payments select Coinbase Commerce.

    Shopify coinbase

    Under Email enter the email address used to create your Coinbase Commerce account and for API Key copy and paste the API Key created earlier within Coinbase Commerce.

    Shopify final

    Click Save to finish! Your customers are now able to checkout and pay with Bitcoin, Bitcoin Cash, Ethereum or Litecoin.

    Webhooks

    Webhooks allow you to monitor for updates to charges associated with your account. You might use webhooks to update a database record when a payment succeeds or to email a customer when a payment has been confirmed.

    Coinbase Commerce will send webhook events whenever a charge is created, confirmed or fails. Take a look at our API docs to learn more about our implementation.

    Creating a webhook

    Subscribe to webhook notifications by adding an endpoint to the Webhook subscriptions section on your Settings page within Coinbase Commerce. Click Add an endpoint to add the URL where you’d like to receive webhooks.

    You’ll be prompted to enter the endpoint URL (https only) where you’d like to receive webhooks. You can choose to be notified of all events or just a subset of events that you care about.

    Receiving webhook notifications

    Coinbase Commerce will validate that the connection to your service is secure before sending your webhook data. For this to work, your server must be correctly configured to support https.

    Responding to a webhook

    Your endpoint should respond with a 200 HTTP status code to acknowledge receipt of a webhook. If there is no acknowledgement of receipt, we will retry with an exponential backoff for up to three days. The maximum retry interval is 1 hour.

    Checking signatures

    Coinbase Commerce signs every webhook event it sends to your endpoints. The signature is included as a X-CC-Webhook-Signature header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret in settings. Always make sure that you verify the webhook signature before acting on it inside your system.

    Integrations

    Shopify

    If you have a Shopify store, you can get started accepting payments right away by adding Coinbase Commerce as an alternative payment method from within Shopify.
    Learn more

    WooCommerce

    A WooCommerce payment gateway that allows your customers to pay with cryptocurrency via Coinbase Commerce.
    Learn More

    PrestaShop

    A PrestaShop payment module that allows you to receive payments in cryptocurrency via Coinbase Commerce, hosted on Github.

    Magento

    Accept Cryptocurrencies on your Magento 2 store with Coinbase Commerce, hosted on Github.

    OpenCart

    Accept Cryptocurrencies on your OpenCart store with Coinbase Commerce, hosted on Github.

    Zen Cart

    Accept Cryptocurrencies on your Zen Cart store with Coinbase Commerce, hosted on Github.

    Drupal

    Integrate Coinbase Commerce into your Drupal site, hosted on Github.

    osCommerce

    Accept Cryptocurrencies on your osCommerce store with Coinbase Commerce, hosted on Github.

    WHMCS

    Accept Cryptocurrencies on WHMCS with Coinbase Commerce, hosted on Github.

    Spree

    Accept Cryptocurrencies on your Spree store with Coinbase Commerce, hosted on Github.

    X-Cart

    Accept Cryptocurrencies on X-Cart with Coinbase Commerce, hosted on Github.

    Gravity Forms

    Accept Cryptocurrencies on Wordpress using Coinbase Commerce's Gravity Forms integration, hosted on Github.

    Libraries

    Python

    Available on PyPI through pip and easy_install:

    pip install coinbase-commerce
    
    or
    
    easy_install coinbase-commerce
    


    Check out the source code and more detailed documentation on Github.

    Node.js

    Available on npm:

    npm install coinbase-commerce-node
    


    Check out the source code and more detailed documentation on Github.

    Ruby

    Available as a gem:

    gem install coinbase_commerce
    


    Check out the source code and more detailed documentation on Github.

    PHP

    Available via composer:

    composer require coinbase/coinbase-commerce
    


    Check out the source code and more detailed documentation on Github.

    SDKs

    Android

    Coming soon!

    IOS

    Coming soon!

    Unity

    Coming soon!