REST API · JWT

`rest-balance` REST API: пополнение баланса через ЮKassa

Служебные методы мобильного приложения Пиксель Тулс: через них оно пополняет баланс пользователя оплатой в ЮKassa. Сам платёж приложение создаёт в своём магазине ЮKassa, а эти методы заводят счёт в Пиксель Тулс, связывают его с платежом и зачисляют деньги после оплаты. Для сторонних интеграций они не подходят — пополнить баланс можно в личном кабинете.

Адрес: /api-rest/balance/<метод>
Авторизация: JWT в заголовке token
Назначение: служебные, для мобильного приложения

Счёт на пополнение

POST /api-rest/balance/add

Заводит неоплаченный счёт на сумму в рублях и отдаёт его номер. Если за последние 50 минут уже есть неоплаченный счёт на ту же сумму, ещё не связанный с платежом, вернётся он — повторное нажатие «Оплатить» не плодит счета. Номер передаётся в метаданные платежа ЮKassa как balance_hid.

Параметры query и JSON-тело

token string обязательный заголовок

Access token из user/auth.
sum int обязательный

Сумма пополнения, целые рубли, больше нуля.

Ответ

data.payment_id int

Номер счёта в Пиксель Тулс — для balance/update.

POST /api-rest/balance/add

curl -X POST 'https://tools.pixelplus.ru/api-rest/balance/add' \
  -H 'token: ВАШ_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
      "sum": 1000
  }'

<?php
$url = 'https://tools.pixelplus.ru/api-rest/balance/add';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'sum' => 1000,
    ]),
    CURLOPT_HTTPHEADER => ['token: ВАШ_JWT', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api-rest/balance/add",
    headers={
        "token": "ВАШ_JWT",
    },
    json={
        "sum": 1000,
    },
    timeout=60,
)
print(response.json())

token обязательный заголовок JWT из ответа user/auth token обязательный заголовок Access token из user/auth sum обязательный Сумма пополнения, целые рубли, больше нуля

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "status": "success",
    "message": "Request successful",
    "code": 200,
    "data": {
        "payment_id": 110616
    },
    "dt": "2026-10-06 12:00:00"
}

Привязка платежа ЮKassa к счёту

POST /api-rest/balance/update

Записывает в счёт ID созданного платежа ЮKassa — с префиксом kassa_m_payment_. Привязать можно только свой неоплаченный счёт и только один раз.

Параметры query и JSON-тело

token string обязательный заголовок

Access token из user/auth.
payment_id int обязательный

Номер счёта из balance/add.
external_id string обязательный

ID платежа в ЮKassa.

Ответ

В data — счёт после изменения, строка журнала баланса.

data.id string

Номер счёта.
data.ext_id string

Привязанный платёж: kassa_m_payment_<ID ЮKassa>.
data.user_id, data.sum, data.date string

Пользователь, сумма в рублях, дата создания счёта.
data.type string

1 — пополнение.
data.status string

2 — ждёт оплаты, 1 — зачислен.

POST /api-rest/balance/update

curl -X POST 'https://tools.pixelplus.ru/api-rest/balance/update' \
  -H 'token: ВАШ_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
      "payment_id": 110616,
      "external_id": "2e8a7f3c-000f-5000-9000-1b2c3d4e5f60"
  }'

<?php
$url = 'https://tools.pixelplus.ru/api-rest/balance/update';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'payment_id' => 110616,
        'external_id' => '2e8a7f3c-000f-5000-9000-1b2c3d4e5f60',
    ]),
    CURLOPT_HTTPHEADER => ['token: ВАШ_JWT', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api-rest/balance/update",
    headers={
        "token": "ВАШ_JWT",
    },
    json={
        "payment_id": 110616,
        "external_id": "2e8a7f3c-000f-5000-9000-1b2c3d4e5f60",
    },
    timeout=60,
)
print(response.json())

token обязательный заголовок JWT из ответа user/auth token обязательный заголовок Access token из user/auth payment_id обязательный Номер счёта из balance/add external_id обязательный ID платежа в ЮKassa

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "status": "success",
    "message": "Request successful",
    "code": 200,
    "data": {
        "id": "110616",
        "ext_id": "kassa_m_payment_2e8a7f3c-000f-5000-9000-1b2c3d4e5f60",
        "user_id": "1001",
        "type": "1",
        "sum": "1000",
        "date": "2026-10-06 11:58:17",
        "status": "2",
        "dt_update": "2026-10-06 12:00:00"
    },
    "dt": "2026-10-06 12:00:00"
}

