YSoft Payment System Administration web interface

Prerequisites

Check these prerequisites before using the YSoft SafeQ Payment System Administration web interface:

  • YSoft SafeQ Payment System is connected to YSoft SafeQ Management Server (for more information see safeq.authentication.address in Advanced Configuration of YSoft SafeQ Payment System)

  • At least one user with role > " YSoft SafeQ Administrators with full access right" is available in YSoft SafeQ (for more information about required YSoft SafeQ roles, see Configuring Payment System).

  • Services YSoft SafeQ Payment System and YSoft SafeQ Management Server are running

Log In/Out

There are several ways how to get to the Administration login page:

  • use shortcut named YSoft Payment System web interface, which should be on a desktop of your YSoft SafeQ Payment System server

  • go to the index page https://<PAYMENT-SERVER-HOST>:8443 and click on link YSoft Payment System Administration

  • use direct link https://<PAYMENT-SERVER-HOST>:8443/payment-system/admin

Log In With Credentials

  1. Go to the YSoft SafeQ Payment System Administration login page.

  2. Enter credentials of YSoft SafeQ user with administrator rights (role YSoft SafeQ Administrators with full access right ).

    images/download/thumbnails/160483986/image2014-10-27_14_46_1.png

  3. Click Log in.

Log In As Current Windows User

This feature is not available in the default configuration of YSoft SafeQ Payment System. For more information about the configuration of Single Sign On, see Configuring Single Sign-on for YSoft SafeQ Payment System.

  1. Go to the YSoft SafeQ Payment System Administration login page.

  2. Click link Log in as current Windows user.

    images/download/thumbnails/160483986/image2016-5-17_18-16-10.png

Log Out

The Log out button is located in the top right corner. Users will also be automatically logged out after long inactivity(for more information about session timeout, see Working with Payment System chapter Session Timeout).

Administration Overview

The Administration web interface is dedicated to system administrators. Its left menu is divided into two main sections:

  • Manage – allows administrators to manage (create, modify, delete) objects that are in YSoft SafeQ Payment System

  • Configure – allows administrators to configure different settings and features for YSoft SafeQ Payment System and for Cash Desk as well

Common Actions

Action

Description

Example

Language selection

You can select the language of the Administration web interface at the top right corner.

images/download/attachments/160483986/image2016-5-19_9_25_8.png

Filtering

Some tables allow the filtering of results. The filter is always located at the top of the page, above the table header. Filter fields usually represent table columns. Button "Reset" will set filter fields to their default values. Page refresh will also trigger filter reset.

images/download/attachments/160483986/image2016-5-19_9_30_20.png

Sorting

Some table columns allow sorting. The following icons represent ascending images/download/attachments/160483986/arrow-up.png and descending images/download/attachments/160483986/arrow-down.png order. Sorting affects all table results, not just the visible page.


Pagination

The default table view will display a maximum of 10 records per page. You can change this limit in the upper right corner of the table. Allowed values are 10, 25, 50, and 100 records per page. The present table page is represented by a number inside of blue square at the bottom of the table. Icons », «, »», «« will move you to the next, previous, last, and first page, respectively. Pagination is not affected by a page refresh.

images/download/attachments/160483986/image2016-5-19_10_13_23.png
images/download/attachments/160483986/image2016-5-19_10_14_9.png

Bulk actions

Some tables contain checkboxes. These are used for bulk actions located at the bottom of the table. Bulk action buttons are clickable only after selecting at least one record. The checkbox located at the top left corner will select all records from the present table page.

images/download/attachments/160483986/image2016-5-19_10_43_32.png

View detail

Some table records have a "View" link at the end of their row. This link will display more details about the record.

images/download/attachments/160483986/image2016-5-19_10_11_7.png

View all

Some details display previews from additional tables (for example "Last 5 transactions"). Link "view all" will forward you to the full table view.

images/download/attachments/160483986/image2016-5-19_10_37_52.png

Remove action

These actions generally remove selected records from the view in the Administration web interface. In some cases, records remain in the database for auditing purposes.

Remove actions are final and cannot be reverted.


Management

Entitlements

Entitlement defines which kind of services can be used by a YSoft SafeQ user (a subject) in YSoft SafeQ Payment System. There are following types of entitlements: Prepaid account (user has money balance to pay for services), Page quota (user can use services to a limited amount), No access (user is not allowed to use YSoft SafeQ Payment System services), and Unlimited access (user is allowed to print or copy unlimitedly). Each entitlement has a unique set of criteria used for matching of YSoft SafeQ users either by username or by cost center number. If no entitlement matches these criteria, YSoft will assign Default entitlement to a user. YSoft SafeQ users are represented as subjects in YSoft SafeQ Payment System. Each subject is represented by the assigned entitlement and balance if applicable. The subject is created upon the first interaction with YSoft SafeQ Payment System (login at a terminal, login to End User interface, Entitlement refresh, interaction with the account in Cash desk).

