Technical FAQ

Coinbase’s Merchant Tools product will be retired on April 30th 2018. Learn more.









Which method should I use on my site to accept bitcoin?

  • Payment Page
  • Payment Button
  • Payment iFrame

All three of these integration options provide a great payment experience, and are best used in the following scenarios: - Payment Pages: - Use these if you want to have a fully-hosted payment solution - With this method, customers will be redirected to a page on our site to complete the payment process. - At its simplest, this method requires only a link to our website.

Example-okcupid-1 Select Bitcoin as your payment method
Example-okcupid-2 Payment details are provided by Coinbase
Example-okcupid-3 Complete payment

  • Payment Buttons:

    • Use these if you want to have a separate payment area available, while still having the customer stay on your website.
    • With this method, customers will stay on your site throughout the checkout process, but will have a separate payment modal.
    • This method requires embedded HTML.

Example-khan-academy-1 Click to donate
Example-khan-academy-2 Choose your donation amount
Example-khan-academy-3 Khan Academy receives your donation

  • Payment Iframes:
    • Use these if you want the customer to pay completely on your website, without having to navigate to a separate page/area.
    • With this method, customers will stay on your site throughout the checkout process and will not be shown a separate payment modal
    • This requires embedded HTML.

Example-cheapair-2 Select Bitcoin as your payment method
Example-cheapair-3 Use the Coinbase payment iframe to pay inline
Example-cheapair-4 Tickets purchased!

Do you have any client libraries available for X programming language?

To see the up to date list of official client libraries please visit our API documentation.


Which authentication methods can be used with the Coinbase API?

We offer two different methods for authentication API requests. These methods are:

  • API Key - Best for accessing your own account
  • OAuth2 - Best for accessing other users’ accounts

How do permissions work with API credentials?

When generating API credentials for an account, you will be given the option to select specific permissions. You should select permissions (scopes) listed for used API endpoint specified in the API reference.


How can I refund an order with the API?

To refund an order with the API, use the refund call. This call requires two parameters:

  • The order ID, which you’ll need to include in the request URL: POST<order_id>/refund
  • The refund currency, which can be either BTC or USD, included in the request body.

If BTC is selected, we will refund the original BTC payment amount. If USD is selected, we will refund an amount equivalent to the USD-denominated order amount.

The documentation for this API call, as well as more information about the required parameters, can be found in our full API reference here.


How is my website notified when an order is completed?

Coinbase offers a webhook notification system. If enabled, our system will notify your website when a customer completes or mispays their order. More information about these notifications can be found at the following documentation page here.

If you have the I receive merchant orders notification option selected on your settings page, we will also email you whenever a customer completes or mispays their order.

Settings_email Select email notification options.

How will my website be notified when my daily instant-exchange cashout is processed?

When your daily cashout is processed (usually around 2PM PST), our system will send your website a webhook notification with the transaction details.


I saw a mispayment on the orders page of my account. What does this mean?

A mispayment is an order payment that was received under abnormal circumstances. Two triggers will cause a mispayment to occur:

  • The customer’s payment was received after the 15-minute order timeout expired.
  • The customer’s payment was greater than or less than the actual order amount.

Mispayments can usually be handled by either refunding or fulfilling the customer’s order.

  • In the case of (1), where a payment was received after the timeout, many merchants choose to fulfil the order.
  • In the case of (2) - a mispayment triggered by an under/over-payment - it is often easiest to refund the customer’s order and have them create a new one.


How can I export transaction data from my Coinbase account?

Coinbase offers reports of your transactions for download.

Reports_request1 Go to reports page in settings
Reports_request2 Create a new report.
Reports_request3 Create a recurring reports in the advanced settings.

We request an email address during the report generation process. When the report has been generated, a download link will be sent to the provided address. Reports are delivered in CSV file format.

You may run reports on a recurring basis by selecting one of the repeating options. In that case, you’ll receive an e-mail with the download link at your chosen intervals.

You may also specify a callback URL to which a JSON string will be sent every time that Report is run. This report will contain a download link, allowing you to programatically retrieve the data. This JSON string will be identical to the response from the reports API endpoint, which allows you to generate a report through our API (currently only available on API v1).

There are several different reports that can be generated:

  • Transaction History: A list of transactions that belong to your account.

    Reports_transactions1 Transactions Report Example
    Reports_transactions2 Transactions Reports Example (continued)

  • Merchant Order History: A list of merchant orders that belong to your account.

    Reports_merchanthistory1 Merchant Order History Example
    Reports_merchanthistory2 Merchant Order History Example (continued)

  • Merchant Order Mispayments: A list of mispaid merchant orders on your account.

    Reports_mispayments Buys, Sells, and Merchant Payouts Example

  • Buys, Sells, and Merchant Payouts: A list of all transactions involving bank transfers.

    Reports_buys_sells Buys, Sells, and Merchant Payouts Example

    • Cost Basis for Taxes (BETA): A report that is helpful for determining the cost basis of your Bitcoin.
Reports_taxes1 Cost Basis for Taxes Example
Reports_taxes1 Cost Basis for Taxes Example (continued)

  • Merchant Payout Report

  • This report is a combination of the “Buys, sells, and Merchant Payouts” report, the “Merchant Order History” report, and the “Merchant Order Mispaymetns” report — but only for one payout.

    The Merchant Payout Report is generated automatically after every daily payout when you have both instant exchange and the payout report options enabled in your merchant settings.

    Every Merchant Payout Report generates an email notification to your primary email address, and also sends a callback to the callback url specified in your merchant settings if present.


    Why did I get a 401 Unauthorized response?

    If you received a 401 Unauthorized response on one of your requests, it is likely that an issue is present in your authentication parameters. Response error should also notify you of the underlying issue. Make sure that:

    • Your API key and secret is enabled (or your OAuth grant is not revoked)
    • The parameters were included in the correct place (e.g. in the request headers)
    • Make sure that the correct data was signed.

    If all of the above factors are normal, shoot us over an email at and we’ll be happy to take a look.

    What are all the possible response/error types generated by the API?

    All the available status codes and error types are listed in the API reference:

    Why aren’t redirect URLs working on my payment buttons/iframes?

    Redirect URLs will only be used for : payment pages hosted on

    These URLs will not be applied to buttons or iframes, as doing so would require unnecessarily invasive Javascript. If you need to apply redirection URLs to these, you can set up your own Javascript to listen for the coinbase_payment_complete Javascript event, and redirect your users when that fires. You can see an example of this in the Using Your Own Button And Custom Javascript Events section of our documentation.

    How do I receive notification data in PHP?

      $data = file_get_contents("php://input");

    Many PHP developers try to use the $_POST variable with Coinbase notifications, only to find they’re not getting any data. $_POST works only when the POSTer has specified a content type of application/x-www-form-urlencoded and multipart/form-data.

    Coinbase sends everything as application/json. php://input returns the entire body of the POST request regardless of content type.

    Why isn’t my AJAX request to the API working?

    Coinbase’s Access-Control-Allow-Origin won’t allow authenticated browser-based AJAX requests, even if you try to do so with JSONP.

    Browser extensions (such as Postman) are not necessarily subject to the same rules and may be able to do so.

    Getting Help

    Who can I contact if I need help with the API?

    Post a technical question in Stack Overflow with the Coinbase tag, or for private/sensitive inquiries, email our API support team at and we’ll be happy to help.