• Quickstart
  • Guides
  • 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 15 minutes 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.

    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.