What is a "unified" SDK?

📘
Note
This page is for the Java SDK version 9.0.0 or higher. Earlier versions had a slightly different client instantiation process. For version 8.x, please see the that version's client instantiation documentation.

We previously maintained two separate SDKs for each language. The "lite" SDKs only utilized the pos facade which does not require request signing. This made it much simpler to set up because consumers of the SDKs did not have to manage key pairs, but the lite SDKs were also limited in functionality. The "full" SDKs utilized the merchant and payout facades, which have more functionality, such as creating refunds, but were inherently more complex due to signed requests requiring the consumer to generate and manage private keys.

One of the major downsides for us was upkeep. Every dependency update or new feature that would affect both SDKs would require them both to be updated. We realized that this was an unnecessary complexity and that with the right architecture, we could create a single version of each SDK that could be set up to use any of the facades.

This new unified SDK supports everything the lite and full SDKs did, all in one package. This makes it easier for consumers to start with one facade and graduate to the more complex ones with little effort. On our side, it de-duplicates the work that's going into everything and allows us to focus on continuously improving the set of SDKs.

Setup

📘
Note
This setup is required for using the merchant and payout facades. You can skip this section if If you will only be using the pos facade.

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.

Generating a configuration and private key

Using the BitPay setup 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.

First, download an SDK ZIP from the GitHub releases page and unpack.

Next, run the setup script:

mvn compile exec:java@setup

Follow the on-screen prompts to generate your key and config file. 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.

You can find the generated config file and key (if you chose to create a key file) in output/.

Usage

There are two new methods of instantiation, which is the main part of existing applications that will need to be updated.

POS Facade

If you have only the need for a simple invoice creation flow, you may want to use the pos facade which, while limited in capability, is easier to get started with because you don't need to maintain private keys.

Prerequisites

You will need to create a Point-of-Sale token in the BitPay dashboard.

Initialization

import com.bitpay.sdk.Client;
import com.bitpay.sdk.PosToken;

Client bitpay = Client.createPosClient(new PosToken("posToken"), Environment.TEST);

Merchant/Payout Facades

In the case that you have a more complex flow that uses enhanced functionality such as refunds, you will want to use the merchant and/or payout facades.

Prerequisites

Copy the output from the setup script to a location on your system that your project can reach.

Initialization

import com.bitpay.sdk.Client;

Client bitpay = Client.createClientByConfigFilePath(
      new ConfigFilePath("/path/to/BitPay.config.json")
 );

import com.bitpay.sdk.Client;

Client bitpay = new Client(
	 BitPayClient bitPayClient,
        String identity,
        TokenContainer tokenContainer,
        GuidGenerator guidGenerator
);

Upgrade Notes

Outside of the client instantiation, there are other minor differences in the capitalization of package and field names, for example:

The com.bitpay.sdk.model.Invoice package is now com.bitpay.sdk.model.invoice. Classes have remained starting with an uppercase letter, so the models below it will be referenced as com.bitpay.sdk.model.invoice.Invoice.
Some fields have been renamed, such as how Invoice.setNotificationURL() is now Invoice.setNotificationUrl()

We feel that the consistency, readability, and standardization gained from these minor differences outweigh the backward compatibility, and don't add a tremendous amount of overhead to upgrading.