3.3. Get balance

For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Get balance requests are initiated through HTTPS POST request by using URL in the following format:

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.apropay.com/paynet/api/v2/get-balance/ENDPOINTID – for Get balance transaction by End point ID

Get balance API also supports receiving all current balances values by merchant and by manager login.

https://gate.apropay.com/paynet/api/v2/get-balance/merchant/MERCHANTLOGIN – for Get balance transaction by Merchant login.

https://gate.apropay.com/paynet/api/v2/get-balance/manager/MANAGERLOGIN – for Get balance transaction by Manager login.

3.3.1. Get balance by Merchant login

Request Parameters

In order to initiate a Get balance by Merchant login Merchant sends an HTTPS POST request with the parameters specified in Get balance Request Parameters Table below

Note

Request must have content-type=application/x-www-form-urlencoded.
Get balance by Merchant login Request Parameters Mandatory Description
balance-name Optional Your balance name. If this parameter is omitted, the result will give you all available balances.

Response Parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
Get balance by Merchant login Response Parameters Description
name Balance name.
amount Current balance including STH and Rolling reserve.
online-balance-live-amount Current balance calculated from configuration excluding STH and Rolling reserve. Live = current - STH - RR.
total-short-term-hold-amount Current amount of hold based on Date bumping function.
total-rolling-reserve-amount Current amount calculated from rate plan hold.
currency Currency used for selected balance.
amount-buffer-hold Calculated amount for OUT operations without final status.

Response Example

"name":"BalanceTest1","amount":0.000,"online-balance-live-amount":0.000,"total-short-term-hold-amount":0.000,"total-rolling-reserve-amount":0.000,"currency":"USD","amount-buffer-hold":0.000

Postman Collection

Debug

Using HMAC-SHA1

To reproduce your API call, input all of the data from your original request, including the authentication tokens. Don’t forget to set the nonce and timestamp to the values you used. An OAuth signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your OAuth signature code.

HTTP method
url
parameters
version
consumer key
consumer secret
timestamp
nonce
signature method

normalized parameters
signature base string
signature
authorization header
              
            
              
            
              
            

3.3.2. Get balance by Endpoint ID

Request Parameters

In order to initiate a Get balance by Endpoint ID Merchant sends an HTTPS POST request with the parameters specified in Get balance Request Parameters Table below

Note

Request must have content-type=application/x-www-form-urlencoded.
Get balance by Endpoint ID Request Parameters Mandatory Description
balance-provider Mandatory Input your balance provider.

Response Parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
Get balance by Endpoint ID Response Parameters Description
balance-amount Current balance.

Response Example

balance-amount=29.99

Postman Collection

Debug

Using HMAC-SHA1

To reproduce your API call, input all of the data from your original request, including the authentication tokens. Don’t forget to set the nonce and timestamp to the values you used. An OAuth signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your OAuth signature code.

HTTP method
endpoint
url
parameters
version
consumer key
consumer secret
timestamp
nonce
signature method

normalized parameters
signature base string
signature
authorization header
              
            
              
            
              
            

3.3.3. Get balance by Manager login

Request Parameters

In order to initiate a Get balance by Manager login Merchant sends an HTTPS POST request with the parameters specified in Get balance Request Parameters Table below

Note

Request must have content-type=application/x-www-form-urlencoded.
Get balance by Manager login Request Parameters Mandatory Description
balance-name Optional Your balance name. If this parameter is omitted, the result will give you all available balances.

Response Parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
Get balance Response Parameter Description
name Balance name.
amount Current balance including STH and Rolling reserve.
online-balance-live-amount Current balance calculated from configuration excluding STH and Rolling reserve. Live = current - STH - RR.
total-short-term-hold-amount Current amount of hold based on Date bumping function.
total-rolling-reserve-amount Current amount calculated from rate plan hold.
currency Currency used for selected balance.
merchantLogin Merchant login for the balance.
amount-buffer-hold Calculated amount for OUT operations without final status.

Response Example

"name":"BalanceTest1","amount":0.000,"online-balance-live-amount":0.000,"total-short-term-hold-amount":0.000,"total-rolling-reserve-amount":0.000,"currency":"USD","merchantLogin":"Merchant","externalMerchantIdentifier":null,"amount-buffer-hold":0.000},

Postman Collection

Debug

Using HMAC-SHA1

File example Adjustments parameters and file example

To reproduce your API call, input all of the data from your original request, including the authentication tokens. Don’t forget to set the nonce and timestamp to the values you used. An OAuth signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your OAuth signature code.

HTTP method
url
parameters
version
consumer key
consumer secret
timestamp
nonce
signature method

normalized parameters
signature base string
signature
authorization header
              
            
              
            
              
            

3.3.4. Setting up balances

Balances can be configured for managers and merchants via Accounts tab.

../_images/accountstab.png

There are four balance types:

1. Short term hold(STH) - calculated current amount of hold based on Date bumping function. Example: Transactions passed from 11:01 to 11:59 on one day will be credited at 12:01 on the day on which they should be credited according to the parameter DAY + n or BDAY + n.

../_images/sth.png
  1. Current Balance - calculated value from configuration including STH and Rolling reserves.
../_images/currbalance.png
  1. Balance Live - calculated value from configuration excluding STH and Rolling reserves. Live = current - STH - RR.
../_images/livebalance.png
  1. Rolling reserve(long terms holds, hold from rate plan) - amount calculated from rate plan hold.

Warning

Rolling reserve will be credited to balance on Transaction date + 1 day + period from rate plan.

../_images/rr.png

