Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/chainside/webpos-sdk-php


https://github.com/chainside/webpos-sdk-php

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

        




    chainside

    



    developed with :heart: by chainside




# Introduction



This project is the **official** SDK library for the integration with the [Chainside Pay](https://chainside.net) 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



```bash

composer require chainside\webpos-sdk

```



Then include it in your script:



```php

 [

    // ...

    Chainside\SDK\WebPos\Laravel\ChainsideWebPosSdkServiceProvider::class

],



```



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



```php

 [

    // ...

    '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](http://docs.guzzlephp.org/en/stable/quickstart.html)



### 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](#Objects) 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

 'live',

    'client_id' => 'CLIENT_ID',

    'secret' => 'SECRET'

];



$client = new Client($config);



```



or if running in Laravel:



```php

 '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

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

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](#callbackpaymentorder) | Yes |  |



### Triggered events



| Event | Object Class |

|------------|--------------|

| `payment.completed` | [CallbackPaymentOrder](#callbackpaymentorder) |

| `payment.dispute.start` | [CallbackPaymentOrder](#callbackpaymentorder) |

| `payment.overpaid` | [CallbackPaymentOrder](#callbackpaymentorder) |

| `payment.cancelled` | [CallbackPaymentOrder](#callbackpaymentorder) |

| `payment.dispute.end` | [CallbackPaymentOrder](#callbackpaymentorder) |

| `payment.expired` | [CallbackPaymentOrder](#callbackpaymentorder) |

| `payment.chargeback` | [CallbackPaymentOrder](#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]](mailto:[email protected])