Download the PHP package chainside/webpos-sdk without Composer
On this page you can find all versions of the php package chainside/webpos-sdk. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package webpos-sdk
developed with :heart: 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
Then include it in your script:
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
Optional: include the Facade in your config/app.php file under the key aliases
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:
or if running in Laravel:
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:
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:
Alternatively you can use the parseFromGlobals method to automatically retrieve the request headers and
the raw body from the PHP HTTP global variables:
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]
