README.md

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:

Install with composer

composer require chainside\webpos-sdk

Then include it in your script:

<?php

require_once '/path/to/vendor/autoload.php';

// ... use the library

Support for Laravel

For Laravel 5.5+ there is non need to do any further step since the package uses the Laravel Autodiscovery Feature.

For Laravel 5.4 and below you need to follow these steps:

Include the Service Provider in your config/app.php file under the key providers

<?php

/* config/app.php */

// ...

'providers' => [
    // ...
    Chainside\SDK\WebPos\Laravel\ChainsideWebPosSdkServiceProvider::class
],

Optional: include the Facade in your config/app.php file under the key aliases

<?php

/* config/app.php */

// ...

'aliases' => [
    // ...
    'ChainsideWebPosClient' => Chainside\SDK\WebPos\Laravel\Facades\Client::class,
    'ChainsideWebPosCallbackHandler' => Chainside\SDK\WebPos\Laravel\Facades\CallbackHandler::class,
],

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	array	No		Http Client additional configuration
cache_directory	string	No	/tmp/chainside_sdk_cache	The directory where to store the cache file

HTTP Client Configuration

To customize the HTTP client configuration please see the Guzzle Docs

Cache Configuration

By default, the SDK library uses a file cache as caching system. You can specify a different file location by changing the cache_directory config variable.

NOTE: When using the library with Laravel, the sdk will automatically use the caching driver specified in the Laravel configuration.

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 the client

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

<?php

use Chainside\SDK\WebPos\Client;

$config = [
    'mode' => 'live',
    'client_id' => 'CLIENT_ID',
    'secret' => 'SECRET'
];

$client = new Client($config);

or if running in Laravel:

<?php

// Using the IoC
$client = app('chaniside.sdk.webpos');

// Using the Facade, you can directly instantiate run an action

$response = \ChainsideWebPosClient::clientCredentialsLogin(...);

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

Method
getCallbacks($paymentOrderUuid) : CallbackList
paymentReset($paymentOrderUuid) : PaymentOrderRetrieval
paymentUpdate($paymentOrderUuid, PaymentUpdateObject $paymentUpdate) : None
deletePaymentOrder($paymentOrderUuid) : PaymentOrderDeletionResponse
getPaymentOrder($paymentOrderUuid) : PaymentOrderRetrieval
getPaymentOrders($pageSize = null, $page = null, $sortOrder = null, $sortBy = null, $status = null) : PaymentOrderList
createPaymentOrder(PaymentOrderCreation $createPaymentOrder) : PaymentOrderCreationResponse
clientCredentialsLogin(ClientCredentials $clientCredentialsLogin) : ClientCredentialsLoginResponse

Objects

CallbackList

Callback list object

Parameters

Parameter	Type	Required	Description
callbacks	\Illuminate\Support\Collection	Yes	Valid payment transitions callbacks

Callback

Callback Retrieval object

Parameters

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

PaymentOrderRetrieval

Payment order retrieval data

Parameters

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

Transaction

Bitcoin transaction paying a payment order

Parameters

Parameter	Type	Required	Description
outs	\Illuminate\Support\Collection	Yes	Transaction's outputs
status	string	Yes	Transaction's status
normalized_txid	string	Yes	Transaction's normalized id
outs_sum	integer	Yes	Paying amount of the transaction
txid	string	Yes	Transaction's id
created_at	string	Yes
blockchain_status	string	Yes	Transaction's internal status

Out

Transaction's output

Parameters

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

PaymentOrderState

Data describing the current state of a payment order

Parameters

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

PaidStatus

Cryto and fiat paid amounts

Parameters

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

PaymentOrderCreator

Data of payment order's creator

Parameters

Parameter	Type	Required	Description
type	string	Yes	Payment order creator's type
deposit_account	DepositAccountLite	Yes	Deposit account associated to the payment order's creator
name	string	Yes	Payment order creator's name
uuid	string	Yes	Payment order creator's uuid

DepositAccountLite

Deposit account lite object when sent nested in other api objects

Parameters

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

RateRetrieval

Rate Data

Parameters

Parameter	Type	Required	Description
source	string	Yes	Exchange providing the rate
created_at	string	Yes	Creation's date of the rate
value	string	Yes	Value of the rate

CurrencyRetrieval

Currency Data

Parameters

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

PaymentUpdateObject

Callback's trigger request body

Parameters

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

PaymentOrderDeletionResponse

Payment order deletion response

Parameters

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

PaymentOrderList

List of Business' payment orders

Parameters

Parameter	Type	Required	Description
total_items	integer	Yes	Total number of items
paymentorders	\Illuminate\Support\Collection	Yes	Business' payment orders
total_pages	integer	Yes	Total number of pages given the requested page size

PaymentOrderCreation

Data required to create a new payment order

Parameters

Parameter	Type	Required	Description
continue_url	string	No	The URL where the user is redirected upon successful payment
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
callback_url	string	No	The URL contacted to send callbacks related to payment status changes
required_confirmations	integer	No	Required confirmations for transactions paying the payment order
details	string	No	Payment order's details
amount	string	Yes	Payment order's fiat amount

PaymentOrderCreationResponse

Response data for a payment order creation request

Parameters

Parameter	Type	Required	Description
expiration_time	string	Yes	Expiration's date of the payment order
uuid	string	Yes	UUID of the payment order
rate	RateRetrieval	Yes	Crypto/Fiat rate of the payment order
created_at	string	No	Creation date of the payment order
amount	integer	Yes	Crypto amount of the payment order
reference	string	No	Payment Order reference
expires_in	integer	Yes	Expiration's time of the payment order
redirect_url	string	Yes	URL where to redirect the user to perform the payment
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)

ClientCredentials

Data required to perform a confidential client login

Parameters

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

ClientCredentialsLoginResponse

Response data for a login performed by a confidential client.

Parameters

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

CallbackPaymentOrder

Payment order retrieval data

Parameters

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

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:

<?php

use Chainside\SDK\WebPos\ChainsideCallbacksHandler;

$config = [
    'mode' => 'live',
    'client_id' => 'CLIENT_ID',
    'secret' => 'SECRET'
];

$context = new ApiContext($config);
$handler = new ChainsideCallbacksHandler($context);

$headers = $request->getHeaders();
$body = $request->getRawBody();

$receivedCallback = $handler->parse($headers, $body);

The ChainsideCallbacksHandler will verify and parse the callback automatically from the incoming request.

If you are using Laravel you can use the facade to access the callback handler:

<?php

$receivedCallback = \ChainsideWebPosCallbackHandler::parse($headers, $request);

// Or using the IoC
// $receivedCallback = app('chainside.sdk.webpos.callback.handler')->parse($headers, $request);

Alternatively you can use the parseFromGlobals method to automatically retrieve the request headers and the raw body from the PHP HTTP global variables:

<?php

$context = new ApiContext($config);
$handler = new ChainsideCallbacksHandler($context);

$receivedCallback = $handler->parseFromGlobals();

// Or, using Laravel

$receivedCallback = \ChainsideWebPosCallbackHandler::parseFromGlobals();

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]