{"id":22151436,"url":"https://github.com/chainside/webpos-sdk-php","last_synced_at":"2025-07-26T05:31:25.780Z","repository":{"id":62501009,"uuid":"171940383","full_name":"chainside/webpos-sdk-php","owner":"chainside","description":null,"archived":false,"fork":false,"pushed_at":"2020-09-30T16:33:43.000Z","size":118,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-15T19:21:05.810Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chainside.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-21T20:28:43.000Z","updated_at":"2024-04-15T19:21:05.811Z","dependencies_parsed_at":"2022-11-02T12:01:09.490Z","dependency_job_id":null,"html_url":"https://github.com/chainside/webpos-sdk-php","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainside%2Fwebpos-sdk-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainside%2Fwebpos-sdk-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainside%2Fwebpos-sdk-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainside%2Fwebpos-sdk-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chainside","download_url":"https://codeload.github.com/chainside/webpos-sdk-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227652379,"owners_count":17799226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-02T00:33:10.321Z","updated_at":"2024-12-02T00:33:11.144Z","avatar_url":"https://github.com/chainside.png","language":"PHP","readme":"\u003c!--\nNigiri auto-generated file\n--\u003e\n\u003cp\u003e\n    \u003cimg src=\"https://www.chainside.net/wp-content/themes/chainside2018/assets/favicon/favicon-192.png\" alt=\"chainside\" width=\"80\"\u003e\n    \u003cbr /\u003e\u003cbr /\u003e\n    developed with :heart: by \u003ca href=\"https://www.chainside.net\"\u003echainside\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- START doctoc --\u003e\n\u003c!-- END doctoc  --\u003e\n\n# Introduction\n\nThis 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.\n\n# Installation\n\nFollow these steps to install the SDK library into your system:\n\n## Install with composer\n\n```bash\ncomposer require chainside\\webpos-sdk\n```\n\nThen include it in your script:\n\n```php\n\u003c?php\n\nrequire_once '/path/to/vendor/autoload.php';\n\n// ... use the library\n\n```\n\n## Support for Laravel\n\nFor **Laravel 5.5+** there is non need to do any further step since the package uses the [Laravel Autodiscovery Feature](https://laravel.com/docs/packages#package-discovery).\n\nFor *Laravel 5.4 and below* you need to follow these steps:\n\nInclude the Service Provider in your `config/app.php` file under the key `providers`\n\n```php\n\u003c?php\n\n/* config/app.php */\n\n// ...\n\n'providers' =\u003e [\n    // ...\n    Chainside\\SDK\\WebPos\\Laravel\\ChainsideWebPosSdkServiceProvider::class\n],\n\n\n```\n\n**Optional:** include the Facade in your `config/app.php` file under the key `aliases`\n\n```php\n\u003c?php\n\n/* config/app.php */\n\n// ...\n\n'aliases' =\u003e [\n    // ...\n    'ChainsideWebPosClient' =\u003e Chainside\\SDK\\WebPos\\Laravel\\Facades\\Client::class,\n    'ChainsideWebPosCallbackHandler' =\u003e Chainside\\SDK\\WebPos\\Laravel\\Facades\\CallbackHandler::class,\n],\n\n```\n\n# Structure\n\nThe following sections will describe the high level structure of the\nSDK library.\n\n## Configuration\n\nIn order to be able to configure your SDK client you have to set some\nconfiguration parameters. Here is the list of the configuration parameters\nused by the library:\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| **mode** | _string_ | Yes | `live` | The SDK mode, can be `sandbox` or `live` |\n| **client_id** | _string_ | Yes | `null` | Your WebPos client id |\n| **secret** | _string_ | Yes | `null` | Your WebPos secret |\n| **http**   | _array_  | No  | | Http Client additional configuration  |\n| **cache_directory** | _string_ | No | `/tmp/chainside_sdk_cache` | The directory where to store the cache file |\n\n### HTTP Client Configuration\n\nTo customize the HTTP client configuration please see the [Guzzle Docs](http://docs.guzzlephp.org/en/stable/quickstart.html)\n\n### Cache Configuration\n\nBy default, the SDK library uses a file cache as caching system. You can specify a different file location by changing the\n*cache_directory* config variable.\n\n**NOTE:** When using the library with Laravel, the sdk will automatically use the caching driver specified\nin the Laravel configuration.\n\n## Client\n\nThe Library exposes a _client_ object which is instantiated with the system configuration and\nprovides an high-level interface to send requests. Client's instances take care of compiling and\nsending http request and parse responses into [SdkObject](#Objects) instances.\n\n## Objects\n\nThe library defines an SdkObject class which is extended by actual objects which represent Chainside-Pay\nAPI requests and response bodies. Every json object defined in the API has a corresponding SdkObject\nclass which is either the input of a _client_ instance method (for creation) or returned (for reading)\n\n## Callbacks\n\nCallbacks are requests sent by the server to your application in order\nto notify about some events. Every callback is sent **only to HTTPS**\nwebhooks and will be securely signed by the server in order to be verified.\n\n# Usage\n\nThe following sections will describe how to use the SDK library and\nall the detail needed to integrate your business with Chainside Pay.\n\n## Instantiate the client\n\nIn order to communicate with our backend first you need to instantiate\nthe client:\n\n```php\n\u003c?php\n\nuse Chainside\\SDK\\WebPos\\Client;\n\n$config = [\n    'mode' =\u003e 'live',\n    'client_id' =\u003e 'CLIENT_ID',\n    'secret' =\u003e 'SECRET'\n];\n\n$client = new Client($config);\n\n```\n\nor if running in Laravel:\n\n```php\n\u003c?php\n\n// Using the IoC\n$client = app('chaniside.sdk.webpos');\n\n// Using the Facade, you can directly instantiate run an action\n\n$response = \\ChainsideWebPosClient::clientCredentialsLogin(...);\n\n```\n\n\nOnce the client is instantiated and configured, you can use the following\nmethods to send requests:\n\n| Method |\n|--------|\n| `getCallbacks`($paymentOrderUuid) : [CallbackList](#CallbackList)|\n| `paymentReset`($paymentOrderUuid) : [PaymentOrderRetrieval](#PaymentOrderRetrieval)|\n| `paymentUpdate`($paymentOrderUuid, PaymentUpdateObject $paymentUpdate) : [None](#None)|\n| `deletePaymentOrder`($paymentOrderUuid) : [PaymentOrderDeletionResponse](#PaymentOrderDeletionResponse)|\n| `getPaymentOrder`($paymentOrderUuid) : [PaymentOrderRetrieval](#PaymentOrderRetrieval)|\n| `getPaymentOrders`($pageSize = null, $page = null, $sortOrder = null, $sortBy = null, $status = null) : [PaymentOrderList](#PaymentOrderList)|\n| `createPaymentOrder`(PaymentOrderCreation $createPaymentOrder) : [PaymentOrderCreationResponse](#PaymentOrderCreationResponse)|\n| `clientCredentialsLogin`(ClientCredentials $clientCredentialsLogin) : [ClientCredentialsLoginResponse](#ClientCredentialsLoginResponse)|\n\n\n## Objects\n\n### CallbackList\n\nCallback list object\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| callbacks | _\\Illuminate\\Support\\Collection_ | Yes | Valid payment transitions callbacks |\n\n\n### Callback\n\nCallback Retrieval object\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| name | _string_ | Yes | Namespace of a callback sent after the related payment status' transition |\n\n\n### PaymentOrderRetrieval\n\nPayment order retrieval data\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| dispute_start_date | _string_ | Yes | Time at which either the payment order has been fully paid or is expired |\n| chargeback_date | _string_ | Yes | Time at which either the payment order has been fully paid or is expired |\n| resolved_at | _string_ | Yes | Time at which either the payment order has been fully paid or is expired |\n| transactions | _\\Illuminate\\Support\\Collection_ | Yes | Transactions paying the payment order |\n| details | _string_ | Yes | Payment order's details |\n| redirect_url | _string_ | Yes | URL where to redirect the user to perform the payment |\n| expires_in | _integer_ | Yes |  Expiration time of the payment order |\n| state | _[PaymentOrderState](#paymentorderstate)_ | Yes | Current payment state of the payment order |\n| required_confirmations | _integer_ | Yes | Required confirmations for transactions paying the payment order |\n| uuid | _string_ | Yes | UUID of the payment order |\n| uri | _string_ | Yes | Bitcoin uri |\n| expiration_time | _string_ | Yes | Expiration date of the payment order |\n| created_by | _[PaymentOrderCreator](#paymentordercreator)_ | Yes | Data of the pos which created the payment order |\n| rate | _[RateRetrieval](#rateretrieval)_ | Yes | Crypto/Fiat rate of the payment order |\n| created_at | _string_ | Yes | Creation date of the payment order |\n| amount | _string_ | Yes | Fiat's amount of the payment order |\n| reference | _string_ | Yes | Business' reference for the payment order |\n| currency | _[CurrencyRetrieval](#currencyretrieval)_ | Yes | Fiat currency of the payment order |\n| callback_url | _string_ | Yes | The URL contacted to send callbacks related to payment status changes |\n| btc_amount | _integer_ | Yes |  Bitcoin amount of the payment order |\n| address | _string_ | Yes | Bitcoin address of the payment order |\n\n\n### Transaction\n\nBitcoin transaction paying a payment order\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| outs | _\\Illuminate\\Support\\Collection_ | Yes | Transaction's outputs |\n| status | _string_ | Yes | Transaction's status |\n| normalized_txid | _string_ | Yes | Transaction's normalized id |\n| outs_sum | _integer_ | Yes | Paying amount of the transaction |\n| txid | _string_ | Yes | Transaction's id |\n| created_at | _string_ | Yes |  |\n| blockchain_status | _string_ | Yes | Transaction's internal status |\n\n\n### Out\n\nTransaction's output\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| n | _integer_ | Yes | Transaction output's index |\n| amount | _integer_ | Yes | Output's amount |\n\n\n### PaymentOrderState\n\nData describing the current state of a payment order\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| in_confirmation | _[PaidStatus](#paidstatus)_ | Yes | Payment order's paid but unconfirmed amount |\n| unpaid | _[PaidStatus](#paidstatus)_ | Yes | Payment order's unpaid amount |\n| paid | _[PaidStatus](#paidstatus)_ | Yes | Payment order's paid amount |\n| status | _string_ | Yes | Payment order's status |\n| blockchain_status | _string_ | Yes | Payment order's internal status |\n\n\n### PaidStatus\n\nCryto and fiat paid amounts\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| crypto | _integer_ | Yes | Cryto Amount |\n| fiat | _string_ | Yes | Fiat Amount |\n\n\n### PaymentOrderCreator\n\nData of payment order's creator\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| type | _string_ | Yes | Payment order creator's type |\n| deposit_account | _[DepositAccountLite](#depositaccountlite)_ | Yes | Deposit account associated to the payment order's creator |\n| name | _string_ | Yes | Payment order creator's name |\n| uuid | _string_ | Yes | Payment order creator's uuid |\n\n\n### DepositAccountLite\n\nDeposit account lite object when sent nested in other api objects\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| type | _string_ | Yes | Deposit account's type |\n| name | _string_ | Yes | Deposit account's name |\n| uuid | _string_ | Yes | Deposit account's uuid |\n\n\n### RateRetrieval\n\nRate Data\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| source | _string_ | Yes | Exchange providing the rate |\n| created_at | _string_ | Yes | Creation's date of the rate |\n| value | _string_ | Yes | Value of the rate |\n\n\n### CurrencyRetrieval\n\nCurrency Data\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| type | _string_ | Yes | Currency's type (fiat/crypto) |\n| name | _string_ | Yes | Name of the currency |\n| uuid | _string_ | Yes | UUID of the currency |\n\n\n### PaymentUpdateObject\n\nCallback's trigger request body\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| callback | _string_ | Yes | Name of the callback to be sent |\n\n\n### PaymentOrderDeletionResponse\n\nPayment order deletion response\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| cancel_url | _string_ | Yes | The URL where the user is redirected upon payment order expiration/cancellation |\n\n\n### PaymentOrderList\n\nList of Business' payment orders\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| total_items | _integer_ | Yes | Total number of items |\n| paymentorders | _\\Illuminate\\Support\\Collection_ | Yes | Business' payment orders |\n| total_pages | _integer_ | Yes | Total number of pages given the requested page size |\n\n\n### PaymentOrderCreation\n\nData required to create a new payment order\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| continue_url | _string_ | No | The URL where the user is redirected upon successful payment |\n| reference | _string_ | No | Business' reference of the payment order |\n| cancel_url | _string_ | No | The URL where the user is redirected upon successful payment order expiration/cancellation |\n| callback_url | _string_ | No | The URL contacted to send callbacks related to payment status changes |\n| required_confirmations | _integer_ | No | Required confirmations for transactions paying the payment order |\n| details | _string_ | No | Payment order's details |\n| amount | _string_ | Yes | Payment order's fiat amount |\n\n\n### PaymentOrderCreationResponse\n\nResponse data for a payment order creation request\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| expiration_time | _string_ | Yes | Expiration's date of the payment order |\n| uuid | _string_ | Yes | UUID of the payment order |\n| rate | _[RateRetrieval](#rateretrieval)_ | Yes | Crypto/Fiat rate of the payment order |\n| created_at | _string_ | No | Creation date of the payment order |\n| amount | _integer_ | Yes | Crypto amount of the payment order |\n| reference | _string_ | No | Payment Order reference |\n| expires_in | _integer_ | Yes | Expiration's time of the payment order |\n| redirect_url | _string_ | Yes | URL where to redirect the user to perform the payment |\n| address | _string_ | Yes | Bitcoin address of the payment order |\n| uri | _string_ | Yes | Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) |\n\n\n### ClientCredentials\n\nData required to perform a confidential client login\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| grant_type | _string_ | Yes | Oauth2 Authorization's grant type |\n| scope | _string_ | Yes | Oauth2 scope of the client's authorization |\n\n\n### ClientCredentialsLoginResponse\n\nResponse data for a login performed by a confidential client.\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| token_type | _string_ | Yes | Token's type |\n| expires_in | _integer_ | Yes | Token's expiration time |\n| access_token | _string_ | Yes | User's access token |\n| id_token | _string_ | Yes | Jwt Token containing identity's informations |\n| scope | _string_ | No | Authorization's scope |\n\n\n### CallbackPaymentOrder\n\nPayment order retrieval data\n\n#### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| dispute_start_date | _string_ | Yes | Time at which either the payment order has been fully paid or is expired |\n| expiration_time | _string_ | Yes | Expiration date of the payment order |\n| chargeback_date | _string_ | Yes | Time at which either the payment order has been fully paid or is expired |\n| uuid | _string_ | Yes | UUID of the payment order |\n| transactions | _\\Illuminate\\Support\\Collection_ | Yes | Transactions paying the payment order |\n| details | _string_ | Yes | Payment order's details |\n| redirect_url | _string_ | Yes | URL where to redirect the user to perform the payment |\n| expires_in | _integer_ | Yes |  Expiration time of the payment order |\n| state | _[PaymentOrderState](#paymentorderstate)_ | Yes | Current payment state of the payment order |\n| required_confirmations | _integer_ | Yes | Required confirmations for transactions paying the payment order |\n| uri | _string_ | Yes | Bitcoin uri |\n| resolved_at | _string_ | Yes | Time at which either the payment order has been fully paid or is expired |\n| continue_url | _string_ | Yes | The URL where the user is redirected upon successful payment |\n| created_by | _[PaymentOrderCreator](#paymentordercreator)_ | Yes | Data of the pos which created the payment order |\n| cancel_url | _string_ | Yes | The URL where the user is redirected upon payment order expiration/cancellation |\n| rate | _[RateRetrieval](#rateretrieval)_ | Yes | Crypto/Fiat rate of the payment order |\n| created_at | _string_ | Yes | Creation date of the payment order |\n| amount | _string_ | Yes | Fiat's amount of the payment order |\n| reference | _string_ | Yes | Business' reference for the payment order |\n| callback_url | _string_ | Yes | The URL contacted to send callbacks related to payment status changes |\n| currency | _[CurrencyRetrieval](#currencyretrieval)_ | Yes | Fiat currency of the payment order |\n| btc_amount | _integer_ | Yes |  Bitcoin amount of the payment order |\n| address | _string_ | Yes | Bitcoin address of the payment order |\n\n\n\n\n## Callbacks\n\nChainside will send callbacks if some event is triggered regarding one of your assets registered on the Business Panel.\nOur server will send a request to your webhooks that you need to parse and verify. You can do this using this SDK library\nin the following way:\n\n```php\n\u003c?php\n\nuse Chainside\\SDK\\WebPos\\ChainsideCallbacksHandler;\n\n$config = [\n    'mode' =\u003e 'live',\n    'client_id' =\u003e 'CLIENT_ID',\n    'secret' =\u003e 'SECRET'\n];\n\n$context = new ApiContext($config);\n$handler = new ChainsideCallbacksHandler($context);\n\n$headers = $request-\u003egetHeaders();\n$body = $request-\u003egetRawBody();\n\n$receivedCallback = $handler-\u003eparse($headers, $body);\n\n```\n\nThe `ChainsideCallbacksHandler` will **verify** and **parse** the callback automatically from the incoming request.\n\nIf you are using Laravel you can use the facade to access the callback handler:\n\n```php\n\u003c?php\n\n$receivedCallback = \\ChainsideWebPosCallbackHandler::parse($headers, $request);\n\n// Or using the IoC\n// $receivedCallback = app('chainside.sdk.webpos.callback.handler')-\u003eparse($headers, $request);\n\n```\n\nAlternatively you can use the `parseFromGlobals` method to automatically retrieve the request headers and\nthe raw body from the PHP HTTP global variables:\n\n```php\n\u003c?php\n\n$context = new ApiContext($config);\n$handler = new ChainsideCallbacksHandler($context);\n\n$receivedCallback = $handler-\u003eparseFromGlobals();\n\n// Or, using Laravel\n\n$receivedCallback = \\ChainsideWebPosCallbackHandler::parseFromGlobals();\n\n```\n\n### Callback structure\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| event | _string_ | Yes | Event which triggered the callback |\n| created_at | _string_ | Yes | Date in which the callback was sent |\n| object_type | _string_ | Yes | Type of the object sent in the callback |\n| object | [CallbackPaymentOrder](#callbackpaymentorder) | Yes |  |\n\n\n### Triggered events\n\n| Event | Object Class |\n|------------|--------------|\n| `payment.completed` | [CallbackPaymentOrder](#callbackpaymentorder) |\n| `payment.dispute.start` | [CallbackPaymentOrder](#callbackpaymentorder) |\n| `payment.overpaid` | [CallbackPaymentOrder](#callbackpaymentorder) |\n| `payment.cancelled` | [CallbackPaymentOrder](#callbackpaymentorder) |\n| `payment.dispute.end` | [CallbackPaymentOrder](#callbackpaymentorder) |\n| `payment.expired` | [CallbackPaymentOrder](#callbackpaymentorder) |\n| `payment.chargeback` | [CallbackPaymentOrder](#callbackpaymentorder) |\n\n\n# Contributing\n\nIn order to maintain consistency between our backend and our SDKs, contributing through pull requests is highly\ndiscouraged. Consider posting an issue if you need to signal any problem with this library.\n\n# Security Issues\n\nIn case of a discovery of an actual or potential security issue please contact us at [info@chainside.net](mailto:info@chaniside.net)\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainside%2Fwebpos-sdk-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainside%2Fwebpos-sdk-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainside%2Fwebpos-sdk-php/lists"}