API & SDK Documentation

Node Full SDK (version < 5.0.0)

BitPay NodeJS client

This SDK provides a convenient abstraction of BitPay's cryptographically-secure API and allows payment gateway developers to focus on payment flow/e-commerce integration rather than on the specific details of client-server interaction using the API. This SDK optionally provides the flexibility for developers to have control over important details, including the handling of private keys needed for client-server communication.

It also implements BitPay's remote client authentication and authorization strategy. No private or shared-secret information is ever transmitted over the wire.

Dependencies

You must have a BitPay merchant account to use this SDK. It's free to sign-up for a BitPay merchant account.

If you need a test account, please visit https://test.bitpay.com/dashboard/signup and register for a BitPay merchant test account. Please fill in all questions, so you get a fully working test account.
If you are looking for a testnet bitcoin wallet to test with, please visit https://bitpay.com/wallet and
create a new wallet.
If you need testnet bitcoin please visit a testnet faucet, e.g. https://testnet.coinfaucet.eu/en/ or http://tpfaucet.appspot.com/

For more information about testing, please see Testing

Handling your client private key

Each client paired with the BitPay server requires a ECDSA key. This key provides the security mechanism for all client interaction with the BitPay server. The public key is used to derive the specific client identity that is displayed on your BitPay dashboard. The public key is also used for securely signing all API requests from the client. See the BitPay API for more information.

The private key should be stored in the client environment such that it cannot be compromised. If your private key is compromised you should revoke the compromised client identity from the BitPay server and re-pair your client, see the API tokens for more information.

Here is how to generate the configuration file and private key:

  • Using the BitPaySetup Script helps to generate the private key, as well as a environment file formatted in JSON which contains all configuration requirements, that should be stored in the client local file system. It is not recommended to transmit the private key over any public or unsecure networks.

1. Commands to run setup script when using BitPay as NPM package:

You need to navigate to

node_modules/bitpay-sdk/dist/setup

and run the script using

node BitPaySetup.js

or you can enter the following command

node node_modules/bitpay-sdk/dist/setup/BitPaySetup.js

2. Commands to run setup script when using BitPay as a SDK:

First run the following command to generate the dist folder

npm run build

After running following command there will be a dist folder generated. You need to navigate to

dist/setup

and run the setup script using

node BitPaySetup.js

or you can directly run by

node dist/setup/BitPaySetup.js

Once the BitPaySetup Script has run and generated the Json correctly, read the console output and follow the instructions in order to pair your new tokens.
This method would also allow you to generate the Private Key as plain text which you can securely store in case you are using cloud services.

You can find the generated configs file here

node_modules/bitpay-sdk/dist/secure/

The environment file can be either generated by the BitPaySetup utility or created manually by copying the following Json structure:

{
  "BitPayConfiguration": {
    "Environment": "",
    "EnvConfig": {
      "Test": {
        "PrivateKeyPath": "",
        "PrivateKey": "",
        "ApiTokens": {
          "merchant": "",
          "payout": ""
        }
      },
      "Prod": {
        "PrivateKeyPath": "",
        "PrivateKey": "",
        "ApiTokens": {
          "merchant": "",
          "payout": ""
        }
      }
    }
  }
}

Usage

This library was built and tested using the Intellij IDE; the source code tree is directly compatible with Other NodeJS IDEs.
Library dependencies can be downloaded by executing the following command at the root of the library:

// Using YARN.

yarn add bitpay-sdk

// Using NPM

npm install bitpay-sdk

Getting Started

Initializing your BitPay client

Once you have the environment file (JSON previously generated) you can initialize the client on two different ways:

// Provide the full path to the env file which you have previously stored securely.

const {Client, Env, Currency, Models, Tokens} = require('bitpay-sdk');

let client = new Client(configFilePath);
        

// Initialize with separate variables.

const {Client, Env, Currency, Models, Tokens} = require('bitpay-sdk');

let tokens = Tokens;
tokens.merchant = 'AdsBgKAHzQTE8geuC3jg4TPivcbLsiic69SAsZSoKSWk';
let keyFilePath = __dirname+'/../secure/private_key_test.key';
let keyPlainText = 'ce2030a2ed82ac2b0337e8ee00943428949e78cd606b8b1af9e08be6cdb442fd';
let configFilePath = __dirname+'/../secure/BitPay.config.json';

let client = new Client(
    null,
    Env.Test,
    [FULL_PATH_TO_THE_PRIVATE_KEY_|OR|_PRIVATE_KEY_AS-PLAIN_TEXT],
    tokens
);

Pair your client with BitPay

Your client must be paired with the BitPay server. The pairing initializes authentication and authorization for your client to communicate with BitPay for your specific merchant account.

Pairing is accomplished by having the BitPaySetup utility request a pairing code from the BitPay server.
Meanwhile a new pairing code is generated, the BitPaySetup utility will ask you to activate it in your BitPay account. It will also store the paired token in the environment file.

The pairing code is then entered into the BitPay merchant dashboard for the desired merchant. Your interactive authentication at https://bitpay.com/login provides the authentication needed to create finalize the client-server pairing request.