Date bumping function has four parameters:

  1. ASAP - crediting funds without delay. Doesn’t include STH and Rolling Reserve.
  2. ASAP_plus_RR - crediting funds ASAP and counts Rolling reserve. Doesn’t include STH.
  3. BDAY + n - crediting funds from STH after N business days + Rolling Reserve.
  4. DAY + n - crediting funds from STH after N days + Rolling Reserve.
../_images/date_bump.png

For each balance it’s possible to select one or more End points, according to which it will be calculated. End point can be added when creating a balance:

../_images/addaccbalance.png

Also by clicking on the area highlighted in the picture:

../_images/accbedit.png
../_images/editbalance.png

Balances for which one or more End points are selected are highlighted in green.

Warning

There can be multiple balances in one currency. For this case, only one of the balances can be without the specified End points. When creating all subsequent ones, it is mandatory to specify the End point. The calculation is carried out for each of the balances separately: balance without the specified End points is counted only for those End points for which a separate balance has not been created.

Configuration override function will refactor main configuration. :

../_images/confoverride.png
../_images/overrideadd.png

For balance 191 Sale and Payout operations are refactored, that means for this balance main configuration doesn’t affect.

UI Example:

../_images/confoverridedone.png

Warning

If at least one operation type is refactored balance will count by refactored configuration and only for refactored operations, if there is no refactor for operation type, than balance will count by main configuration.

Adjustments for balance can be made via Add adjustment button. Adjustment amount and external source of the adjustment are mandatory.

../_images/adjclick.png
../_images/addadj.png

Alternatively, adjustments requests via API are available. Please refer to the Adjustments parameters and file example. Added adjustments as seen in the UI:

../_images/adjbut.png

For better user experience adjustments can be sorted by creation date using the button from below:

../_images/adjdatefilter.png

To change balance created date use Change created date button.

../_images/change_date_account_balance.png
../_images/change_date_confirm_account_balance.png

Reconciliation and Export transaction are available per balance.

../_images/recexbut.png

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 Move Rolling Reserve button:


recexbut

Transaction period pops up after clicking on Export transaction button. Please note that the date is counted as [day_From, day_To), so the last part will not be included in the interval.

../_images/period_field.png

CSV file contains the following fields:

../_images/balanceexp.png

Warning

“Reserve date” and “STH date” fields are the date and time when amount will affect balance. For now STH date in report doesn’t count hourly period described in balance types.

The total amount of adjustments and the ability to upload all adjustments to csv is available in Accounts tab.

../_images/adj.png

The first line of the file contains the date and the sum of all adjustments.

../_images/adj_ex.png

Balance configuration example

1. Cick +Add and set up the transaction type and rates, which will add or deduct funds from balance by settings described in Balance rules. Apply direction parameter affects only Rolling reserve. Example: Sale is set as deduct, than balance will be reduced by amount calculated from rate plan chosen for operation type after N days( N = Transaction date + 1 day + period from rate plan ). Optionally, gate and endpoint can be selected - if they are left empty, balance configuration will work for all gates and endpoints of selected merchant.

../_images/addconf.png
  1. Choose which balance is required - Account balances, Processor balance (balances for acquirer can be set), Card mapping balances and Gate group balances (setting balances for specific list of gates)
../_images/adding_account_balance.png

Default balance for manager must be selected by clicking on Def.

../_images/defbut.png

Example of configured balance. First balance is funded by sale transactions and defunded by payout transactions and is set up for USD currency, also merchant rates applied for sale transactions. Second balance has override for sale transactions which will deduct balance with amount calculated from manager rate plan.

../_images/configuredbalance.png

Scheduled Adjustment

This functionality helps to configure a monthly/weekly fee, which can be set up on the appointed dates every month/week. Scheduled for balance adjustments can be made via Add+ button :


scheduledadd

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

scheduledadd1

Status indicates whether the adjustment is active or not. It can also be turned on or off by clicking on it:


scheduledstatus

ID is unique identifier of the scheduled adjustment:


scheduledid

Period shows which schedule is selected for the following adjustment:


scheduledperiod

Date shows time interval from first adjustment to the last adjustment:


scheduleddate

Next schedule date shows when is the next scheduled adjustment:


schedulednextdate

Last run date shows when was the last scheduled adjustment:


scheduledlastate

Amount shows the adjustment amount:


scheduledamount

Automatic shows in which conditions scheduled adjustment will be stopped:


scheduledautomatic

Edit can be used to edit scheduled adjustment:


schedulededit

Delete can be used to delete scheduled adjustment:


scheduleddelete

Balance rules

Transaction type Impact on balance
sale Add
capture Add
dispute Add
chargeback_reversal Add
arbitration Add
payout_cancel Add
chargeback Deduct
prearbitration Deduct
reversal Deduct
payout Deduct
transfer (deposit2card) Deduct
preauth Rate only
cancel Rate only
fraud Rate only
retrieval Rate only
pan_eligibility Rate only
create_card_mapping Rate only
update_card_mapping Rate only
inquire_card_mapping Rate only
delete_card_mapping Rate only
mfo_scoring Rate only
account_verification Rate only
void Rate only

Adjustments parameters and file example

Adjustments must be sent in archived tsv file format.

Balance Adjustment Parameter Description
Credit amount Credit amount.
Debit amount Debit amount.
External ID Adjustment external ID.
External Merchant ID External merchant ID. Set in properties of merchant/manager.
Balance name Balance name. If parameter is not set, default balance is automatically selected.

tsv file example:

10.45               eid1    THIS_IS_EXT_MERCH_ID    Global merchant balance
90.05               eid2    THIS_IS_EXT_MERCH_ID    Global merchant balance

Balance Adjustment Debug

In order to make an adjustment, tsv file must be archived and sent. 7-Zip or similar archiving software is needed in order to use this debugger.

url
Source
Manager login
filename
control key