Pairing a client requires a SIN, or a 'Client id'. If you do not have or have not created a SIN, please follow the instructions in this article: Creating Private Keys, Public Keys, and SINs

In the following, it is assumed the merchant has already created a BitPay merchant account. If you haven't done this, then the first step would be to create a merchant account on https://bitpay.com/dashboard/signup.

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. The privileges of an API token are determined by the 'facade' associated. Facades determine 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 you register an Identity, you are registering against a specific facade. Best practices suggest that the requested facade should be limited to the minimum level that grants the required capabilities. The available facades are:

• public: The implicit facade applied when no token is provided. This facade provides access to public methods for generating merchant applications, generating and claiming tokens, or checking exchange rates.
• pos: Limited to creating new invoices 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 and ledger download, as well as the creation of new merchant or POS tokens associated with the account.

Pair your client with BitPay

Your client must be paired with the BitPay server in order to be able to created invoice, submit refund requests...The pairing initializes authentication and authorization for your client to communicate with BitPay for your specific merchant account.

Pairing is accomplished by having your client request an API token to the BitPay server. In order to request an API token, you need to send a POST request to bitpay.com/tokens with the following query parameters:

• label (e.g. My BitPay Client)
• facade (use the 'merchant' facade)
• SIN (e.g. Tf3wXWuwfT1TmenHF21P1nYZ7BeyrYNdiwo, a client IDs always starts with a 'T')

Developers may call the API directly over HTTPS using the language of their choice, or take advantage of one of BitPay's code libraries

The BitPay server will respond with a new token that will include a pairing code. Below is an example of a JSON object returned by the BitPay server with the pairing code in the payload.

{"data": 
 [{"policies": 
 [{"policy":"id", 
 "method":"inactive", 
 "params":["Tf3wXWuwfT1TmenHF21P1nYZ7BeyrYNdiwo"] 
 }], 
 "token":"DsyNv4xXMXguMyQAfPtkznyZ7T5SxnAyaZEwc8nGJuL5", 
 "facade":"merchant", 
 "label":"Some description...", 
 "dateCreated":1436986447652, 
 "pairingExpiration":1437072847652, 
 "pairingCode":"Wp4RRAz" 
 }] 
}

In order to validate the pairing code (in bold) and approve the client, visit the following URL format: bitpay.com/api-access-request?pairingCode=<pairingcode_goes_here>.

Note:

• The pairing step is only needed once.
• The token needs to be stored for usage in the future.
• Pairing codes will expire after 24 hours. However, once a token is approved or claimed, the expiration is cleared.