Announcing the New BitPay API

We're excited to announce BitPay's new cryptographically-secure API, a RESTful service utilizing our previously announced authentication protocol, BitAuth. We've eliminated the shared secret and implemented capability-based security, allowing for a much more powerful and simultaneously secure interface to interact with the BitPay API.


Refund API

Before we get too far into the details, our biggest news – the new BitPay API implements refunds, issued to any Bitcoin address. You can now create a refund request by issuing a POST request to /invoices/:id/refunds, which will initiate the supporting process for validating the refund request.

We utilize the Bitcoin Payment Protocol to determine the Bitcoin address to send the refund to. This means our refund capability works with any bitcoin address, meaning it is compatible with all bitcoin wallets. Shoppers never need a BitPay account to make a purchase at a BitPay merchant, or to receive a refund from a BitPay merchant.

This will allow all of our customers to initiate the refund process from within their applications, which we hope will lead to more smooth Bitcoin payment experiences for everyone, regardless of platform or wallet.

Billing API

You can now automate the submission of Bitcoin Bills using the BitPay API. Submit a POST request to /bills with the amount and the recipient, and they will receive an email request for payment. This allows BitPay merchants to request future payments, as opposed to Invoices which are a request for an immediate payment.

For documentation on both the Refund and Billing API, visit our API documentation.

API Documentation »

Capability-Based API Access

Instead of mechanisms such as OAuth or role-based security, our new API implements capability-based access control, as pioneered by Mark Miller, with his work on ERights. In addition to your cryptographic signature (which provides your authentication), you will provide a "token", which describes the resource you are attempting to interact with, in addition to the capabilities you are attempting to claim. This allows our servers to validate the intent of each and every request.

Tokens are constructed per resource and per capability – you will receive a new token when creating new documents, which can then be used to interact with that document in a scope limited to the operations the creator was authorized to perform. Tokens can be created with additional restrictions, and then utilized within your application to suit your own security needs – independent of BitPay.

For more details on the new token assignment scheme, see the API authorization documentation.


Doing Away with Shared Secrets

Our primary goal with this new API implementation was to cryptographically secure interactions with BitPay, whether they be the processing of payments or updating of account information. Ideally, this security would be independent of that of SSL/TLS – that is, even if SSL were to be compromised, API requests could still be secured.

To this end, we'll be using the same cryptographic security that Bitcoin itself uses, requiring all requests made to our API to be signed with the private key from your BitAuth keypair – as mapped to the secp256k1 elliptic curve. We match these signatures against a number of other parameters to make absolutely certain that the request we received came from you, and only you. You can take a look at our auth documentation for more details.

Tokens can be restricted to an identity, requiring a signature by that identity to utilize, or even a list of identities – perhaps a group of devices (such as point of sale tablets) or a list of people and their keys. Tokens have the flexibility of being restricted in other ways, as they can conceivably be constructed without BitPay, if signed by their creator.

Here's an example of what it looks like to create an Invoice with our new API (using the Node.js library):

var bitpay  = require('bitpay');  
var privkey = fs.readFileSync('path/to/private.key');  
var client  = bitpay.createClient(privkey);

client.on('ready', function() {  
  client.post('invoices', {
    amount: 1.99,
    currency: 'USD'
  }, function(err, invoice) {
    console.log(err || invoice);
  });
});

We've gone ahead and updated our open-source client libraries to provide these signatures automatically, so if you're using our tools you'll already have access to the most secure API in the Bitcoin ecosystem. If you're using a standard REST client, these new parameters are readily passed via HTTP headers and should be easily implemented by referring to our auth documentation.

Familiar REST Interface

Interacting with the new BitPay API should feel very familiar, and should exhibit extremely predictable behavior – like most other APIs on the modern web, we're modeling our API on Roy Fielding's REST architecture to reduce the complexity over other models.

We're expanding the number of resources available in our API, but not at the cost of increasing complexity—we're making everything available using familiar REST principles, with each resource uniquely identified in its collection by a single resource identifier (an URI) and interactable via standard HTTP verbs, GET, POST, PUT, and DELETE.

We're taking it one step further and offering responses to OPTIONS requests, which will always provide the latest documentation for the URI you are requesting information about. We will be implementing HEAD to check for the existence of objects, and PATCH for partial updates (such as only modifying one field on a document).

Versioning & Support

With a growing number of enterprise customers, we've made the decision to implement versioning in our API. We've chosen to stick with semantic versioning, to be supplied in the X-Accept-Version header – as of this post, 2.0.0 is available for consumption. This allows us to continue to iterate and add new features to this API, without breaking existing implementations.

Action Idempotence

Most API calls made are completely idempotent, and will always return the same result. This means that for complex, multi-step operations, you can replay the entire sequence of calls and not trigger any duplicate events.

For traditionally non-idemptotent events such as document creation (POST), or document modification (PATCH) – we provide idempotence through the guid parameter, supplied by the client, and server-enforced to be unique per identity.

[1]: "safe" operations can be guaranteed to not ever be cached by middleware, such as routers or HTTP proxies.
[2]: feedback on these methods wanted! Reach out to us in the BitPay API chat or send us an email.

Open Source

Our new API is built on top of Bitcore, our open-source Javascript library for doing all things related to Bitcoin and Bitcoin's cryptography. Contributors to Bitcore have built a number of projects on this shared technology, and we encourage others to take advantage of this get started on their own projects.

Similarly, we've also open-sourced BitAuth, the authentication layer for our new API, to allow others to integrate it into their own systems.

Take a look at BitPay on GitHub to see how you can participate in our open-source community, with forks of and pull requests to all of our open source projects completely welcomed and encouraged.

Getting Started

Getting started is extremely easy, as we're shipping this new API with several libraries for various languages:

We will be providing updates to our other existing libraries & Bitcoin eCommerce plugins to provide support for the new BitPay API over the coming months.

As always, please feel free to send us your feedback and thoughts via email or on Twitter, @BitPay.

Thanks for being part of our community! We look forward to seeing what you build.

Get the latest updates to your inbox