Подтверждение оплаты

POST /api-rest/balance/confirm

Вызывается после оплаты. Сервер сам запрашивает платёж в ЮKassa и зачисляет деньги, только если платёж в статусе succeeded, а счёт из его метаданных (balance_hid, user_id, sum) ещё не оплачен и совпадает по пользователю и сумме. Если пользователь согласился сохранить карту, она привязывается для автоплатежей.

Параметры query и JSON-тело

token string обязательный заголовок

Access token из user/auth.
external_id string обязательный

ID платежа в ЮKassa — без префикса.
source string обязательный

Платёжная система.

yookassa
ЮKassa — единственное значение

Ответ

Успех — code: 200, data пустой. Новый баланс — в user/state/get.

POST /api-rest/balance/confirm

curl -X POST 'https://tools.pixelplus.ru/api-rest/balance/confirm' \
  -H 'token: ВАШ_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
      "external_id": "2e8a7f3c-000f-5000-9000-1b2c3d4e5f60",
      "source": "yookassa"
  }'

<?php
$url = 'https://tools.pixelplus.ru/api-rest/balance/confirm';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'external_id' => '2e8a7f3c-000f-5000-9000-1b2c3d4e5f60',
        'source' => 'yookassa',
    ]),
    CURLOPT_HTTPHEADER => ['token: ВАШ_JWT', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/api-rest/balance/confirm",
    headers={
        "token": "ВАШ_JWT",
    },
    json={
        "external_id": "2e8a7f3c-000f-5000-9000-1b2c3d4e5f60",
        "source": "yookassa",
    },
    timeout=60,
)
print(response.json())

token обязательный заголовок JWT из ответа user/auth token обязательный заголовок Access token из user/auth external_id обязательный ID платежа в ЮKassa — без префикса source обязательный Платёжная система

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "status": "success",
    "message": "Request successful",
    "code": 200,
    "data": [],
    "dt": "2026-10-06 12:00:00"
}

Ошибки

Код	Сообщение	Когда
`470`	`incorrect request sum`	`add`: сумма не передана, не число или не больше нуля. Подробности — в `data.errors`.
`440`	`empty payment id`	`update`: нет `payment_id`.
`450`	`empty external id`	`update`: нет `external_id`.
`404`	`incorrect payment id`	`update`: счёта с таким номером нет.
`403`	`access denied`	`update`: счёт другого пользователя.
`460`	`forbidden to change confirmed balance item`	`update`: счёт уже оплачен.
`470`	`forbidden to change balance item`	`update`: к счёту уже привязан платёж.
`404`	`empty external payment id`	`confirm`: нет `external_id`.
`403`	`unavailable source`	`confirm`: `source` не `yookassa`.
`500`	`confirm payment error`	`confirm`: платёж не оплачен, не найден в ЮKassa, уже зачислен или метаданные не совпали со счётом.
`401`	`Token is not authorized`	Нет заголовка `token` или токен недействителен — см. rest-auth.

Ответ с ошибкой

{
    "status": "error",
    "message": "incorrect request sum",
    "code": 470,
    "data": {
        "errors": [
            "поле «Сумма» Должна быть больше 0"
        ]
    },
    "dt": "2026-10-06 12:00:00"
}

Порядок вызовов

balance/add — получить номер счёта.
Создать платёж в ЮKassa с метаданными balance_hid (номер счёта), user_id и sum.
balance/update — связать счёт с ID платежа.
После оплаты — balance/confirm. Повторный вызов для уже зачисленного платежа вернёт 500, деньги дважды не зачисляются.

Платёж проверяется в магазине ЮKassa мобильного приложения — платежи, созданные в другом магазине, подтвердить не получится.

rest-balance REST API: пополнение баланса через ЮKassa

Счёт на пополнение

Параметры query и JSON-тело

Ответ

Привязка платежа ЮKassa к счёту

Параметры query и JSON-тело

Ответ

Подтверждение оплаты

Параметры query и JSON-тело

Ответ

Ошибки

Порядок вызовов

`rest-balance` REST API: пополнение баланса через ЮKassa