developed with ❤️ by chainside

Introduction

This project is the official SDK library for the integration with the Chainside Pay Platform. It is an extension of the Sdk-boilerplate library.

Installation

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

pip install chainside-webpos-sdk 

In order to configure the redis cache backend, you must install the redis server and the python client. (For further information, check the https://redis.io/ documentation)

Installing redis server:

Apt:

apt install redis-server

Brew:

brew install redis

Then, to install the python client

pip install redis

Structure

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

Configuration

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:

http is a further configuration for the actual sending of requests. It can be configured by specifying the following parameters (if not specified, a default is provided)

A cache adapter can be configured aswell (if not, a default cache adapter is provided from the sdk). The configuration must define the following parameters:

Driver can be either 'redis', 'django' or the default 'dict'. If redis is configured as a driver, the options configuration parameters are the following:

For django or dict cache adapters, no further configuration is needed. If django is selected, the adapter wraps the django.core.cache cache singleton If dict is selected, (or the cache driver is not specified ), the sdk instantiates a DictCacheAdapter object which is a singleton in the application and uses a dictionary to store values.

Client

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.

Objects

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

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.

Usage

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

Instantiate and use the client

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

from webpos_sdk.client import Client
from webpos_sdk.objects import PaymentOrder
conf = {
        'mode' : 'live',
        'client_id' : '${webpos_client_id}',
        'secret' : '${webpos_secret}',
        ...
        }
client = Client(conf)
payment_order = PaymentOrder(
                                amount='10.00',
                                continue_url='https://continue.com',
                                ...
                            )
response = client.create_payment_order(payment_order)                            

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

Objects

PaymentOrderDeletionResponse

Payment order deletion response

Attributes

PaymentOrderRetrieval

Payment order retrieval data

Attributes

PaymentOrderState

Data describing the current state of a payment order

Attributes

PaidStatus

Cryto and fiat paid amounts

Attributes

PaymentOrderCreator

Data of payment order's creator

Attributes

DepositAccountLite

Deposit account lite object when sent nested in other api objects

Attributes

RateRetrieval

Rate Data

Attributes

Transaction

Bitcoin transaction paying a payment order

Attributes

Out

Transaction's output

Attributes

CurrencyRetrieval

Currency Data

Attributes

PaymentOrderList

List of Business' payment orders

Attributes

PaymentOrderCreation

Data required to create a new payment order

Attributes

PaymentOrderCreationResponse

Response data for a payment order creation request

Attributes

CallbackList

Callback list object

Attributes

Callback

Callback Retrieval object

Attributes

PaymentUpdateObject

Callback's trigger request body

Attributes

ClientCredentials

Data required to perform a confidential client login

Attributes

ClientCredentialsLoginResponse

Response data for a login performed by a confidential client.

Attributes

CallbackPaymentOrder

Payment order retrieval data

Attributes

Exceptions

Every exception raised due to an error response contains debug informations.

from webpos_sdk.exceptions import SdkHttpException

try:
    client.create_payment_order(payment)
except SdkHttpException as e:
    print(e.debug_info)
    print(e.request_id)

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.

Callbacks

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:

from webpos_sdk.callbacks.handler import ChainsideCallbacksHandler
from webpos_sdk.api_context import ChainsideApiContext

conf = {
        'mode' : 'live',
        'client_id' : '${webpos_client_id}',
        'secret' : '${webpos_secret}',
        ...
        }
context = ChainsideApiContext(conf)
handler = ChainsideCallbacksHandler(context)
callback_sdk_object = handler.parse(request.headers, request.body) 
# The request body should be the raw body ( in bytes ) of the request since it's used to compute the signature

Callback structure

Triggered events

Changelog

2.0.0 : 
    - Add request_id and debug_info to raised exceptions
    - Add pagination to payment order retrieval method
    - Replace the payment orders retrieval endpoint 

Contributing

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.

Security Issues

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