Перевод баланса

POST https://gptunnel.ru/api/v1/balance/transfer

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

user_id — деньги приходят на личный счёт пользователя;
org_id — деньги приходят на счёт организации.

Операция атомарна: либо списание и зачисление проходят вместе, либо не проходит ничего. Перевод виден отправителю в разделе «Журнал» кабинета организации, получателю — в истории операций как «Перевод».

Headers

Параметр	Тип	Описание
`Authorization`*	`string`	API ключ организации
`Idempotency-Key`*	`string`	Уникальный ключ операции, 8–64 символа A-Za-z0-9_-
`Content-Type`*	`string`	application/json

Параметры запроса

Параметр	Тип	Описание
`user_id`	`string`	ID пользователя-получателя, 24 hex-символа строчными. Ровно одно из user_id и org_id
`org_id`	`string`	ID организации-получателя, 24 hex-символа строчными. Ровно одно из user_id и org_id
`amount`*	`number`	Сумма в рублях, больше 0 и не более 100 000, до 2 знаков после запятой

Пример запроса

curl --request POST \
  --url https://gptunnel.ru/api/v1/balance/transfer \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Idempotency-Key: order-2026-10-20-000153' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "6ad72133269dc8d9f75a33bc",
    "amount": 500
}'

import axios from 'axios'

const response = await axios({
  method: 'POST',
  url: 'https://gptunnel.ru/api/v1/balance/transfer',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Idempotency-Key': 'order-2026-10-20-000153',
  },
  data: {
    user_id: '6ad72133269dc8d9f75a33bc',
    amount: 500,
  },
})

console.log(response.data)

import requests

response = requests.post(
    'https://gptunnel.ru/api/v1/balance/transfer',
    headers={
        'Authorization': 'YOUR_API_KEY',
        'Idempotency-Key': 'order-2026-10-20-000153',
    },
    json={
        'user_id': '6ad72133269dc8d9f75a33bc',
        'amount': 500,
    },
)

print(response.json())

Ответ

Поля ответа

Параметр	Тип	Описание
`code`	`number`	0 при успехе
`transaction_id`	`string`	Ваш Idempotency-Key из запроса — по нему перевод ищется в истории операций и в журнале
`org_id`	`string`	Организация-отправитель
`recipient_user_id`	`string \| null`	Пользователь-получатель, если переводили по user_id
`recipient_org_id`	`string \| null`	Организация-получатель, если переводили по org_id
`recipient_created`	`boolean`	Всегда false при переводе по id
`amount`	`number`	Сумма, зачисленная получателю, в рублях
`currency`	`string`	Всегда RUB
`discount_percent`	`number`	Партнёрская скидка на перевод в процентах, 0 если не назначена
`discount_amount`	`number`	Сумма скидки, возвращённая на баланс отправителя отдельной операцией
`created_at`	`string`	Время операции, ISO 8601
`replayed`	`boolean`	true, если это повтор по тому же Idempotency-Key

{
  "code": 0,
  "transaction_id": "order-2026-10-20-000153",
  "org_id": "6ad5e0c3269dc8d9f75a1f07",
  "recipient_user_id": "6ad72133269dc8d9f75a33bc",
  "recipient_org_id": null,
  "recipient_created": false,
  "amount": 500,
  "currency": "RUB",
  "discount_percent": 0,
  "discount_amount": 0,
  "created_at": "2026-10-20T09:15:42.000Z",
  "replayed": false
}

{
  "code": 19,
  "message": "Insufficient funds on the organization balance."
}

{
  "code": 20,
  "message": "Idempotency-Key was already used with a different request body."
}

Партнёрская скидка

Если организации назначена скидка на переводы, получатель всё равно получает полную сумму amount. С отправителя списывается полная сумма, а скидка возвращается на его баланс отдельной операцией «Скидка на перевод» — её размер приходит в discount_amount. Так в истории операций видны и оборот, и размер скидки.

Ошибки

HTTP	code	Когда
400	3	Тело не по схеме: нет получателя, указаны оба, сумма вне диапазона. Подробности — в поле `details`
400	18	Получатель совпадает с организацией-отправителем
400	21	Нет заголовка `Idempotency-Key` или он не по формату
403	16	Тумблер на ключе включён, но организация не может переводить: переводы выключены, организация удалена или обслуживается через дистрибьютора
403	22	На ключе выключен тумблер «Переводы»; ключ личного аккаунта тоже получает этот код
404	17	Пользователь по `user_id` не найден
404	23	Аккаунт пользователя удалён
404	24	Организация по `org_id` не найдена
404	25	Организация-получатель удалена
409	20	`Idempotency-Key` уже использован с другим телом
422	19	Не хватает средств с учётом кредитного лимита

Одновременные переводы одной организации выполняются по очереди, отдельного кода ошибки для них нет. Если два запроса с одним Idempotency-Key пришли одновременно, второй дождётся первого и вернёт его результат с replayed: true (или 409, код 20, если тело другое).

Полный список кодов и ответ 401 на неверный ключ — в справочнике ошибок.