Recurring Payments

Handle subscriptions and recurring billing

Subscribe With Bitcoin

Sample embed code:

<a class="coinbase-button" data-code="f08179f52b978c662531a285395185f2" data-button-style="subscription_large" href="https://www.coinbase.com/checkouts/f08179f52b978c662531a285395185f2">Subscribe With Bitcoin</a>
<script src="https://www.coinbase.com/assets/button.js" type="text/javascript"></script>

Any bitcoin sent using the sample button will be donated to the Bitcoin Foundation.

Description

Recurring payments work well for services that require multiple payments over time. For example:

  • Software as a service
  • Monthly rent or electricity bills
  • Magazines, newspapers, or other publications
  • Service industries

Some examples might include web hosting, ride sharing, dating websites, collecting rent, maid services, gym memberships, or any subscription product.

By default bitcoin is a push technology, meaning each payment has to be initiated by the customer. Coinbase offers recurring payments in bitcoin (a pull technology) that customers can initiate. Unlike our other merchant tools, recurring payments require the customer to pay with a Coinbase wallet, since this is a layer we provide on top of the bitcoin protocol.

Recurring payments are a common use case in the world of credit cards because it creates fewer manual steps and late payments. Along with our two-click checkout process, Coinbase’s recurring payment integration brings the same benefits to bitcoin.

Customers retain the right to pause or cancel recurring payments at any time from their Coinbase account, and do not need to contact merchants to cancel. This provides a greater level of accountability and also prevents prices from being raised without the customer’s permission (unlike with a credit card).

Callbacks

In addition to regular callbacks received when a payment completes, recurring payments have their own callbacks that let you know the status of a customer’s subscription.

These callbacks can be idenfied by the presence of the recurring_payment parameter at the root level.

The status field in the callback can have one of three possible values: active, paused, or canceled. Here is a description of each:

status description
active This means either a new recurring payment was created by the customer or a paused recurring payment was re-enabled by the customer.
paused This means there was a problem with the customer’s payment (such as insufficient funds being available) and the scheduled payment did not arrive. When this happens we contact the customer to provide instructions for them to resolve it. You can also use this event to send your own notices.
canceled The customer has canceled their subscription. This is also sent if the recurring payment has been in the paused state for 3 or more weeks.

Here is a sample callback:

    {
      "recurring_payment": {
        "id": "518c8e8bf8182b0b26000008",
        "created_at": "2013-05-09T23:07:07-07:00",
        "status": "active",
        "custom": "ORDER1234",
        "button": {
          "type": "subscription",
          "name": "Recurring donation to the Bitcoin Foundation",
          "description": "",
          "id": "ec4fb9f25123690def6c545a697e470d"
        }
      }
    }

The status field is the only field that will change on most requests.

The custom param works the same as with all payment buttons and holds any custom value that you passed in when the first payment was made. This is typically a user or order ID that you can use to update your records.

The id param of the button corresponds to the data-code attribute in your embed HTML. Embed html for recurring payment/subscription buttons can be generated from the button generator or via the Coinbase API.