developed with ❤️ by chainside

This project is the official SDK library for the integration with the Chainside Pay Platform. It requires jdk1.7 or higher.

Follow these steps to install the SDK library into your system:

Follow these steps to install the SDK library into your system. You can install it either using the maven-dependency-plugin, configuring the pom.xml or configuring the gradle.build (for gradle users)

With Maven plugin:

mvn org.apache.maven.plugins:maven-dependency-plugin:2.1:get 
-Dartifact=net.chainside.webpossdk:webpos-sdk-java:1.4.2 
-DrepoUrl=http://central.maven.org/maven2/

In pom.xml:

<dependency>
            <groupId>net.chainside.webpossdk</groupId>
            <artifactId>webpos-sdk-java</artifactId>
            <version>1.4.2</version>
</dependency>

In gradle.build:

compile 'net.chainside.webpossdk:webpos-sdk-java:1.4.2'

If you are experiencing protocol errors during the download, you might need to upgrade the TLS version used from the dependency manager. Depending on the jdk1.7 version used, you might need to enable TLSv1.2 protocol to download dependencies. This can be achieved by passing -Dhttps.protocols=TLSv1.2 to the chosen package manager command

The following sections will describe the high level structure of the SDK library.

In order to be able to configure your SDK client you have to set some configuration parameters. Here is the list of the configuration parameters used by the library:

If a proxy configuration is given, the requests are sent using the configured proxy. A proxy configuration must be specified as:

If the proxy server requires authentication, credentials must be specified in the proxy configuration parameters as:

Example:

import net.webpossdk.api.ChainsideClient;
import net.webpossdk.object.CallbackList;

HashMap<String, Object> config = new HashMap();
config.put("mode", "live");
config.put("clientId", WEBPOS_CLIENT_ID);
config.put("secret", WEBPOS_SECRET);
HashMap<String,String> credentials = new HashMap();
credentials.put("user", PROXY_USERNAME);    
credentials.put("password", PROXY_PWD);
HashMap<String,Object> proxyConfig =  new HashMap();
    proxyConfig.put("hostname", PROXY_HOSTNAME);
    proxyConfig.put("port", 8000);
    proxyConfig.put("protocol", "http");
    proxyConfig.put("credentials", credentials);

ChainsideClient client = new ChainsideClient(config); 

The Library exposes a client object which is instantiated with the system configuration and provides an high-level interface to send requests. Client's instances take care of compiling and sending http request and parse responses into SdkObject instances.

The library defines an SdkObject class which is extended by actual objects which represent Chainside-Pay API requests and response bodies. Every json object defined in the API has a corresponding SdkObject class which is either the input of a client instance method (for creation) or returned (for reading)

Callbacks are requests sent by the server to your application in order to notify about some events. Every callback is sent only to HTTPS webhooks and will be securely signed by the server in order to be verified.

The following sections will describe how to use the SDK library and all the detail needed to integrate your business with Chainside Pay.

In order to communicate with our backend first you need to instantiate the client:

import net.webpossdk.api.ChainsideClient;
import net.webpossdk.object.CallbackList;

HashMap<String, Object> config = new HashMap<>();
config.put("mode", "live");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

PaymentOrderCreation paymentOrder = new PaymentOrderCreation();
paymentOrder.setAmount("10.00");
paymentOrder.setReference("#1");
paymentOrder.setDetails("#1 details");
paymentOrder.setRequiredConfirmations(3);
PaymentOrderCreationResponse resp = client.createPaymentOrder(paymentOrder);

String btcAddress = resp.address // will output the payment order address
                        

Once the client is instantiated and configured, you can use the following methods to send requests:

Data required to perform a confidential client login

Response data for a login performed by a confidential client.

Payment order deletion response

Payment order retrieval data

Rate Data

Currency Data

Bitcoin transaction paying a payment order

Transaction's output

Data of payment order's creator

Deposit account lite object when sent nested in other api objects

Data describing the current state of a payment order

Cryto and fiat paid amounts

List of Business' payment orders

Data required to create a new payment order

Response data for a payment order creation request

Callback list object

Callback Retrieval object

Callback's trigger request body

Payment order retrieval data

Every exception raised due to Chainside error responses contains debug informations.

try{
    client.createPaymentOrder(paymentOrder)
}catch (ChainsideHttpExceptio e){
    System.out.println(e.getDebugInfo())
    System.out.println(e.getRequestId())
}

Debug Info contains general information about request and response headers, body and status code. Request Id is an internal id which can be communicated to chainside in order to help debugging the problem in case this cannot be identified.

Chainside will send callbacks if some event is triggered regarding one of your assets registered on the Business Panel. Our server will send a request to your webhooks that you need to parse and verify. You can do this using this SDK library in the following way:

HashMap<String, Object> config = new HashMap<>();
config.put("mode", "live");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

ChainsideApiContext ctx = new ChainsideApiContext(config);
ChainsideCallbackHandler handler = new ChainsideCallbackHandler(ctx);

/* Retrieve http request and raw body in as an array of bytes
HashMap<String, String> headers = request.getHeaders(); 
byte[] rawBody = request.getRawBody(); 
*/

SdkObject parsedObject = handler.parse(headers, rawBody);

1.4.0 : 
    - The library now contains the jdk1.7 compatible code. The api of the sdk remains the same.
1.4.1 : 
    - Satoshi amounts of payment objects primitive type changes from Integer to Long. 
      Setters are still compatible with integer as they convert the given value to a Long, while getters return type
      changes. This involves the following methods:
            - CallbackPaymentOrder getBtcAmount() 
            - PaymentOrderCreationResponse getAmount() 
            - PaymentOrderRetrieval getBtcAmount() 
            - Out getAmount() 
            - PaidStatus getCrypto()
            - Transaction getOutsSum()   

In order to maintain consistency between our backend and our SDKs, contributing through pull requests is highly discouraged. Consider posting an issue if you need to signal any problem with this library.

In case of a discovery of an actual or potential security issue please contact us at info@chainside.net