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:

Parameter	Type	Required	Default	Description
mode	string	Yes	live	The SDK mode, can be sandbox or live
client_id	string	Yes	null	Your WebPos client id
secret	string	Yes	null	Your WebPos secret
http			Http further configuration

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)

Parameter	Type	Required	Default	Description
verify_ssl	string	No	true	Wheter to perform ssl verification
timeout	integer	No	10	Timeout on sent requests (seconds)

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:

Parameter	Type	Required	Default	Description
driver	string	No	dict	The cache driver to be used
options	dict	No	null	Cache driver further configuration

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

Parameter	Type	Required	Default	Description
hostname	string	No	localhost	Hostname of the redis server
port	integer	No	6379	Port of the redis server
password	string	No	null	Password to connect to the redis server
decode_responses	boolean	No	True	Wheter to return byte or decoded responses

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:

Method
delete_payment_order(payment_order_uuid:uuid) : PaymentOrderResponse
get_payment_order(payment_order_uuid:uuid) : PaymentOrderRetrieval
get_payment_orders(status:string=None,page:integer=None,sort_order:string=None,page_size:integer=None,sort_by:string=None) : PaymentOrderList
create_payment_order(payment_order:PaymentOrder) : PaymentOrderResponse
client_credentials_login(client_credentials:ClientCredentials) : ClientCredentialsLoginResponse
get_callbacks(payment_order_uuid:uuid) : CallbackList
payment_reset(payment_order_uuid:uuid) : PaymentOrderRetrieval
payment_update(payment_order_uuid:uuid,payment_update_object:PaymentUpdateObject) : None

Objects

PaymentOrderDeletionResponse

Payment order deletion response

Attributes

Attribute	Type	Required	Description
cancel_url	string	Yes	The URL where the user is redirected upon payment order expiration/cancellation

PaymentOrderRetrieval

Payment order retrieval data

Attributes

Attribute	Type	Required	Description
expires_in	integer	Yes	Expiration time of the payment order
btc_amount	integer	Yes	Bitcoin amount of the payment order
resolved_at	string	Yes	Time at which either the payment order has been fully paid or is expired
state	PaymentOrderState	Yes	Current payment state of the payment order
required_confirmations	integer	Yes	Required confirmations for transactions paying the payment order
transactions	[Transaction]	Yes	Transactions paying the payment order
address	string	Yes	Bitcoin address of the payment order
redirect_url	string	No	URL where to redirect the user to perform the payment
rate	RateRetrieval	Yes	Crypto/Fiat rate of the payment order
chargeback_date	string	Yes	Time at which either the payment order has been fully paid or is expired
created_at	string	Yes	Creation date of the payment order
expiration_time	string	Yes	Expiration date of the payment order
currency	CurrencyRetrieval	Yes	Fiat currency of the payment order
amount	string	Yes	Fiat's amount of the payment order
created_by	PaymentOrderCreator	Yes	Data of the pos which created the payment order
details	string	No	Payment order's details
uuid	string	Yes	UUID of the payment order
uri	string	Yes	Bitcoin uri
callback_url	string	No	The URL contacted to send callbacks related to payment status changes
dispute_start_date	string	Yes	Time at which either the payment order has been fully paid or is expired
reference	string	Yes	Business' reference for the payment order

PaymentOrderState

Data describing the current state of a payment order

Attributes

Attribute	Type	Required	Description
paid	PaidStatus	Yes	Payment order's paid amount
in_confirmation	PaidStatus	Yes	Payment order's paid but unconfirmed amount
unpaid	PaidStatus	Yes	Payment order's unpaid amount
blockchain_status	string	Yes	Payment order's internal status
status	string	Yes	Payment order's status

PaidStatus

Cryto and fiat paid amounts

Attributes

Attribute	Type	Required	Description
crypto	integer	Yes	Cryto Amount
fiat	string	Yes	Fiat Amount

Transaction

Bitcoin transaction paying a payment order

Attributes

Attribute	Type	Required	Description
txid	string	Yes	Transaction's id
normalized_txid	string	Yes	Transaction's normalized id (DEPRECATED)
blockchain_status	string	Yes	Transaction's internal status
outs_sum	integer	Yes	Paying amount of the transaction
status	string	Yes	Transaction's status
created_at	string	Yes
outs	[Out]	Yes	Transaction's outputs

Out

Transaction's output

Attributes

Attribute	Type	Required	Description
n	integer	Yes	Transaction output's index
amount	integer	Yes	Output's amount

RateRetrieval

Rate Data

Attributes

Attribute	Type	Required	Description
from	string	No	Starting currency for rate calculation
to	string	No	Target currency for rate calculation
source	string	Yes	Exchange providing the rate
value	string	Yes	Value of the rate
created_at	string	Yes	Creation's date of the rate

CurrencyRetrieval

Currency Data

Attributes

Attribute	Type	Required	Description
type	string	Yes	Currency's type (fiat/crypto)
uuid	string	Yes	UUID of the currency
name	string	Yes	Name of the currency

PaymentOrderCreator

Data of payment order's creator

Attributes

