.. _usermerchant: Merchants ######### .. toctree:: :maxdepth: 1 .. contents:: :local: .. role:: ex .. role:: code Creating Merchant ================= To see and search all Merchants, go to :code:`Settings -> Users -> Merchants`, then in order to create new Merchant press to :code:`+ New Merchant` button: .. image:: ../../_static/images/createmerchantnew.png Below are all the fields available for filling in: .. list-table:: :widths: 40, 46, 14 :header-rows: 1 :class: longtable table-text-justify table-text-center * - Field name - Description - Necessity * - :code:`Login` - Login which is required while logging in the system. **Cannot be changed after creation**. - :ex:`Required` * - :code:`Password` - Password for login. In order to change it, contact support. - :ex:`Required` * - :code:`Display Name` - Merchant name which will be displayed. - :ex:`Required` * - :code:`E-mail` - Contact E-mail which will be added to this Merchant account. - :ex:`Required` * - :code:`Control Key` - Secret key which will be used for signing requests. - :ex:`Required` * - :code:`Payment group` - Currently not in use. “Common” is a default value. **Cannot be changed after creation**. - :ex:`Required` * - :code:`Name` - Shows Merchant's contact person name. This name will be displayed only in merchant details. - :ex:`Required` * - :code:`Surname` - Shows Merchant's contact person surname. This name will be displayed only in merchant details. - :ex:`Required` * - :code:`Business type` - Will show which business type Merchant has. - :ex:`Optional` * - :code:`Returning customer approve sessions count` - Shows after how many approved transactions, Payer will be considered as Returning for Merchant. - :ex:`Optional` * - :code:`Registration country` - Shows Merchant country. - :ex:`Optional` * - :code:`Merchant site URL` - Merchant site URL can now be set on Merchant details screen and included in E-mail notifications (MERCHANT_SITE_URL macro). - :ex:`Optional` * - :code:`Organization` - Shows Merchant's organization name. - :ex:`Optional` * - :code:`Tags` - Shows tags by which Merchant can be found later in system. - :ex:`Optional` * - :code:`API descriptor` - Manager can set :ex:`API descriptor` parameter in the Merchant profile. This value will be returned instead of gate values specified in :ref:`Gate Details`. - :ex:`Optional` Merchant details ================ | The screen allows to view all details of created merchant, change settings, configure merchant balance and view linked endpoints. Linked Endpoints ^^^^^^^^^^^^^^^^ | This section by default display enabled linked endpoints to merchant. By selecting :ex:`Show disabled endpoints` the sheet will be replaced and will display disabled linked endpoints. | .. image:: ../../_static/images/get_balance/linkedendpointsnew.png :alt: linked endpoints :align: center :width: 700 .. _manager_merchant_accounts: Account balance =============== Introduction ^^^^^^^^^^^^ | Manager can configure and view multiple balances for each Merchant account and `request balances by API with manager access `_. These balances calculate the total accumulated funds from transactions associated with Merchant. Balances calculation supports configured rate plans, including :code:`STH` - Short-Term Hold and :code:`RR` - Rolling Reserve. | Manager can add adjustments to Merchant balances on UI or with `adjustment API `_ to reflect non-transactional changes in Merchant balance. See `Get Balance Adjustments `_. | By default Merchants can't see their balances on UI or `request balances by API with merchant access `_ , but this functionality can be granted to each Merchant individually. | | Merchant balances can be configured via Accounts tab on Merchant details screen. | To set up calculation of balances, follow these steps: | 1. Set :ref:`Account configuration` to define how and which transactions and rates should affect :ref:`balances`. | 2. Set :ref:`Balances` for required :ref:`currencies` and :ref:`endpoints`. | 3. Set :ref:`Account configuration override` for specific :ref:`Balances` (if needed). First balance is funded by :code:`sale` transactions and defunded by :code:`payout` transactions and is set up for :ex:`USD` currency, also Merchant rates applied for :code:`sale` transactions. Second balance has override for sale transactions which will deduct balance with amount calculated from manager rate plan. Below is the example of fully configured balance with highlighted steps. .. image:: ../../_static/images/get_balance/configuredbalancenew.png :alt: configured balance :align: center :width: 650 .. _account_configuration: Account configuration ^^^^^^^^^^^^^^^^^^^^^ Merchant's accounts can be configured via :ex:`Accounts` tab. See example of accounts window below: .. image:: ../../_static/images/get_balance/accountstabnew.png :alt: accounts tab :align: center :width: 800 .. _application_rate_direction: Application Rate Direction ~~~~~~~~~~~~~~~~~~~~~~~~~~ Transactions with :code:`rate only` can select both :code:`ADD` and :code:`DEDUCT`. For each transactions apply rate can be specified differently. For example, if it is needed to deduct a commission for a Payout transaction in addition to deducting the amount of the Payout itself then need to choose :code:`DEDUCT` in the :code:`Apply direction` configuration. .. _application_impact_on_balance: Application Impact on Balance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Different types of transactions count differently when calculating balances. List of application impact on balance is shown in the table below: .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Transaction type - Impact on balance * - :code:`sale` - Add * - :code:`capture` - Add * - :code:`dispute` - Add * - :code:`chargeback_reversal` - Add * - :code:`arbitration` - Add * - :code:`payout_cancel` - Add * - :code:`chargeback` - Deduct * - :code:`prearbitration` - Deduct * - :code:`reversal` - Deduct * - :code:`payout` - Deduct * - :code:`transfer (deposit2card)` - Deduct * - :code:`preauth` - Rate only * - :code:`cancel` - Rate only * - :code:`fraud` - Rate only * - :code:`retrieval` - Rate only * - :code:`pan_eligibility` - Rate only * - :code:`create_card_mapping` - Rate only * - :code:`update_card_mapping` - Rate only * - :code:`inquire_card_mapping` - Rate only * - :code:`delete_card_mapping` - Rate only * - :code:`mfo_scoring` - Rate only * - :code:`account_verification` - Rate only * - :code:`void` - Rate only Rate Types ~~~~~~~~~~ For each type of transaction, Manager can separately apply the rate (commission). Possible rate types are: * Nothing * Merchant * Reseller * Manager * Dealer * Acquirer .. _date_bump_func: Date Bumping Functions ~~~~~~~~~~~~~~~~~~~~~~ | Date bumping functions allows to choose when the funds will be credited to the account. Possible values are: * :code:`ASAP` - crediting funds without delay. Doesn't include :code:`STH` and :code:`Rolling Reserve`. * :code:`ASAP_plus_RR` - crediting funds ASAP and counts :code:`Rolling reserve`. Doesn't include :code:`STH`. * :code:`DAY + n` - crediting funds from :code:`STH` after the specified number of days + :code:`Rolling Reserve`. * :code:`BDAY + n` - crediting funds from :code:`STH` after the specified number of business days + :code:`Rolling Reserve`. | .. image:: ../../_static/images/get_balance/date_bump_new.png :alt: date bump :align: center :width: 400 Add account configuration ------------------------- To create new account balance, add :ex:`account configuration` and balance: 1. To add new account configuration press :code:`+Add` button in configuration field and set up the transaction type and rates, which will add or deduct funds from balance by settings described in :ref:`Accounts Configuration`. Optionally, gate and endpoint can be selected - if they are left empty, balance configuration will work for all gates and endpoints of selected Merchant. | .. image:: ../../_static/images/get_balance/addconfnew.png :alt: add conf :align: center :width: 300 .. _balances: Balances ^^^^^^^^ Add balance ~~~~~~~~~~~ 2. To add new account balance press :code:`+Add` button in account balances field and set up balance and manager name and currency. Detailed setting of account balance is described below in this section. | .. image:: ../../_static/images/get_balance/adding_account_balance_new.png :alt: adding account balance :align: center :width: 300 Types ~~~~~ There are four types of funds for each balance: Balance Total ------------- Balance Total - amount of funds calculated based on configuration, including :code:`STH` and :code:`RR`. | .. image:: ../../_static/images/get_balance/currbalancenew.png :alt: balance total :align: center :width: 870 Balance Live ------------ Balance Live - amount of funds calculated based on configuration, excluding :code:`STH` and :code:`RR`. | .. image:: ../../_static/images/get_balance/livebalancenew.png :alt: live balance :align: center :width: 870 | .. admonition:: Example Balance Live = Balance Total - STH - RR. Short-Term Holds ---------------- Short-Term Holds - amount of funds calculated based on the :code:`Date bumping function`. | .. image:: ../../_static/images/get_balance/sthnew.png :alt: sth :align: center :width: 870 | .. admonition:: Example Transactions passed today from 11:01 to 11:59 will be credited at 12:01 on the day on which they should be credited according to the parameter :ex:`DAY + n` or :ex:`BDAY + n`. Rolling Reserve --------------- Rolling Reserve (Long-Term Holds or Holds from Rate Plan) - amount of funds calculated based on the rate plan hold. Max Rolling Reserve - a limit on the amount of Rolling Reserve. | .. image:: ../../_static/images/get_balance/MaxRR.png :alt: Max Rolling Reserve :align: center :width: 870 | Max Rolling Reserve can be changed in the Change Max Rolling Reserve window that appears. To set or edit the Max Rolling Reserve, click on the value :ex:`-`. | .. image:: ../../_static/images/get_balance/ChangeMaxRR.png :alt: Change Max Rolling Reserve :align: center :width: 400 .. Warning:: Rolling reserve will be credited to balance on :ex:`Transaction Date + Period from Rate Plan + 1 day`. When the Max Rolling Reserve limit is reached, the total amount of hold funds will not increase and the Rolling Reserve calculated from next transactions will be added to balance live instead. Also, If the Max Rolling Reserve is set later and is less than the current accumulated Rolling Reserve, then the Rolling Reserve calculated from next transactions will be added to the balance live. .. _endpoint_setting: Endpoint Setting ~~~~~~~~~~~~~~~~ There is possibility to selecting one or more endpoints for each balance, according to which balance will be calculated. Endpoint can be added when creating a balance: | .. image:: ../../_static/images/get_balance/adding_account_balance_new.png :alt: add acc balance :align: center :width: 400 | Or it can be specified for an existing balance by clicking on one of the area highlighted in the picture: | .. image:: ../../_static/images/get_balance/accbeditnew.png :alt: acc debit :align: center :width: 870 | This picture also displays the difference between the balances configured with and without the specified Endpoint. .. _currencies_balances: Multiple Balances In One Currency ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There can be several balances configured for the same currency. In this case, only one of the balances can be without the specified Endpoints. When creating all subsequent balances, it is mandatory to specify the Endpoint. The calculation is made for each balance separately: the balance without the specified Endpoints is counted only for those Endpoints for which a separate balance has not been created. | .. image:: ../../_static/images/get_balance/editbalancenew.png :alt: edit balance :align: center :width: 400 .. _account_configuration_override: Account configuration override ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There is possibility to change configuration for every balance (not for all Merchant's balances). For this case need to press :code:`Configuration` button as in the picture below: | .. image:: ../../_static/images/get_balance/confoverridenew.png :alt: conf over ride :align: center :width: 870 | And after this press the :code:`Add` button: .. image:: ../../_static/images/get_balance/overrideaddnew.png :alt: over ride add :align: center :width: 870 | In this window can be changed the balance settings as well as in the :ex:`Configuration` .. warning:: If at least one operation type is overrode, balance will count by overrode configuration and only for overrode operations. If there is no override for operation types, than balance will counts by main configuration. Example: For balance 191 Sale and Payout operations are overrode, that means for this balance main configuration doesn't affect. .. image:: ../../_static/images/get_balance/confoverridedone.png :alt: conf over ride done :align: center :width: 750 To remove :ex:`configuration override` press :code:`Remove all` button and confirm the deletion. Creation Date Changing ~~~~~~~~~~~~~~~~~~~~~~ To change balance created date press :code:`Change created date` button: .. image:: ../../_static/images/get_balance/change_date_account_balance_new.png :alt: change date account balance :align: center :width: 870 Select date of creation and press :code:`Update` button: | .. image:: ../../_static/images/get_balance/change_date_confirm_account_balance_new.png :alt: change date confirm account balance :align: center :width: 300 | After changing the creation date, use :ref:`reconciliation` to recalculate the balance. Export Balance Transactions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ To use Balance reconciliation press on :code:`Reconciliation balance` button: .. image:: ../../_static/images/get_balance/recexbutnew.png :alt: rece xbut :align: center :width: 870 | | To export balance transactions press on :code:`Export Transactions` button and select transactions' period: | .. image:: ../../_static/images/get_balance/recexbut1new.png :alt: rece xbut :align: center :width: 870 | .. image:: ../../_static/images/get_balance/period_field_new.png :alt: period field :align: center :width: 500 | .. note:: The maximum period is 31 days. .. note:: The date is counted as :ex:`[day_From, day_To)`, so the last day will not be included in the interval. CSV file contains the following fields: | .. image:: ../../_static/images/get_balance/balanceexp.png :alt: balance exp :align: center :width: 870 | .. warning:: "Reserve date" and "STH date" fields are the date and time when amount will affect the balance. The STH date in report doesn't count hourly period described in balance types. .. _accounts_reconciliation: Balance Reconciliation ~~~~~~~~~~~~~~~~~~~~~~ Reconciliation allows to recalculate balance after changes. To reconcile balance press 3 dots near balance then :code:`Reconciliation Balance` button and after :code:`Reconcile` button: | .. image:: ../../_static/images/get_balance/recexbutnew.png :alt: rece xbut :align: center :width: 870 | .. note:: Only Total and Live balances are reconciled. RR and STH can not be reconciled; their amount will be credited to live balance according to the configuration at the time the transaction was created. :code:`Move Rolling Reserve` allows to manually transfer the Rolling Reserve to the active balance, before the release date of the holding. To move Rolling Reserve press 3 dots near balance then :code:`Move Rolling Reserve` button: | .. image:: ../../_static/images/get_balance/move_rolling_reserve.png :alt: rece xbut :align: center :width: 870 | Adjustments ^^^^^^^^^^^ Adjustments allows to change balances amount without making any transactions. List of adjustments and full adjustment amount can be viewed by clicking on :code:`Adjustments` button: | .. image:: ../../_static/images/get_balance/adjnew.png :alt: adj :align: center :width: 870 | For the convenience of users, adjustments can be sorted by ID using the button below: | .. image:: ../../_static/images/get_balance/adjIDfilter.png :alt: adj ID filter :align: center :width: 870 Manual Adjustment ~~~~~~~~~~~~~~~~~ Adjustment amount and external source of the adjustment are mandatory. :code:`Adjustments` for balance can be made via :code:`Add+` button: | .. image:: ../../_static/images/get_balance/adjclicknew.png :alt: adj click :align: center :width: 870 | When adding adjustment, next fields can be specified: * Adjustment amount * External ID * External source * External info .. note:: :code:`Adjustment amount` and :code:`External source` are mandatory fields: | .. image:: ../../_static/images/get_balance/adjaddnew.png :alt: add adj :align: center :width: 400 Adjustment API ~~~~~~~~~~~~~~ In addition to manual adjustments, it is possible to make adjustments via API. To do this, a :code:`tsv` has to be created, zipped and sent via the API. API command with examples is specified in the `integration documentation `_. Export Adjustments ~~~~~~~~~~~~~~~~~~ To export all adjustments for specific balance press the :code:`Export` button, specify period of time and after that press :code:`Export` button. The csv file of adjustments will download automatically. .. note:: The maximum period is 31 days Downloaded file contains next fields: * Create Date * Adjustment Amount * Adjustment Application Date * External Adjustment Unique Id * External Source Name * External Adjustment Info The first line of the file contains the period and the sum of all adjustments. .. image:: ../../_static/images/get_balance/adj_ex.png :alt: adj ex :align: center :width: 870 Scheduled Adjustment ~~~~~~~~~~~~~~~~~~~~ This functionality helps to configure a monthly/weekly fee, which can be set up on the appointed dates every month/week. :code:`Scheduled` for balance adjustments can be made via :code:`Add+` button : | .. image:: ../../_static/images/get_balance/scheduledadd.png :alt: scheduled add :align: center :width: 870 | When adding adjustment, next fields can be specified: * Date of first adjustment * Date of last adjustment * Amount * Currency * Automatically stop creating adjustments when a merchant is disabled * Automatically stop making adjustments when balance goes negative or zero * I am aware that the creation of such an adjustment can significantly affect the balance of the merchant, and lead to its uncontrolled change in the long term, which can cause financial losses due to the possibility of unlimited withdrawal of funds due to an uncontrolled increase of the merchant balance. **This checkbox is mandatory** | .. image:: ../../_static/images/get_balance/scheduledadd1.png :alt: scheduled add1 :align: center :width: 870 :code:`Status` indicates whether the adjustment is active or not. It can also be turned on or off by clicking on it: | .. image:: ../../_static/images/get_balance/scheduledstatus.png :alt: scheduled status :align: center :width: 870 | :code:`ID` is unique identifier of the scheduled adjustment: | .. image:: ../../_static/images/get_balance/scheduledid.png :alt: scheduled id :align: center :width: 870 | :code:`Period` shows which schedule is selected for the following adjustment: | .. image:: ../../_static/images/get_balance/scheduledperiod.png :alt: scheduled period :align: center :width: 870 | :code:`Date` shows time interval from first adjustment to the last adjustment: | .. image:: ../../_static/images/get_balance/scheduleddate.png :alt: scheduled date :align: center :width: 870 | :code:`Next schedule date` shows when is the next scheduled adjustment: | .. image:: ../../_static/images/get_balance/schedulednextdate.png :alt: scheduled next date :align: center :width: 870 | :code:`Last run date` shows when was the last scheduled adjustment: | .. image:: ../../_static/images/get_balance/scheduledlastate.png :alt: scheduled lastate :align: center :width: 870 | :code:`Amount` shows the adjustment amount: | .. image:: ../../_static/images/get_balance/scheduledamount.png :alt: scheduled amount :align: center :width: 870 | :code:`Automatic` shows in which conditions scheduled adjustment will be stopped: | .. image:: ../../_static/images/get_balance/scheduledautomatic.png :alt: scheduleda utomatic :align: center :width: 870 | :code:`Edit` can be used to edit scheduled adjustment: | .. image:: ../../_static/images/get_balance/schedulededit.png :alt: scheduled edit :align: center :width: 870 | :code:`Delete` can be used to delete scheduled adjustment: | .. image:: ../../_static/images/get_balance/scheduleddelete.png :alt: scheduled delete :align: center :width: 870