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
| 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
| 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
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
| 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
| Get balance by Endpoint ID Request Parameters | Mandatory | Description |
|---|---|---|
| balance-provider | Mandatory | Input your balance provider. |
Response Parameters¶
Note
| Get balance by Endpoint ID Response Parameters | Description |
|---|---|
| balance-amount | Current balance. |
Response Example¶
balance-amount=29.99
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
| 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
| 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
| 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},
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
| 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.
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.
- Current Balance - calculated value from configuration including STH and Rolling reserves.
- Balance Live - calculated value from configuration excluding STH and Rolling reserves. Live = current - STH - RR.
- 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.
Date bumping function has four parameters:
- ASAP - crediting funds without delay. Doesn’t include STH and Rolling Reserve.
- ASAP_plus_RR - crediting funds ASAP and counts Rolling reserve. Doesn’t include STH.
- BDAY + n - crediting funds from STH after N business days + Rolling Reserve.
- DAY + n - crediting funds from STH after N days + Rolling Reserve.
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:
Also by clicking on the area highlighted in the picture:
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. :
For balance 191 Sale and Payout operations are refactored, that means for this balance main configuration doesn’t affect.
UI Example:
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.
Alternatively, adjustments requests via API are available. Please refer to the Adjustments parameters and file example. Added adjustments as seen in the UI:
For better user experience adjustments can be sorted by creation date using the button from below:
To change balance created date use Change created date button.
Reconciliation and Export transaction are available per balance.
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:
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.
CSV file contains the following fields:
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.
The first line of the file contains the date and the sum of all adjustments.
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.
- 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)
Default balance for manager must be selected by clicking on Def.
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.
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 :
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
Status indicates whether the adjustment is active or not. It can also be turned on or off by clicking on it:
ID is unique identifier of the scheduled adjustment:
Period shows which schedule is selected for the following adjustment:
Date shows time interval from first adjustment to the last adjustment:
Next schedule date shows when is the next scheduled adjustment:
Last run date shows when was the last scheduled adjustment:
Amount shows the adjustment amount:
Automatic shows in which conditions scheduled adjustment will be stopped:
Edit can be used to edit scheduled adjustment:
Delete can be used to delete scheduled adjustment:
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.
|