dotpay_widget

Dotpay widget =================== [![npm version](https://badge.fury.io/js/dotpay_widget.svg)](https://badge.fury.io/js/dotpay_widget) This is unofficial interactive widget which allows you to choose payment channel in user-friendly way if you use [Dotpay payments](http://dotpay.pl) in your shop. You can you as much widgets on one page as you want. This widget allows you also to register your own event handler on choose payment channel. Installation ------------- You can [download](https://github.com/tbajorek/dotpay-widget/releases/latest) the latest version or [clone](https://github.com/tbajorek/dotpay-widget) the repository: ``` git clone https://github.com/tbajorek/dotpay-widget.git ``` You can compile the project using npm and [webpack](https://webpack.js.org): ``` npm install npm start ``` You can copy later the `widget.js` file to your expected destnation. Usage ------------- At first you have to include script with Dotpay widget: ``` <script type="text/javascript" src="<SCRIPT_FOLDER>/widget.js"></script> ``` where `<SCRIPT_FOLDER>` contains Javascript file `widget.js` with code. You can use then global object `window.dotpayWidget` with two methods: - ```init(configuration)``` - initializes a new widget according to configuration given by the *configuration* variable in parameter; if you don't give there some properties, they will be initialized by default values; returns jQuery object containing widget container in DOM structure; - ```getChannel()``` - returns details of selected channel, compatible to structure in data source; if none then it returns null. If you don't give the `configuration` parameter to `init()` function, it still can use configuration object saved in `window.dotpayConfig` variable. HTML element with class given in `view.widgetContainer` property has to exist when `window.dotpayWidget.init()` function is executed. For more details look at [Examples](#examples) When you have chosen a payment channel, all channels slides up. If you want to display them again, you have to click the chosen channel. ### Configuration This table contains all values you can set in widget configuration. | Property | Type | Description | Default value | |------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------| | payment.sellerId | int | Seller id from Dotpay panel | null | | payment.amount | double | Amount of money | 1000.00 | | payment.currency | string | Code of currency | `PLN` | | payment.lang | string | Code of language | `pl` | | request.host | string | Host of request where is available data with payment channels | *see more [details](#location-of-data-source)* | | request.test | boolean | Flag if test mode is used | false | | request.disabled | string | Value which informs how mode of displaying disabled channels is active (*see more [details](#displaying-of-disabled-channels)*) | `mark` | | request.hiddenChannels | array | Array of channel numbers which will not be displayed. This feature doesn't depend on data from server | null | | request.groups | array | Array of channel group ids which are displayed. If none is specified, channels from all groups will be displayed. | null | | view.widgetContainer | string | Class name of widget container | `dotpay-widget-container` | | view.channelContainer | string | Class name of single channel container | `dotpay-channel` | | view.errorContainer | string | Class name of error container | `dotpay-widget-error` | | view.chosenContainer | string | Class name of container for chosen channel | `dotpay-chosen-container` | | view.toggleStyle | string | Name of style how should be toggle channels (available values: `fade` or `slide`) | `fade` | | view.information | boolean | Flag if message information should be displayed in channel | true | | event.onLoad | function | Handler of 'load widget' event (*see more [details](#events)*) | *empty function* | | event.onChoose | function | Handler of 'select channel' event (*see more [details](#events)*) | *empty function* | #### Location of data source Dotpay offers to have a test account where you can make fake payments to test your integration before switch it to production mode. Widget uses different location of data source: - test mode: `https://ssl.dotpay.pl/test_payment/payment_api/v1/channels/` - production mode: `https://ssl.dotpay.pl/t2/payment_api/v1/channels/` You can use own data source. It requires to have available JSON data which format is compatible with used by Dotpay. #### Displaying of disabled channels Some channels can be marked in data source as disabled. You can decide how to display those channels. Here are available three ways: - `display` - disabled channel is displayed like other normal channels; - `mark` - disabled channel is displayed but marked as disable channel; - `hide` - disabled channel isn't displayed. ##### Handlers Widget allows to use two handlers. They are functions which get one parameter. Handlers handles following events: - `onLoad` - widget has been loaded successfully; parameter contains data of all channels loaded from data source; the structure is the same as in the source; - `onChoose` - payment channel has been chosen by user; parameter contains jQuery event details. Events ------ This widget offers two types of events: loading of its data from Dotpay server and choosing selected channel. Handlers are functions which take one argument - event data. It's the same object as for handlers given to native JavaScript function. ### onLoad The event is executed on the main widget object so its reference is given in the argument of handler. ### onChoose This event is executed when a payment channel has been selected. Single argument of its handler has additional property `e.channel` where is located data of selected channel with information compatible with data source (this is when `e` is the name of handler parameter). Elements of `e.channel` object are described in this table: | Property | Type | Description | |--------------------|----------|------------------------------------------------------------------------| | id | int | Payment channel id | | name | string | Name of channel | | logo | string | Url of payment channel's logo | | group | string | Group of channel | | group_name | string | Group name of channel | | short_name | string | Simplified name of channel | | is_disable | boolean | Boolean flag if channel is disabled by Dotpay | | is_not_online | boolean | Boolean flag if channel is not online (not automatical payment) | | warranty_available | boolean | Boolean flag about warranty availability | Examples ------------- #### Full simple code ``` <!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <title>Dotpay Widget</title> <script src="../dist/widget.js"></script> <script> var dotpayConfig = { //widget configuration }; window.dotpayWidget.jQuery(document).ready(function(){ window.dotpayWidget.init(dotpayConfig); }); </script> </head> <body> <div class="dotpay-widget-container"></div> </body> </html> ``` ------------- #### Basic configuration ``` var dotpayConfig = { payment: { sellerId: 999999, amount: 159.47, currency: 'USD', lang: 'en' } }; window.dotpayWidget.init(dotpayConfig); ``` License ------------- MIT, see LICENSE file.