Balance

The balance request returns the MID balance value in the system of your acquiring bank (or provider).

Info

This request doesn't return your balance in the Overpay system.

Request

Info

The ability to execute the balance request and the request parameters depend on the acquiring bank. Some banks require parameter account, some banks require currency. Please contact your account manager to confirm if the request can be executed and to clarify which parameters are required.

To get the balance, send a POST request to https://gateway.overpay.io/balance with the X-API-Version: 2 header and the following parameters:

Note

The request body must be wrapped in a top-level request{} object.


account conditionally required	string Account number. If empty, the system returns the balance of the default account.
currency conditionally required	string Currency in ISO-4217 format, for example, `USD`.
gateway_id conditionally required	string Gateway ID in the Overpay system.

Example of the balance request by account number

{
   "request":{
      "account":"40701810842020395221"
   }
}

Request example if balance is requested by currency

{
   "request":{
      "currency":"USD"
   }
}

Example of the request if the balance is requested by the gateway ID

{
   "request":{
      "gateway_id":"1"
   }
}

Response

status

required

string
Status of response.

required

object
Balance result.

gatewayId required	integer Gateway ID in the Overpay system.
account	string Account number.
amount	integer Account balance in minimal currency units.
currency	string Currency. Provided if the bank returns it, or if the bank processes transactions in one currency only.
bankInfo	object A section of additional information as provided by the bank.

Example of the response

{
   "status": "successful",
   "result": {
      "gatewayId": 5,
      "account": "40701810820020300021",
      "amount": 6623871674,
      "currency": "RUB",
      "bankInfo": {
         "Account": "40701810820020300021",
         "Amount": 66238716.74,
         "Balance": {
         "OperDate": "2021-12-15T00:00:00",
         "Credit": 0.0,
         "CreditRub": 0.0,
         "Debit": 0.0,
         "DebitRub": 0.0,
         "AmountIn": 132339134.78,
         "AmountInRub": 132339134.78,
         "AmountOut": 132339134.78,
         "AmountOutRub": 132339134.78
         }
      }
   }
}

Balance query when the payout control service is activated

If Overpay uses the payout control service and limits the amount of payouts that a merchant can make from a specified gateway in the specified currency, the merchant can obtain the available payout amount using the API request below.

Request

Send a GET request to https://backoffice.overpay.io/shop/channel_balances/?gateway_id={gateway_id}&currency={currency} with the following query parameters:


gateway_id required	integer Gateway ID for your shop in the Overpay system for which you want to retrieve the available payout balance. To get the gateway ID, contact the Tech Support Team or your account manager.
currency	string Gateway currency for which you want to retrieve the available payout balance, in the ISO-4217 alpha-3 code format. For example, `USD`.

Request example

curl --location 'https://backoffice.overpay.io/shop/channel_balances?gateway_id=3405&currency=USD' \
--header 'content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic MT******MDY1' \
--data ''

Response

code

required

string
Transaction processing code.

message

required

string
System message for the merchant with the description of the status code from the code parameter.

friendly_message

required

string
Message for the merchant and the customer corresponding to the code from the code parameter.

object
Object with the information on the available payout balances.

as_of_date

required

string/datetime
Date and time as of which the balances are shown in the following format: YYYY-MM-DDThh:mm:ss.SSSZ in the UTC timezone.

gateway_id

required

integer
Identifier of the gateway for which the payout balances are shown.

array of objects
Array of payout balances.

currencу	string `currency` parameter value for the balance.
available_balance	bigInt Payout balance in minimal currency units of the specified currency.
channel_id	integer Payout channel identifier.
active	boolean Flag indicating whether the payout control service is activated for the gateway in the specified currency.

Response example

{
    "code": "S.0000",
    "message": "Successfully completed.",
    "friendly_message": "Successfully completed.",
    "channel_balances": {
        "as_of_date": "2026-02-16T08:10:10.973Z",
        "gateway_id": 3405,
        "currencies": [
            {
                "channel_id": 1385,
                "currency": "USD",
                "available_balance": 50000,
                "active": false
            }
        ]
    }
}