• Quickstart
  • Guides
  • Integrations
  • Libraries
  • 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.


    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.

    Cryptocurrency Payments

    Payments today rely on customers populating forms with credit card information. This information is then used to pull payments directly from the customer. Cryptocurrencies are different. Instead, a wallet is used to push payments directly to the merchant. A customer specifies the amount of cryptocurrency along with an address before sending funds. In this way, cryptocurrency payments are push payments.

    When a customer requests to pay with cryptocurrency, we create a charge representing the expected payment. A charge can be thought of as a request for payment in one or more cryptocurrencies. Since cryptocurrency payments are made over a separate network, a unique payment address per cryptocurrency is generated on charge creation so we can associate customers to their payments. When a customer makes a cryptocurrency payment, they generate a transaction that is then broadcast to the cryptocurrency network for validation/confirmation.

    Once a charge is created we start monitoring these unique addresses on the respective networks to detect any inbound payments. Each charge has an associated payment status.

    When we detect the customer’s transaction on the blockchain, the payment status changes to Pending. This means the payment has been detected but it has not yet been validated by the network. When the transaction is fully validated and confirmed by the blockchain network, the payment status changes to Completed. These unique payment addresses are monitored for up to 60 minutes. If no payment is detected after 60 minutes then the payment status changes to Expired.

    In some cases, a customer may make a payment after the 60 minutes has passed. In this case the payment status changes to Unresolved with a reason of Delayed.

    In other cases a customer may overpay, underpay, or pay more than once. When this happens the payment status changes to Unresolved with reasons Overpaid, Underpaid, or Multiple respectively. The Unresolved payment status can be manually updated to Resolved by the merchant to indicate that the payment issue has been resolved.

    Payment Statuses

    A list of all payment statuses can be found below:

    Payment Status Description
    New The payment has been created
    Pending The transaction has been detected
    Completed The transaction has been confirmed by the blockchain network
    Expired The payment request has expired (requests expire after 60 minutes if no payment has been detected)
    Unresolved The transaction has been confirmed but the payment diverged from what was expected
    Unresolved (Underpaid) The amount received was less than the amount requested
    Unresolved (Overpaid) The amount received was more than the amount requested
    Unresolved (Delayed) The amount received arrived after the payment request expired
    Unresolved (Multiple) Multiple payments were made to the same address
    Unresolved (Other) The transaction is of an unknown type
    Resolved The merchant has marked the payment as resolved
    Cancelled The request has been cancelled. Only new charges can be cancelled. Once a payment has been detected a charge cannot be cancelled.
    Pending Refund A refund has been initiated for this charge. Once a payment has been refunded it cannot be undone.
    Refunded A refund has been broadcasted and confirmed by the blockchain network

    Here's a visual representation of how all this works:

    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",

    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.


    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:

    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="https://commerce.coinbase.com/v1/checkout.js">

    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.

    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:


    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.


    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="https://commerce.coinbase.com/checkout/6da189f179bc31">
        <span>This is a button.</span>
      <script src="https://commerce.coinbase.com/v1/checkout.js"></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="https://commerce.coinbase.com/checkout/6da189f179bc31">
         <span>This is a button.</span>
       <script src="https://commerce.coinbase.com/v1/checkout.js"></script>

    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'}/>


    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:

    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:

    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.

    Under Alternative payments select Coinbase Commerce.

    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.

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


    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.



    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


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



    Available on PyPI through pip and easy_install:

    pip install coinbase-commerce
    easy_install coinbase-commerce

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


    Available on npm:

    npm install coinbase-commerce-node

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


    Available as a gem:

    gem install coinbase_commerce

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


    Available via composer:

    composer require coinbase/coinbase-commerce

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