Attribute	Type	Required	Description
type	string	Yes	Payment order creator's type
active	bool	No	Wheter the creator active
uuid	string	Yes	Payment order creator's uuid
name	string	Yes	Payment order creator's name
deposit_account	DepositAccountLite	Yes	Deposit account associated to the payment order's creator

DepositAccountLite

Deposit account lite object when sent nested in other api objects

Attributes

Attribute	Type	Required	Description
type	string	Yes	Deposit account's type
uuid	string	Yes	Deposit account's uuid
name	string	Yes	Deposit account's name

PaymentOrderList

List of Business' payment orders

Attributes

Attribute	Type	Required	Description
total_pages	integer	Yes	Total number of pages given the requested page size
paymentorders	[PaymentOrderRetrieval]	Yes	Business' payment orders
total_items	integer	Yes	Total number of items

PaymentOrderCreation

Data required to create a new payment order

Attributes

Attribute	Type	Required	Description
continue_url	string	No	The URL where the user is redirected upon successful payment
callback_url	string	No	The URL contacted to send callbacks related to payment status changes
details	string	No	Payment order's details
amount	string	Yes	Payment order's fiat amount
required_confirmations	integer	No	Required confirmations for transactions paying the payment order
reference	string	No	Business' reference of the payment order
cancel_url	string	No	The URL where the user is redirected upon successful payment order expiration/cancellation

PaymentOrderCreationResponse

Response data for a payment order creation request

Attributes

Attribute	Type	Required	Description
expiration_time	string	Yes	Expiration's date of the payment order
expires_in	integer	Yes	Expiration's time of the payment order
uuid	string	Yes	UUID of the payment order
address	string	Yes	Bitcoin address of the payment order
uri	string	Yes	Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)
redirect_url	string	Yes	URL where to redirect the user to perform the payment
rate	RateRetrieval	Yes	Crypto/Fiat rate of the payment order
amount	integer	Yes	Crypto amount of the payment order
created_at	string	No	Creation date of the payment order
reference	string	No	Payment Order reference

ClientCredentials

Data required to perform a confidential client login

Attributes

Attribute	Type	Required	Description
scope	string	Yes	Oauth2 scope of the client's authorization
grant_type	string	Yes	Oauth2 Authorization's grant type

ClientCredentialsLoginResponse

Response data for a login performed by a confidential client.

Attributes

Attribute	Type	Required	Description
id_token	string	Yes	Jwt Token containing identity's informations
expires_in	integer	Yes	Token's expiration time
access_token	string	Yes	User's access token
scope	string	No	Authorization's scope
token_type	string	Yes	Token's type

CallbackList

Callback list object

Attributes

Attribute	Type	Required	Description
callbacks	[Callback]	Yes	Valid payment transitions callbacks

Callback

Callback Retrieval object

Attributes

Attribute	Type	Required	Description
name	string	Yes	Namespace of a callback sent after the related payment status' transition

PaymentUpdateObject

Callback's trigger request body

Attributes

Attribute	Type	Required	Description
callback	string	Yes	Name of the callback to be sent

CallbackPaymentOrder

Payment order retrieval data

Attributes

Attribute	Type	Required	Description
expires_in	integer	Yes	Expiration time of the payment order
btc_amount	integer	Yes	Bitcoin amount of the payment order
resolved_at	string	Yes	Time at which either the payment order has been fully paid or is expired
state	PaymentOrderState	Yes	Current payment state of the payment order
required_confirmations	integer	Yes	Required confirmations for transactions paying the payment order
cancel_url	string	Yes	The URL where the user is redirected upon payment order expiration/cancellation
address	string	Yes	Bitcoin address of the payment order
redirect_url	string	Yes	URL where to redirect the user to perform the payment
transactions	[Transaction]	Yes	Transactions paying the payment order
chargeback_date	string	Yes	Time at which either the payment order has been fully paid or is expired
created_at	string	Yes	Creation date of the payment order
expiration_time	string	Yes	Expiration date of the payment order
rate	RateRetrieval	Yes	Crypto/Fiat rate of the payment order
details	string	Yes	Payment order's details
currency	CurrencyRetrieval	Yes	Fiat currency of the payment order
amount	string	Yes	Fiat's amount of the payment order
created_by	PaymentOrderCreator	Yes	Data of the pos which created the payment order
continue_url	string	Yes	The URL where the user is redirected upon successful payment
uuid	string	Yes	UUID of the payment order
uri	string	Yes	Bitcoin uri
callback_url	string	Yes	The URL contacted to send callbacks related to payment status changes
dispute_start_date	string	Yes	Time at which either the payment order has been fully paid or is expired
reference	string	Yes	Business' reference for the payment order

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

Parameter	Type	Required	Description
event	string	Yes	Event which triggered the callback
created_at	string	Yes	Date in which the callback was sent
object_type	string	Yes	Type of the object sent in the callback
object	CallbackPaymentOrder	Yes

Triggered events

Event	Object Class
payment.completed	CallbackPaymentOrder
payment.dispute.start	CallbackPaymentOrder
payment.overpaid	CallbackPaymentOrder
payment.cancelled	CallbackPaymentOrder
payment.dispute.end	CallbackPaymentOrder
payment.expired	CallbackPaymentOrder
payment.chargeback	CallbackPaymentOrder

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 [email protected]