BitPay API

Overview

BitPay provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their BitPay account. Using the BitPay API, clients can create and manage invoices, issue refunds, manage bills, retrieve real-time rates information, view merchant ledger entries, and much more. Developers may call the API directly over HTTPS using the language of their choice, or take advantage of one of BitPay's Node.js, PHP, and Ruby API clients.

Concepts

API Contract

BitPay considers the following types of API changes to be non-breaking and backwards-compatible:

• exposing a new resource type
• adding a new method to an existing resource type
• adding an optional property to an existing resource type
• adding an optional query parameter to an existing resource method
• deprecating an existing resource method and providing an alternative

Identities

Authentication in BitPay's API utilizes a specialized identification scheme, BitAuth Identity Protocol. Every Identity is represented in public form as a Client ID, which much like the Bitcoin protocol, is simply a hash of the identity's public key. For your convenience, all of BitPay's Client Libraries support this functionality.

Tokens

Authorization in BitPay's API utilizes Capability-based Security principles. Each API call must be accompanied by an API Token which grants access to the requested capability. API Tokens are analagous to a real-world event ticket, which grants access to a specific event when presented at the door. Also like tickets, they may grant broad or narrow privileges (e.g. 'General Admission' vs. 'Seat 44B') as well as add bearer requirements (e.g. 'Must be over 21' or 'Non-transferrable, must show ID').

New tokens are provided with each response from the API. For example, creating a new Invoice with one token will provide a new, second token that grants access to view and interact with that Invoice exclusively. If not using BitPay's Client Libraries, you will need to keep track of these tokens on your own.

Facades

Facades named collections of capabilities that can be granted, such as the ability to create invoices or grant refunds. In the ticket analogy, this corresponds to the ticket 'level', where a 'VIP' ticket would confer broader access than a 'Standard' level ticket. When registering an Identity, it is against a specific facade. Best practices suggest that the requested facade should be limited to the minimum level that grants the required capabilities.

Getting Access

To use any non-public facade a token will need to be sent with the API request. Tokens can require authentication, which would requiring cryptographically signing each request. You can either generate a token directly from an API client or via the My Account -> API Tokens page. To receive a token directly from an API client, send a POST request to bitpay.com/tokens with the following query parameters:

• label (e.g. My BitPay Client)
• id (e.g. Tf3wXWuwfT1TmenHF21P1nYZ7BeyrYNdiwo)
• facade (e.g. merchant)

This will respond with a new token that will include a pairingCode. This pairing code can then be shared with a merchant organization administrator to approve access. This can be done by visiting My Account -> API Tokens and entering the pairing code, or by visiting the url format: bitpay.com/api-access-request?pairingCode=<pairingcode_goes_here>.

Alternatively, pairing codes can be generated directly at My Account -> API Tokens, and can then be claimed by API clients which associates a Client ID with the token, and will activate it for further usage. To claim a token from an API client, send a POST request to bitpay.com/tokens with the following parameters:

• label (e.g. My BitPay Client)
• id (e.g. Tf3wXWuwfT1TmenHF21P1nYZ7BeyrYNdiwo)
• pairingCode (e.g. As retrieved from My Account -> API Tokens)

A token without a Client ID authentication restriction can be made, and a token can then be copied directly to make API calls, such as creating invoices. It is also important to note that pairing codes will expire after 24 hours, however once a token is approved or claimed the expiration is cleared.

Making Requests

Requests to the BitPay REST API follow a RESTful convention using standard HTTP verbs against various BitPay resources to return JSON formatted responses. Once again the mechanics of this exchange may be simplified through the use of one of the BitPay libraries.

Each request should include in the HTTP headers:

• x-identity(the hexadecimal public key generated from the client private key)
• x-signature(header which is cryptographically computed as described below)
• content-type: application/json
• x-accept-version: 2.0.0

To make an API request send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of the following (plus any additional parameters needed):

• token(obtained during client registration process above)
• guid(an optional parameter to enforce idempotence for POST requests)

For more information about specific resource URIs, please visit the resource documentation.

Signing Your Request

The x-signature header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. So if you are sending a request to:

https://bitpay.com/invoices

And your request body is:

{"amount":500,"currency":"USD","token":"1234567"}

The string you will sign is:

https://bitpay.com/invoices{"amount":500,"currency":"USD","token":"1234567"}

The result should be included as the value of the x-signature request header.

Cross-Origin Resource Sharing

The BitPay REST API supports CORS, so that you may send requests directly from the client, however remember to never expose your private key. If your key becomes compromised, you will want to disable your old Client ID and register a new one.

API Sessions

API sessions are an optional feature of our API which can be utilized to provide even greater security and reliability. In particular it protects against replay attacks and ensures api requests are processed in the same order they are received.

An API session can be created by issuing a POST to /sessions. The server responds with a sessionId. The sessionId is used in each subsequent request along with a requestNumber. These fields, sessionId and requestNumber are included as parameters either in the URL for a GET or in the data body for POST and PUT.

On the first request, the requestNumber should be 1. Each additional request should increment the requestNumber by 1. If the server receives a request out of order it will return an error. If the client does not hear back from the server because of an interruption in network connectivity or some other problem, the client may retry by sending the same request with the same requestNumber. The server will then respond with a cached copy of the data if it had already serviced that request but was interrupted when delivering it to the client.

API sessions timeout after 15 minutes of inactivity. After 15 minutes, clients will get an error, and must create a new session. Clients can be programmed to handle creation of new sessions and timeouts automatically. Please see the Node.js client library for a working implementation.

References

Available Resources