chainside/webpos-sdk

There is no license information available for the latest version (3.0.0) of this package.

SDKs for WebPos integration for ChainsidePay

3.0.0 2019-11-11 16:38 UTC

README

chainside

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 info@chainside.net