Here are few basic examples of subject creation:

  • A new subject

    1. YSoft SafeQ user is assigned to cost center number 0 and has no corresponding subject in YSoft SafeQ Payment System.

    2. User logs into YSoft SafeQ Embedded Terminal or the YSoft SafeQ End User interface.

    3. YSoft SafeQ user is matched with some entitlement (for example default entitlement with prepaid account).

    4. YSoft SafeQ Payment System creates a new subject based on the entitlement type (for example subject with prepaid account and with zero initial and zero minimum balance).

  • A match with an existing subject with changed cost center

    1. YSoft SafeQ user is assigned to cost center number 0 and has one corresponding subject in YSoft SafeQ Payment System.

    2. YSoft SafeQ Payment System subject is created with entitlement matching to cost center number 0 (for example "Prepaid account").

    3. YSoft SafeQ user is assigned to new cost center number 1. The subject in YSoft SafeQ Payment System remains unchanged.

    4. User logs into YSoft SafeQ Embedded Terminal or YSoft SafeQ End User interface.

    5. YSoft SafeQ user now matched with a different entitlement (for example "Page Quota).

    6. YSoft SafeQ Payment System subject is updated to the last matched entitlement (subject changes to "page quota" in this example).

  • A match with many subjects during refresh of an entitlement

    1. Several YSoft SafeQ users are newly assigned to cost center number 1

    2. An administrator clicks refresh button on the existing entitlement in YSoft SafeQ Payment System Administration web interface.

    3. YSoft SafeQ Payment System updates all subjects corresponding to all YSoft SafeQ users from cost center number 1.

There is always only one default entitlement.

Default entitlement cannot be refreshed.

Login to YSoft SafeQ Embedded Terminal or YSoft SafeQ End User interface will always trigger an entitlement match (usually by request about subject's balance or remaining quota).

Subjects are created during a transaction request (or generally a call to REST API) and depends on YSoft SafeQ option onDemandPaymentAccountCreation, that is enabled by default in YSoft SafeQ 6.

The current implementation of unlimited access entitlement will always return HTTP 404 as a response to an API request about user balance. This response allows unlimited use of services in Embedded Terminals.

There is a limitation, when log into hardware terminals (for example Terminal Professional v3 or Terminal Ultralight) will not trigger entitlement matching algorithm, because these devices use older REST API for communication with YSoft SafeQ Payment System (they use "payment-system/api/v2" instead of "entitlement-system/api/v1"). As a consequence this mean, that login into these devices will not trigger subject creation nor assignment of related entitlement in YSoft SafeQ Payment System.

For more information about entitlement attributes, see tables below. For more information about subjects, see chapter Subjects.

Following examples show creation of new entitlement, a list of entitlements and details of prepaid account and page quota entitlements.

images/download/attachments/160483986/image2016-7-20_13_3_52.png

images/download/attachments/160483986/image2016-7-20_13-22-8.png

images/download/attachments/160483986/image2016-7-20_13_24_2.png.jpg

images/download/attachments/160483986/image2016-7-20_13-27-23.png

Entitlement Attributes

Attribute

Description

Summary

Summary used for better identification of entitlement in Administration web interface.

GUID

Unique entitlement identifier.

Type

There are four possible values:

  • No access – Users are not allowed to use YSoft SafeQ Payment System. This means, that for example login into YSoft Embedded Terminal will be denied. This option is usually used as an equivalent of disabled or removed user.

  • Page quota – Subjects assigned to this entitlement will use quota limits in order to use a different combination of services. For the list of available combinations, see chapter Quotas.

  • Prepaid account – Subjects assigned to this entitlement will use money in order to pay for services. This option allows the use of initial and minimum balance and assignment of period recharges.

  • Unlimited access – Users assigned to this entitlement are allowed to print and copy without any limit. Jobs are without any charge. A subject is not created.

Shared entitlement

This attribute distinguishes between two basic modes:

  • Disabled – Each subject from entitlement has its own account (with information about balance or remaining quota). This is the default behavior when you have one YSoft SafeQ Payment System subject for each YSoft SafeQ user.

  • Enabled – This will create a shared subject. All YSoft SafeQ users matched by entitlement criteria will share their balance or remaining quota. This means that a decrease of balance or remaining quota by one user will affect the whole group. This option is usually used in situations when you want to have for example shared balance for each cost center.

It is not possible to change this attribute once the entitlement was created.

Cost center number

Cost center number or list of numbers used as entitlement matching criteria.

Usernames

YSoft SafeQ username or list of usernames used as entitlement matching criteria.

Entitlement assigned to username will always take precedence before cost center number. This means that the YSoft SafeQ user assigned to entitlement by his username will be always matched by this entitlement, even if the user's cost center number is used in a different entitlement.

Assigned to

Table of entitlement matching criteria. There are two possible type values, Cost center, and User.

Initial balance

This attribute is specific to Prepaid account entitlement. It will grant an initial virtual balance to all newly created subjects matched by this entitlement. Existing subjects are not affected by this option. For more information about virtual balance, see chapter Subject Attributes.

The initial virtual balance is assigned to a default safeq API user. For more information about API users, see chapter API Users.

It is also possible to assign a global initial balance in the configuration of YSoft SafeQ Payment System.

Minimum balance

This attribute is specific to the Prepaid account entitlement type. It will set a minimum balance to all existing or new subjects matched by this entitlement. For more information about minimum balance, see chapter Subject Attributes.

Periodic recharges

This attribute is specific to the Prepaid account entitlement type. It defines a list of periodic recharges, which will be assigned to all existing or new subjects matched by this entitlement. For more information about periodic recharges, see chapter Periodic Recharges.

Quotas

This attribute is specific to the Page quota entitlement type. It defines a list of quotas, which will be assigned to all existing or new subjects matched by this entitlement. For more information about periodic recharges, see chapter Quotas.

Entitlement Actions

Action

Description

Create entitlement

Opens a form for the creation of new entitlement. Saving of entitlement will create or update all subjects matched by entitlement criteria.

Edit

Opens a form for editing of entitlement.

Edit of Quotas attribute will reset all manual quota increases and consumed quotas or in other words, assigned quota subjects will act as if they were new records.

Remove

Removes selected entitlement. All already assigned subjects or those matched by entitlement criteria will be assigned to a default entitlement. It is not possible to remove the default entitlement.

Refresh

The button is displayed only for non-default entitlements with disabled sharing. It checks YSoft SafeQ users in cost centers used in matching criteria of this entitlement and it assigns or reassigns found subjects from this entitlement. From the functional point of view, it is not necessary to use this button as the subjects are going to be reassigned to a correct entitlement as soon as they interact with the system (e.g. when they authenticate on the MFD or make a print). The benefit of using this button is to see the YSoft SafeQ users in the YSoft SafeQ Payment System Administration interface or to ensure that the Periodic Recharges will happen for all users assigned to the entitlement.

Subjects

Subjects represent users from external user management (usually from YSoft SafeQ) with YSoft SafeQ Payment System specific information. There are two subject types determined by assigned entitlement: Prepaid account (subject uses money operations), and Page quota (subject uses quota operations). The remaining entitlement types No access (the subject is not used in operations from YSoft SafeQ Payment System) and Unlimited access (subject can print or copy without limit) does not create a subject. The subjects are further distinguished by their entitlement's attribute Shared entitlement to two basic groups: Personal (each subject has its own balance or remaining quota) and Shared (each subject shares its balance or remaining quota with all users assigned to the entitlement). The creation of new subjects is handled by transaction requests from other YSoft SafeQ subsystems (see chapter Entitlements) or by refresh button (see entitlement actions description for "Refresh").

Prepaid account subject type was in former versions of YSoft SafeQ Payment System called customer.

Accounts with Unlimited access and No access are not listed among subjects due to the current way of implementation.

The following examples show a list of personal subjects and details of prepaid account and page quota subject type. Possible attributes and actions are described below.

images/download/attachments/160483986/image2018-8-22_14-27-44.png

images/download/attachments/160483986/image2018-8-22_14-28-40.png

images/download/thumbnails/160483986/image2018-8-22_14-31-22.png

Subject Attributes

Attribute

Description

Name

Name is automatically assigned during subject creation. In the case of a Personal subject, the name is usually represented as follows "Name Surname (username)", where all values originate from the YSoft SafeQ user. In the case of a Shared subject, the name corresponds to the cost center number.

Subject name is automatically synchronized with YSoft SafeQ user after the opening of a subject in Using the Cash Desk Web Interface.

There is a limitation with names of Quota and Shared subjects, which are never synchronized with YSoft SafeQ 6.

Active Entitlement

Type and name of the assigned entitlement.

Possible values are prepaid account , page quota, no access, and unlimited access. Their values correspond to the assigned entitlement. For more details, see entitlement types in chapter Entitlement Attributes.

Personal subjects of no access or unlimited access type are not displayed in the administration interface.

Status

Status is indicated by the color of a user's account. If the account's background is green, then the account is active based on assigned entitlement. If it is grey, then the account is disabled. If it is orange, then the account is active based on assigned entitlement, however, the account is disabled (this should not be a common case).

Possible values are:

  • Enabled - Most of the subjects are in this status. Each new subject uses this status.

  • Disabled - Used only for Payment subjects (customers) migrated from a former version of YSoft SafeQ Payment System.

There is also Removed status, which is not visible from the administration interface and is required if a new subject has exactly the same name, surname and username but different originating ID.

In relation to the other YSoft SafeQ subsystems, disabled and removed subjects, behave like subjects with no access entitlement.

Personal Balance

The personal balance represents the subject's real money deposited by cash desk, payment gateway, or redeemed by a voucher. Each customer can have only one personal balance.

Virtual Balance

The virtual balance represents the customer's bonus or free credit. It can be provided by periodic recharge, manual increase, or by setting an initial account balance. Each customer can have many virtual balances, each assigned to a different API user merchant role, but in most cases, there is only one named safeq. Virtual balance is accessible only through the Merchant who granted it (i.e. virtual credit granted by one API account is not visible for another API account). In the case of transaction settlement, drawing of virtual balance take always precedence before personal balance. For more information about transaction settlement, see Working with Payment System.

Minimum Balance

The minimum balance represents a value below, which the personal balance cannot be decreased. Its value can be positive, zero, or even negative.

The virtual balance is not affected by the minimum balance. Its minimum value is always zero.

Periodic recharges

List of assigned periodic recharges.

Debts

Debts represent the total overdrawn value of personal balance. Similar to virtual balance, each debt is assigned to a different API user. For more information about debt configuration, see Working with Payment System (section Overdrawn transactions) and configuration of YSoft SafeQ Payment System.

Reservations

Reservations represent blocked personal and/or virtual balance. For more information about reservations, see Working with Payment System section Reservations.

Transactions

Transactions represent the history of balance changes. For more information about transaction types, see chapter Report Attributes.

Open deposits

Open deposits represent unfinished payment gateway deposits. For more information see Using YSoft SafeQ end user interface section Electronic Payment.

Quotas

Assigned Quotas and their consumed and remaining values. Each subject can have several different quota limits.

If your subject uses quotas with the same identifiers (aka services), for example, "BW" and "PRINT, BW", then each use of "PRINT, BW" service, will also spend the "BW" service.


Exported CSV reports are not localized.

Subject Actions

Most of the subject attributes can be managed from the menu in the chapter Entitlements.

Attribute

Description


This action is available only for Page quota subject type. It serves for a manual increase of quota limit for the selected subject. For more detail about the quota limit, see the chapter Quotas.

All manual increases are discarded during quota reset.

Enable prepaid account

This action enables the prepaid account if it is disabled.

Disable prepaid account

This action disables the prepaid account if it is disabled.

Remove prepaid account

This action removes the prepaid account and also clears all balances and annul all debts.

Export filtered subjects to CSV file

All subjects which correspond with a current filter will be exported to a CSV file

Quotas

Quota represents a limit of some service or combination of services provided by YSoft SafeQ. Available services are Print, Copy, Black&White, Color, and Any (aka ALL_PAGES). Quotas are assigned to subjects (either as personal or shared) through the configuration of entitlements. Each quota defines quota reset (aka recurrence), which after a specified time, will reset all spent quotas to their default limit.

Accounting of quotas depends on the configuration of entitlements and vendor-specific behavior.

The following examples show a list of quotas, the creation of a new quota, and the quota detail. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-6-16_16-5-15.png

images/download/attachments/160483986/image2016-6-16_17-15-57.png

images/download/attachments/160483986/image2016-6-16_16-10-30.png

Quota Attributes

Attribute

Description

Name

Unique quota name.

Limit

Quota limit. This limit will be assigned to each subject with this quota. This limit can be increased individually on the subject detail.

Setting the quota limit to zero will automatically deny all quota reservations for specified quota identifiers.

Identifiers / Applies to

Identifiers are in fact services available in YSoft SafeQ. These can be spent by a user. Not all combinations are valid (for example "Print Copy" is invalid).

Recurrence

Recurrence specifies how often should YSoft SafeQ Payment System reset a quota limit. Following options are possible:

  • daily – Reset will be executed every day.

  • weekly – Reset will be executed every week on the specified day of the week.

  • monthly – Reset will be executed on a given day every month.

  • yearly – Reset will be executed every year on a given day of the given month.

  • at the end of month – Reset will be executed on the last day of every month (regardless of the number of days in the month).

Please note that if you specify the day of the month from interval 29-31, then the recharge will not be executed if the month does not have the given amount of days – e.g. February does not have day 30 or 31.

Enable threshold notification

Enables configuration of threshold notification.

Threshold

Defines a proportion (in comparison to quota limit) or amount of consumed quota which will trigger quota notification.

Be aware, that your YSoft SafeQ Payment System should have a valid SMTP configuration and enabled quota notifications, before the actual email threshold notification can be sent. For more detail, see the chapter Notifications.

Owner / Owner's username/email

If defined the notification is sent to:

  • defined email address or YSoft SafeQ user if he has valid email address.

  • and the user who reached the limit

If it is not defined only the user who reached the limit is notified.

Quota Actions

Action

Description

Create quota

Displays "Create quota" page.

Edit quota

Displays "Edit quota" page.

Remove

Removes quotas. It is not possible to remove the assigned quota, at first, you should remove it from entitlement.

Periodic Recharges

Periodic recharge increases virtual balance of assigned subjects on a regular basis. It is always triggered right at the start of the defined day at 00:00. Since each virtual balance is bound to a merchant (API user with merchant role), periodic recharges are also bound to a merchant. Only the existing subjects are recharged. To increase the virtual balance even if the user missed periodic recharge date see entitlement's initial balance attribute or refresh entitlement action description.

The following examples show a list of periodic recharges and periodic recharge detail. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-5-27_16-49-22.png

images/download/attachments/160483986/image2016-6-14_21-1-49.png

Periodic Recharges Attributes

Attribute

Description

Name

Periodic recharge name

Description

Optional periodic recharge description

Status

There are two possible statuses:

  • enabled – periodic recharge is enabled and will be executed on schedule

  • disabled – periodic recharge will not be executed

Assigned merchant

Merchant (API user with merchant role), which identifies the type of subject's virtual balance to be credited.

Type

Periodic recharges can be set up to:

  • recharge by amount – the specified amount will be added with each execution

  • recharge to amount – virtual balance will be set to the specified value if the current value is less than a specified value (i.e. the resulting value will be maximum of current value and specified value)

Recurrence

Recurrence specifies the periodicity of the recharge. Following options are possible:

  • daily – recharge will be executed every day

  • weekly – recharge will be executed every week on the specified day of the week

  • monthly – recharge will be executed on the given day every month.

  • yearly – recharge will be executed every year on the given day of the given month

  • at the end of month – recharge will be executed on the last day of every month (regardless of the number of days in the month)

Please note that if you specify a day of the month from interval 29-31, then the recharge will not be executed if the month does not have the given amount of days – e.g. February does not have day 30 or 31.

In case your YSoft SafeQ Payment System was not running during some scheduled periodic recharge, don't worry, because all enabled periodic recharges are always executed retroactively, or in other words, all missed scheduled recharges will be executed at the first possible moment.

Start

Recharge will start executing at the first possible moment after the specified start date. The start date must be set to be in the future.

Periodic Recharges Actions

Action

Description

Enable recharge / Enable selected

Changes status of selected recharges to enabled.

Disable recharge / Disable selected

Changes status of selected recharges to disabled.

Remove recharge / Remove selected

Removes periodic recharge. Removed recharges remain in the database for auditing purposes, but they are no longer visible in the administration interface. Recharge is inactive.

Create periodic recharge.

Opens the "create periodic recharge" page.

View assigned customers

Shows page with a list of subjects currently assigned to the recharge. Subjects can be assigned or unassigned from the recharge.

Cash desks

Cash desks represent information about some physical place, where cash desk operators increase, decrease or refund the balance on subject accounts on behalf of account owners. In an example scenario, a person, who would like to deposit money into a money account, visits a cash desk operator. The operator will deposit money into a person's account through the Cash Desk web interface. This operation would increase both cash desk balance (where the real money is stored) and personal balance (where electronic money is sent). For more information about the usage of cash desks, see Using the Cash Desk Web Interface.

The following examples show a list of cash desks and cash desk detail. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-5-20_20-16-1.png

images/download/attachments/160483986/image2016-5-20_20-16-41.png

Cash Desk Attributes

Attribute

Description

Name

Cash desk name is used by cash desk operator in Cash Desk web interface as the main discriminator among different cash desks.

Status / Initial status

There are several available values for cash desk status:

  • Closed – Cash Desk can be opened by cash desk operator in Cash Desk web interface.

  • Opened – Cash Desk is already opened by cash desk operator. Other operators cannot use this cash desk until the present operator close it or the administrator terminates the cash desk session.

  • Disabled – Cash desk is not visible in Cash Desk web interface (even for an assigned operator).

  • Removed – Cash desk is not visible in Administration of Cash Desk web interface. This is a final state, without transition to any other state.

Type

Cash desk type affects functionality on the detail of the subject in the Cash Desk web interface. Possible types are:

  • General – This type allows you to use all actions (deposit, withdraw, change of virtual balance, refund, redeem) and you will also see all virtual balances assigned to a subject.

  • Merchant – This type is designed for environments with more than one API user merchant role (usually there is only "safeq"). It will be always assigned to one merchant and it allows you to do only basic operations with the subject's virtual balance. Only virtual balance assigned to the same merchant will be visible in the Cash Desk web interface.

Merchant

API user merchant role assigned to the cash desk with "merchant" type.

Balance / Initial balance

In the case of the general cash desk type, the cash desk balance represents real money used for deposit or withdrawal from the subject personal balance.

In the case of merchant cash desk type, there is no balance, because all operations affect only virtual balances.

Enabled display of customer history

There are two possible values:

  • Yes – This will display the button "Customer history" in detail of the subject in the Cash Desk web interface.

  • No –This will hide the button.

Current operator

Name of the cash desk operator, who lastly opened the cash desk.

Assigned operators

You can select YSoft SafeQ users with the role "cash desk operators". These users will see this cash desk after login into the Cash Desk web interface (assuming that the cash desk is not disabled).

Cash Desk Actions

Action

Description

Create cash desk

Create a new cash desk.

After the setting of the initial balance, all other cash desk balance adjustments have to be performed in the Cash Desk web interface through actions "Deposit into cash desk" and "Withdraw from cash desk".

Edit cash desk

Edit cash desk attributes.

Remove cash desk / Remove selected

Remove the cash desk. It will be no longer visible on the administration interface or Cash Desk web.

Enable cash desk / Enable selected

Change cash desk status to "Enabled".

Disable cash deks / Disable selected

Change cash desk status to "Disabled".

Terminate cash desk session

Forcibly perform transition to "Closed" status. This will make the cash desk available for all assigned operators and it will allow administrators to edit cash desk attributes.

YSoft Payment Machines

YSoft Payment Machines allow users to deposit money to their YSoft SafeQ Payment System account without the assistance of an administrator or cash desk operator. For more detail about connecting of new YSoft Payment Machine, see Configuring YSoft Payment Machine.

The following examples show a list of payment machines and payment machine detail. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-5-25_13-56-42.png

images/download/attachments/160483986/image2016-5-25_13-53-9.png

YSoft Payment Machines Attributes

Attribute

Description

Name

Name of the YSoft Payment Machine. Name is used for better identification of YSoft Payment Machine in the web administration (e.g. location).

Status

Online status of the YSoft Payment Machine. Useful for troubleshooting.

Authorization

Authorization status. Unauthorized machines cannot communicate with YSoft SafeQ Payment System.

IP

YSoft Payment Machine IP address.

Firmware

YSoft Payment Machine firmware version.

Serial number

YSoft Payment Machine serial number.

MAC address

YSoft Payment Machine mac address.

Closure

List of deposits for a certain time period. For more details see Operating YSoft Payment Machine.

YSoft Payment Machines Actions

Action

Description

Grant authorization / Authorize selected

Authorizes YSoft Payment Machine allowing it to connect to YSoft SafeQ Payment System.

Remove authorization / De-authorize selected

De-authorizes Payment Machine making it unable to connect to YSoft SafeQ Payment System.

Rename YSoft Payment Machine

Shows dialog for the renaming of YSoft Payment Machine.

Payment Gateways

The Payment Gateways tab allows you to set up integration with payment gateways through payment gateway plugins. For more detail about installation, see Payment gateway plugin deployment . Connected payment gateways are displayed to clients as gateway options on their payment gateway deposit screens. For more detail about payment gateway deposits, see Using YSoft SafeQ end user interface section Electronic Payment.

images/download/attachments/160483986/image2016-6-3_13-52-55.png

images/download/attachments/160483986/image2016-6-3_14-41-31.png

Payment Gateways Attributes

Attribute

Description

Name

Descriptive name of the plugin.

This name will be used as a gateway icon tooltip on the payment gateway deposit page.

URL

URL to the payment gateway plugin. At the moment YSoft SafeQ Payment System supports two types with these default URLs:

  • PayPal plugin URL https://<YPS_HOST>:8443/paypal-integration/api/v1

  • DIBS plugin URL https://<YPS_HOST>:8443/dibs-integration/api/v1

Use YSoft SafeQ Payment System server (or server where your payment gateway plugins are installed) true IP instead of "YPS_HOST".

The payment gateway plugin needs to be installed before using these URLs.

Do not use localhost or 127.0.0.1 instead of "YPS_HOST", because this URL be used by clients for their payment gateway deposits.

Make sure to add the certificate associated with the URLs to <YPS>\ps-conf\truststore.jks , otherwise the plugin configuration may fail to be saved. For details refer to Configuring SSL/TLS for YSoft SafeQ Payment System .

Icon URL

URL to the payment gateway icon. This icon helps visually distinguish the payment gateways. You can use either URL to the image from the internet or you can use these two defaults:

  • PayPal icon http://<YPS_HOST>:8080/paypal-integration/assets/icon.png

  • DIBS icon http://<YPS_HOST>:8080/dibs-integration/assets/icon.png

Use YSoft SafeQ Payment System server (or server where your payment gateway plugins are installed) true IP instead of "YPS_HOST".

We are deliberately using HTTP protocol instead of HTTPS in this case because HTTPS can cause problems with the visibility of the icon in some browsers.

Minimum deposit amount

The minimum amount for one deposit. Bigger amounts are usually used in the case of a payment gateway, which charges transaction fees.

Status

Possible values are:

  • enabled – user can deposit through the payment gateway

  • disabled – user cannot deposit through the payment gateway and it is not visible on the payment gateway deposit screen

Require confirmation of terms and conditions

Flag indicating whether the user must accept terms and conditions prior to transferring money through the payment gateway.

Terms and conditions

Text of terms and conditions is displayed when confirmation is required.

Payment Gateways Actions

Actions

Description

Enable connection / Enable selected

Enables selected payment gateway connection

Disable connection / Disable selected

Disables selected payment gateway connection.

Remove connection / Remove selected

Removes selected payment gateway connection. Payment gateway information is still kept in the system for auditing purposes, but the payment gateway is not accessible from the administration interface.

Create connection to plug-in

Opens create plug-in connection dialog

Edit connection

Opens edit plug-in connection dialog

Vouchers

Vouchers represent an alternative way of depositing money to subject personal balance by generating voucher codes with some assigned amount. These codes can be later redeemed by the cash desk operator from Cashdesk web interface or by the client through his YSoft SafeQ end user interface.

The following example shows a list of vouchers. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-6-3_16-7-50.png

Voucher Attributes

Attribute

Description

Code

Unique code identifying the voucher.

Amount

The amount by which the personal balance would be or was increased.

Expiration date

If a voucher with New status exceeds this limit, it is automatically switched to Expired status. Vouchers with no expiration date will never expire.

Status

Possible values are:

  • New – Voucher can be redeemed.

  • Expired – Voucher expired and it cannot be redeemed.

  • Redeemed – Voucher was already redeemed by some subject. It cannot be redeemed again.

Redemption date

Date when the voucher was redeemed.

Customer

subject who redeemed the voucher.

Voucher Actions

Action

Description

Example

Remove selected

Remove selected vouchers. Removed vouchers remain in the database for auditing purposes, but they are no longer visible on the administration interface and cannot be redeemed.


Generate vouchers

This action allows you to generate many New vouchers with random codes in one batch. Possible attributes are:

  • Number of vouchers – The system will generate random codes for the given number of vouchers. The maximum number is 1000.

  • Voucher value – Each generated voucher will have a given amount value.

  • Expiration date – Each generated voucher will have a given expiration date. This field is optional. If you omit it, generated vouchers will never expire.

images/download/attachments/160483986/image2016-6-3_16_41_14.png

Import vouchers

This action allows you to import many New vouchers with the given code from the CSV file. Possible columns in CSV file are:

  • Code (first mandatory column) – Unique voucher code. Use a maximum of 10 characters.

  • Amount (second mandatory column) – Decimal value from 0.0001 up to 1000000000.

  • Expiration date (third optional column) – Date in the yyyy-mm-dd format. It has to be in the future. If you omit it, generated vouchers will never expire.

images/download/attachments/160483986/image2016-6-3_16_52_22.png

Vouchers to template

In order to distribute new voucher codes to your money account owners, you can export your vouchers into a printable file. This action requires a DocX template with updatable fields, where each field represents a voucher code. Selected vouchers will be exported into this template. Here are the possible attributes:

  • Template file – Select a DocX template.

  • Type – You can export either selected vouchers from your vouchers menu or records created after a specific date.

  • Output file format – Choose your output format.

Only vouchers in New status will be exported into the output file.

images/download/attachments/160483986/image2016-6-6_10_44_30.png

Export vouchers

This action allows you to export vouchers into a CSV file. There are two basic modes.

  • export new vouchers – When you select this type, you will export vouchers in New status from the specific date.

  • export voucher changes – When you select changed vouchers type, you will export all status changes from all vouchers and from the specific date.

images/download/attachments/160483986/image2016-6-6_12_11_49.png

API Users

API user represents an account, which can access YSoft SafeQ Payment System REST APIs. These APIs allow integration of YSoft SafeQ Payment System with YSoft SafeQ subsystems and other third party systems. An API user can have different roles (for example Merchant, Cashdesk, Admin, Balance management). API user named safeq is always created as a default.

Since safeq API user is usually used by the rest of the YSoft SafeQ suite, its credentials are also stored in YSoft SafeQ > System settings > YSoft Payment System under options paymentSystemApiUserName and paymentSystemApiPassword .

The following examples show a list of API users and API user detail. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-6-3_14-17-50.png

images/download/attachments/160483986/image2016-6-3_13-16-11.png

API Users Attributes

Attribute

Description

Name

Name of the API user. Used for API authentication.

Password

Password used for API authentication.

Status

Current status of the API user. Possible values are:

  • enabled – API user can access the APIs

  • disabled – API user cannot access the APIs

  • locked – API user used more than 5 wrong passwords and cannot access the APIs. Action Enable will unlock the API user.

Merchant API

Access to Merchant APIs – APIs for transaction processing (reservations, settlements).

Cashdesk API

Access to Cashdesk APIs – APIs for deposits, withdrawals, or closures on a Cashdesk.

Admin API

Access to Admin APIs – APIs for management of subjects, money accounts or periodic recharges.

Balance Management API

Access to Balance Management API – APIs for increasing or decreasing virtual account balance.

API Users Actions

Action

Description

Enable API user / Enable selected

Enables or unlocks selected API users.

Disable API user / Disable selected

Disables selected API users.

Remove API user / Remove selected

Removes selected API users. Removed API users remain in the database for auditing purposes, but they are no longer visible on the administration interface.

Create API user

Opens the create API user dialog.

Change password

Opens the change password dialog.

Edit API user

Opens the edit API user dialog used for the change of the API user access.

System Incidents

System incidents section is used as:

  1. Early warning system – to notify system administrator about urgent situations needed to be fixed ASAP (for example "payment gateway is down" - sysadmin should fix it before the first user would be affected)

  2. Suspicious activity detection – to detect risky or unusual activity in the system and let admin check the risks related.

The following examples show a list of grouped incidents, a list of incidents from one group, and detail of one incident. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-5-27_9-18-37.png

images/download/attachments/160483986/image2016-6-3_15-6-10.png

images/download/attachments/160483986/image2016-6-3_15-30-34.png

System Incident Attributes

Attribute

Description

Count

Incident occurrence count. Incidents of the same kind may occur many times so they are grouped together for better readability.

Severity

Severity can have the following values:

  • Info – information message without the need for administrative action.

  • Warning – an issue that does not prevent the system to operate normally. However, it is advised that the issue is analyzed and resolved by the administrator.

  • Error – serious problem which should be immediately resolved by the administrator.

Incident source

Identifies part of the system, which generated the error.

Description

Incident description.

Occurrence date

Date of incident occurrence.

Incident detail

More detailed incident description.

System Incident Actions

Action

Description

Remove selected incidents

Permanently deletes selected incidents.

Reports

Reports contain a filterable list of all transactions from YSoft SafeQ Payment System.

The following example shows a transaction history. Possible attributes and actions are described below.

images/download/attachments/160483986/image2016-6-3_15-43-3.png

Report Attributes

Attribute

Description

ID

Internal system identifier of the transaction.

Type

Type of transaction can have the following values:

  • Balance decrease – decrease a virtual balance for a specific subject

  • Balance increase – increase a virtual balance for a specific subject

  • Balance reset – increase a virtual balance for a specific subject

  • Cash desk deposit – deposit money to a specific subject's account through a cash desk

  • Cash desk withdrawal – withdraw money from a specific subject's account through a cash desk

  • Debt registration – transactions, which registered/created new debt

  • Debt write off – a part of subject's debt, which was decreased from debt amount

  • Deposit via payment gateway – subject deposited some money to his/her YPS account through a payment gateway

  • Initial imported debt – debt created during the creation of a new imported subject (a debt from a previous payment system)

  • Initial imported deposit – the initial balance of a newly-imported subject (a balance of an account from a previous payment system)

  • Money transfer – money transferred by one step transaction

  • Recharge event – virtual money deposited by a periodic recharge

  • Transaction refund – partly or fully refunded a subject's transaction

  • Transaction settlement – settled subject's reservations (finish step of microtransaction)

  • Voucher redemption – the redemption of a voucher. Deposit money to a subjects' account by a voucher through a YSoft SafeQ end user interface or Cash Desk

  • YSoft Payment Machine deposit event – deposited money through the YSoft Payment Machine

Balance change

Amount of the transaction.

Final balance

Account balance after the transaction was performed.

Date

Transaction processing date.

Description

Transaction description – provided by the merchant.

Customer

Name of the subject, whose account participated in the transaction.

Merchant

API user, who initiated the transaction.

Exported CSV reports are not localized.

Report Actions

Action

Description

Export filtered transactions to CSV file

Download currently filtered transaction records as a CSV file.

Configuration

License

If this menu displays the message "YSoft Payment System is fully activated", your YSoft SafeQ Payment System is functional.

Otherwise check whether:

  • your YSoft SafeQ license contains the YSoft SafeQ Payment System feature

  • your YSoft SafeQ Payment System is properly connected to YSoft SafeQ.

YSoft SafeQ Payment System without a fully activated license will still allow login into the administration interface, but most actions will fail on "insufficient license" error.

Notifications

YSoft SafeQ Payment System provides you with the possibility to receive regular email notifications as an administrator or an account owner. YSoft SafeQ Payment System uses SMTP configuration from YSoft SafeQ. Periodic notifications are generated at midnight of a server's local date. The system tries to deliver unsent notifications every 5 minutes. Interval can be changed by option notification.send-emails.cron. For more detail about advanced configuration, see Advanced Configuration of YSoft SafeQ Payment System section Notification Support.

There are several types of notifications available:

  • Account balance – Notification is issued once when credit balance on the money account goes under the defined balance limit. Notifications are generated immediately after transaction settlement.

  • Transaction – Notification is issued once when any transaction is performed on the money account. Notifications are generated immediately after transaction settlement.

  • Account statement Notification is issued periodically and informs the recipient about all settled transactions on the money account during a given period.

  • Transaction history – Notification is issued periodically and informs the administrator about all settled transactions in YSoft SafeQ Payment System during a given period.

  • Quota reset – Notification is issued after each quota reset and it informs the recipient about assigned subjects and their spendings.

  • Quota threshold – Notification is issued once the quota threshold is reached. The recipient can be an admin or YSoft SafeQ user, whose transaction reached the threshold.

  • Quota threshold owner – Notification is issued the quota threshold is reached. The recipient is the quota owner defined on the detail of the quota. For more information see section Quota Attributes.

  • Error message – Notification is issued once an error occurs during background synchronization.

Each notification can be customized using the WYSIWYG editor and variables related to the current type of notification. Click Save to apply changes in the configuration of notifications.

Cash desks

Defines configuration for the usage of cash desks. You can define rules for rounding, a minimal amount for withdrawal, and receipt formats (displayed in Cash Desk web after a deposit, a withdrawal, or a refund).


The cash desk template variable amount does not contain a currency symbol. If you wish to display currency on your cash desk receipts, insert it into the template manually.

YSoft SafeQ Payment System

This section describes the basic configuration of YSoft SafeQ Payment System accessible from the administration interface. For more details about the advanced configuration, see Advanced Configuration of YSoft SafeQ Payment System.

Configuration option

Description

Decimal places

Any numeric input from the administration interface or Cash Desk web interface is rounded to the given decimal places. The same is true for the display of numbers in web interfaces.

VAT

This number determines, which part of the transaction amount will be displayed as tax.

Maximum account balance

Maximum personal balance. Any deposit (or refund) exceeding this limit will fail.

Initial account balance

Initial virtual balance for newly created subjects. Balance is assigned to the default safeq API user. Value of initial balance can be overridden before each subject creation (either from YSoft SafeQ web or through REST API).

You can also use the entitlement attribute Initial Balance, which will assign initial virtual balance only to a specific group of users. For more detail, see the chapter Entitlement Attributes.

Maximum number of refunds per payment

Each transaction can be refunded by the given number of times (None, One, Many).

Maximum refund time

Transactions older than this interval cannot be refunded.

Expiration of reservations

Reservations older than a given number of hours will be automatically canceled.

Expiration of pending deposits

Open payment gateway deposits older than the given number of days will be automatically canceled.

Overdrawn transactions

Enables or disables debt tracking in YSoft SafeQ Payment System.

It is recommended to use the option Allow and register debt if necessary if you use YSoft SafeQ Payment System with YSoft SafeQ.