# Balance request

The method returns **project balances** for the partner: funds available for payouts, expected credits, and held amounts. Use it to check limits before [payouts](/en/pages/payout-types).

HTTP request format is in [API request format](/en/pages/init-request).

## How it works

1. **Request** — your server calls `get_balance` with `partner_id` and `sign` signature.
2. **Verification** — the API verifies the signature and partner permissions.
3. **Response** — JSON with a `project_balance` list per project.


## Technical details

|  |  |
|  --- | --- |
| **Endpoint** | `https://api.1payment.com/get_balance` |
| **Methods** | `GET`, `POST` |
| **Response format** | JSON |


## Request parameters

### Required

| Parameter | Type | Description |
|  --- | --- | --- |
| `partner_id` | Integer | Your unique ID in the 1Payment system. |
| `sign` | String | Request signature (see "Signature" section). |


## Signature generation (`sign`)

Signature: MD5, lowercase (hex). General rules — [API request format](/en/pages/init-request#request-signature-sign).

**Formula:**


```text
MD5(get_balance + <parameters_without_sign_in_alphabetical_order_joined_by_&> + <API_KEY>)
```

**Example string before hashing:**


```text
get_balancepartner_id=1234secret_key
```

### Signature verification in the documentation

## Request examples

Node.js

```javascript
const crypto = require('crypto');
const axios = require('axios');

async function getBalance(apiKey, partnerId) {
  const params = { partner_id: partnerId };

  // 1. Сортировка параметров по алфавиту
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  // 2. Подпись с префиксом get_balance
  const baseString = `get_balance${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  // 3. GET-запрос
  const response = await axios.get('https://api.1payment.com/get_balance', { params });
  return response.data;
}

const apiKey = process.env.ONEPAYMENT_API_KEY;
getBalance(apiKey, 1234).then(console.log);
```

Python

```python
import hashlib
import os
import requests

def get_balance(api_key: str, partner_id: int) -> dict:
    params = {"partner_id": partner_id}

    # 1. Сортировка параметров
    sorted_keys = sorted(params.keys())
    query_string = "&".join(f"{k}={params[k]}" for k in sorted_keys)

    # 2. Подпись get_balance
    base_string = f"get_balance{query_string}{api_key}"
    params["sign"] = hashlib.md5(base_string.encode("utf-8")).hexdigest()

    # 3. GET-запрос
    response = requests.get("https://api.1payment.com/get_balance", params=params)
    response.raise_for_status()
    return response.json()

api_key = os.environ["ONEPAYMENT_API_KEY"]
print(get_balance(api_key, 1234))
```

PHP

```php
<?php

function getBalance(string $apiKey, int $partnerId): string
{
    $params = ['partner_id' => $partnerId];

    // 1. Сортировка параметров по алфавиту
    ksort($params, SORT_LOCALE_STRING);
    $tail = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign') {
            continue;
        }
        $tail .= "{$k}={$v}&";
    }
    $tail = substr($tail, 0, -1);

    // 2. Формирование подписи (префикс get_balance)
    $params['sign'] = md5('get_balance' . $tail . $apiKey);

    // 3. Запрос к API
    $url = 'https://api.1payment.com/get_balance?' . http_build_query($params);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}

$apiKey = getenv('ONEPAYMENT_API_KEY');
echo getBalance($apiKey, 1234);
```

cURL

```bash
# Подпись: md5("get_balance" + partner_id=1234 + API_KEY)

curl -sS "https://api.1payment.com/get_balance?partner_id=1234&sign=PASTE_MD5_HEX"
```

## API response

Successful response (`200`):


```json
{
  "project_balance": [
    {
      "project_id": 123,
      "currency": "RUB",
      "payout_balance": 100,
      "hold": 0
    },
    {
      "project_id": 456,
      "currency": "USD",
      "payout_balance": 200,
      "expected_balance": 400,
      "hold": 0
    }
  ]
}
```

| Field | Description |
|  --- | --- |
| `project_balance` | Array of balances per partner project. |
| `project_id` | Project ID. |
| `currency` | Currency (ISO 4217). |
| `payout_balance` | Funds available for payouts at the moment. |
| `expected_balance` | Expected balance after all funds are credited (if provided). |
| `hold` | Held amount. |


Request error (`400`):


```json
{
  "error_code": 2
}
```

`error_code` meanings — in [Error codes (API)](/en/pages/error-codes-api). Insufficient payout funds in other methods may return code `9`.

## Related sections

- [Payout types](/en/pages/payout-types)
- [Payout status](/en/pages/payouts/status)