How to Reset Virtual Balance to Zero

Changing "Initial account balance" cannot be used to reset balance to zero, it is used only when a new account is being created in the Payment System. It has no effect on the existing subjects.
The "recharge to amount" within  "Periodic Recharges" cannot be used for resetting the credit as well, since it only applies if current value is less than a specified value.
Source: YSoft Payment System Administration web interface

It is NOT recommended to reset balance by an SQL query (e.g. UPDATE money_account SET balance = 0 WHERE type = 'VIRTUAL'). The operation would not be recorded in the system and this would lead to inconsistency. Administrator might wonder later on why some account has virtual balance 0 while the only operation he can see at this account is virtual balance recharge (and not decrease).

Explanation

The best approach to reset the virtual balance to 0 at several accounts at once is to use the Credit Charger tool. The Credit Charger uses supported methods (API) and this operation will be properly recorded in the system (i.e. it will be visible in Payment System administration page > Subjects > view history of a specific account > decrease balance operation is visible).

Proceed as follows:

  1. Download Credit Charger tool and the documentation:
    https://portal.ysoft.com/customer-support-service/library/manuals/credit-migration

  2. Create list of users with their virtual balance and its negated value

    1. Run this SQL query on Payment System database:

      SQL
      select guid, lookup_key, c.name, balance, -balance negatedbalance, type, state as account_state from customer c
left join money_account ma on c.id = ma.CUSTOMER_ID 
where ma.type = 'VIRTUAL' and ma.balance > 0
order by LOOKUP_KEY asc

    2. Export SQL query output to the CSV file including the column headers

    3. Convert CSV file to XLSX

      • follow Credit Charger tool documentation, section: "3 PREPARE THE SOURCE FOR THE CREDIT IMPORT TOOL"

      • pay special attention to decimal separator (point 7)

      • (Optional) remove lines representing accounts where the virtual balance should remain without a change, unfortunately filtering per Cost Center is not possible

    4. Rename the XLSX file to virtualreset.xlsx

  3. Use XLSX file with Credit Charger to reset the virtual balance

    1. Create folder c:\temp\creditcharger on the server where Payment System is installed

      • Extract Credit Charger tool to the created folder

      • Copy virtualreset.xlsx file to the created folder

    2. Run command line

      • go to directory with the tool: cd c:\temp\creditcharger

    3. Do the import:

      • command line command:

        • CreditCharger.exe -l YPS_Import.log -V -u https://127.0.0.1:8443/ -n safeq -p password --cu B2 --ca E2 -c 1 virtualimport.xlsx

      • remarks:

        • safeq is the name of default API user

        • password is the password of default API user

        • B2 is the column containing username

        • E2 is the column containing negatedbalance (that is current virtual balance prefixed by minus sign)

        • 1 is meant as a Cost Center but it is ignored in this case, though it still needs to be present to run the command

          Command might finish with an error. The following error means either the API username (-n) or the API password (-p) is incorrect:
          apiPayment.PaymentApiException: Payment System API error: Payment API: getConfiguration failed (HTTP status: 401 )

          The solution would be to use the right password for the API user "safeq", refer to YSoft Payment System Administration web interface
          (creating a new account is not recommended due to "virtual credit granted by one API account is not visible for another API account")

          If the username contains backslash (like domain\username), the import will be likely failing with:
          User domain\username not found

          This can be solved as follows:

          1. Log in to server where YSoft Payment System is installed

          2. add following lines to the <YPS>\conf\catalina.properties

            org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true

          3. Restart YSoft SafeQ Payment System service

          4. Use CreditCharger to import the credit, this time it should end with success

          5. Revert change in catalina.properties

          6. Restart YSoft SafeQ Payment System service

          Security warning

          Enabling this setting can be potential security risk - taken from Tomcat documentation:
          The org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH and org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH system properties allow non-standard parsing of the request URI. Using these options when behind a reverse proxy may enable an attacker to bypass any security constraints enforced by the proxy.

          Due to security constraints we do not plan a change in YSoft SafeQ (L4C-2460).

  4. (Optional) Use "Periodic Recharges" to increase virtual balance at accounts where non zero value is required (i.e. in case the balance was reset on all while only some of them were supposed to be reset)