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 BitPay's code libraries (Java, C#, PHP, etc.)

API Contracts

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.

BitAuth uses the same technology in Bitcoin. A public private key pair is created using elliptic curve secp256k1. The public SIN (System identification number), like a bitcoin address, is the RIPEMD 160, SHA256 hash of the public key. See the Bitcoin Wiki for complete details:

In each request, the client signs the full url with the request body concatenated if there is one. The signature is included in the X-Signature header and the public key is included in the X-Identity header.
The server verifies that the signature is valid and that it matches the identity (the public key). It then computes the SIN from the public key, and sees whether that SIN has access to the requested resource.

For your convenience, all client libraries available on BitPay's GitHub account support this functionality.

API 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 grant access to collections of capabilities, such as the ability to create invoices or initiate 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.

Facade	Capabilities Description
`public`	The implicit facade applied when no token is provided. Provides access to public methods for generating merchant applications, generating and claiming tokens, or checking exchange rates.
`pos`	Limited to creating new invoice or bills and search specific invoices or bills based on their id for the merchant's organization
`merchant`	The broadest set of capabilities against a merchant organization. Allows for create, search, and view actions for Invoices and Bills; ledger download, as well as the creation of new merchant or pos tokens associated with the account. API calls using this facade must be cryptographically signed.
`payout`	This is the facade which allows merchant to access the Payouts related resources and corresponding endpoints. Access to this facade is not enabled by default, for more information please contact our support channel. API calls using this facade must be cryptographically signed.