API & SDK Documentation

Java Full SDK (version < 9.0.0)

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.

📘

Note

For more details on the SDK internals, please see the JavaDoc at https://bitpay.github.io/java-bitpay-client/.

Dependencies

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

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 documentation 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 documentation for more information.

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 insecure networks.

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.

The environment file can be either generated by the BitPay.Net Setup 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 Java IDEs.

Initializing your BitPay client

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

Full path to the config file

Client bitpay = new Client("[FULL_PATH_TO_THE_CONFIG_FILE]", null);

Separate variables

Client bitpay = new Client(
    Env.Test,
    "[FULL_PATH_TO_THE_PRIVATE_KEY_|OR|_PRIVATE_KEY_AS-PLAIN_TEXT]",
    new Env.Tokens(){{
        merchant = "2smKkjA1ACPKWUGN7wUEEqdWi3rhXYhDX6AKgG4njKvj";
        payout = "9pJ7fzW1GGeuDQfj32aNATCDnyY6YAacVMcDrs7HHUNo";
    }},
    null
);

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 BitPay.Net Setup utility request a pairing code from the BitPay server.
Meanwhile a new pairing code is generated, the BitPay.Net Setup 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.