Оптовые Telegram Stars, Telegram Premium и другие цифровые товары через REST API. Третий тип товара — NFT-подарки Telegram, см. раздел ниже. Модель — предоплата: вы пополняете закупочный баланс, с него списывается партнёрская цена каждого заказа, конечному клиенту продаёте по своей. О программе в целом — партнёрская программа, новости и разборы — блог.
currency:
"13.50", а не 13.5. Для Stars и Premium это доллары США (USDT), currency: "USD", два знака. Для NFT-подарков —
монета TON, currency: "TON", три знака. Строка, а не число, — намеренно: суммы считаются
десятичной арифметикой, и перевод их во float исказил бы копейки.POST /orders с обязательным idempotency_key.
В этот момент с баланса списывается партнёрская цена.Оплату конечного клиента вы принимаете сами, в своей системе. Ваша маржа — разница между вашей ценой и партнёрской.
Цена одинакова для всех партнёров. Уровней, порогов оборота и персональных скидок нет, торга тоже: одна цифра для каждого, кто подключился.
Цены Stars и Premium номинированы в USDT, курс рубля в расчёте не участвует. Значение пересчитывается вслед за рынком, поэтому перед заказом его стоит перечитывать из каталога.
NFT-подарки оцениваются в TON. Цена каждого подарка своя и живёт, пока он в продаже; в неё уже входят перевод
подарка получателю и комиссия сети. Курс TON к доллару в расчёте не участвует: вы платите TON с NFT-баланса, и цена
в TON не зависит от колебаний курса. Справочный эквивалент в долларах (price_usd_ref) — для отчётов, не для оплаты.
Актуальные цены — GET /products. Точная сумма заказа фиксируется в ответе на
POST /orders; поле price_per_star в каталоге — справочное (6 знаков),
перемножать его самостоятельно не нужно.
Балансы закупочные и предоплатные: расходуются только на заказы и выводу не подлежат. Счёт для Stars и Premium ведётся в долларах США (USDT). Счёт для NFT-подарков — отдельный, в монете TON: NFT покупаются только за TON, поэтому и пополняется он только TON. Деньги между счетами не переводятся и не конвертируются: USDT не тратится на NFT, TON — на Stars и Premium.
Как пополнить. В кабинете выберите счёт (USDT или TON), сеть и сумму — сервис назовёт точную сумму с копейками и адрес. Отправьте ровно её: платёж опознаётся по сумме; для TON можно дополнительно указать в комментарии код из заявки — это необязательно и только ускорит разбор, если сумма не совпадёт. USDT принимаем в сетях GRAM (бывший TON), TRC-20, BEP-20, Polygon и Arbitrum One, USDC — в Polygon и Base (1 USDC = $1); TON — только монету TON в сети TON, на отдельный адрес, который выдаётся в кабинете; минимальное пополнение — 10 TON. Зачисление автоматическое, обычно в течение минуты после подтверждения сети; в Arbitrum One и Base — через 15–25 минут, после финализации сети. При пополнении в TRC-20, BEP-20 и Arbitrum One к сумме добавляется комиссия 1 USDT: сумма к отправке называется уже с ней, на баланс зачисляется введённая сумма; в GRAM (бывший TON), Polygon, USDC Polygon и USDC Base комиссии нет.
Не перепутайте адреса. На адрес для USDT зачисляется только USDT (и USDC в Polygon и Base), на адрес для TON — только монета TON. Другие токены и монеты, отправленные на эти адреса, не зачисляются и не возвращаются. USDT отправляйте только в сети, выбранной в заявке: перевод из другой сети (например, Ethereum ERC-20) автоматически не зачисляется.
Активация. Первое пополнение — от $10.00 в USDT или от 10 TON. До него
API-ключ выпустить нельзя, а запросы к API отклоняются с 403 partner_inactive; каталог и цены в кабинете видны сразу после регистрации.
Остатки — GET /me: поле balance (USD) и nft_balance (TON), оба — в объекте balances.
Если на нужном счёте не хватает средств, заказ отклоняется сразу с 402 insufficient_balance (в ответе — currency и
balance этого счёта): деньги не резервируются, заказ не подвисает в ожидании.
База: https://pay.tgsuperstars.com/api/partner/v1. Аутентификация:
Authorization: Bearer pk_live_... (ключ выпускается в кабинете; опционально —
IP-whitelist на ключ). Машиночитаемая спека:
openapi.json.
Идемпотентность: тот же idempotency_key в POST /orders →
тот же заказ и ровно одно списание. Повтор запроса при таймауте безопасен — это основной способ
не потерять и не задвоить заказ.
curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/me
{
"partner_id": 100200300,
"status": "active",
"balance": "42.50",
"currency": "USD",
"balances": {"USD": "42.50", "TON": "12.370"},
"nft_balance": "12.370",
"nft_currency": "TON",
"pricing": {"note": "актуальные цены — GET /products"},
"limits": {"api_rate_limit": {"per_minute": 120, "burst": 30},
"stars_min_per_order": 50,
"stars_max_per_order": 50000,
"nft_max_order_ton": null, "nft_catalog_rate_limit": {"per_minute": 30},
"nft_orders_rate_limit": {"per_minute": 60}}
}
balance — счёт в USD для Stars и Premium; nft_balance — счёт в TON для NFT-подарков. Поля balance/currency сохранены для совместимости и всегда означают долларовый счёт.
curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/products
{
"currency": "USD",
"stars": {"price_per_1000": "…", "price_per_star": "…",
"currency": "USD", "max_per_order": 50000},
"premium": {"3": {"partner_price": "…", "currency": "USD"},
"6": {"partner_price": "…", "currency": "USD"},
"12": {"partner_price": "…", "currency": "USD"}},
"nft": {"available": true, "pricing_model": "per_gift", "currency": "TON", "balance": "nft_balance",
"catalog": "/nft/gifts", "quote": "/nft/gifts/{gift}", "max_order_ton": null}
}
Цен в примере нет: они меняются вместе с рынком, актуальные приходят в этом ответе. Суммы — строки с двумя знаками после точки, price_per_star — с шестью.
NFT-подарки оплачиваются с NFT-баланса в TON (currency: "TON"); цены каталога и котировки — в TON.
Если цена временно недоступна, вместо цен приходит
{"unavailable": true, "reason": "cost_unavailable"} — это не ошибка HTTP,
а честный признак «сейчас не продаём». Заказ в этот момент тоже не примется.
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"type":"stars","username":"@your_customer"}' https://pay.tgsuperstars.com/api/partner/v1/validate/recipient
Для premium ответ дополнительно содержит already_premium: true,
если у получателя прямо сейчас активна подписка. Это не отказ: заказ на такой аккаунт
принимается, но выдача будет отложена — см. Отложенная выдача Premium.
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"type":"stars","idempotency_key":"ord-1","params":{"quantity":100,"recipient":"@your_customer"}}' https://pay.tgsuperstars.com/api/partner/v1/orders
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"type":"premium","idempotency_key":"ord-2","params":{"months":3,"recipient":"@your_customer"}}' https://pay.tgsuperstars.com/api/partner/v1/orders
Если у получателя уже активна подписка Telegram Premium, заказ всё равно принимается. Подписку нельзя вручить поверх действующей, поэтому выдача откладывается и проходит сама, как только текущая подписка получателя закончится. Включать это отдельно не нужно — так работают все ключи.
Деньги списываются с баланса сразу, в момент создания заказа.
Заказ остаётся в статусе processing и раз в сутки автоматически пробует
выдаться. Сколько продлится ожидание, заранее неизвестно: оно равно остатку текущей
подписки получателя и может составить месяцы.
failed, а списанная сумма
автоматически возвращается на ваш баланс.409 deferred_order_exists. Дождитесь выдачи первого — она сама продлевает
подписку получателя, и второй заказ ждал бы ещё дольше.Если отсрочка вам не подходит, вызывайте validate/recipient перед заказом
и не создавайте заказ, когда в ответе already_premium: true.
Допустимые сроки Premium — 3, 6 и 12 месяцев. Третий тип заказа —
nft, коллекционные подарки Telegram, см. раздел ниже.
Других типов нет: type принимает stars, premium и nft.
{
"order_id": "PA-12345",
"type": "stars",
"status": "processing",
"partner_price": "…",
"currency": "USD",
"retail": null,
"quantity": 100,
"recipient": "@your_customer",
"created_at": "2026-08-10T18:20:31.000000",
"refunded": false
}
partner_price — списанная с баланса сумма, строкой. У архивных заказов,
созданных до 10.08.2026, это число в рублях и currency: "RUB";
ориентируйтесь на currency, а не на тип значения.retail — всегда null: розничная цена сайта рублёвая,
в долларовом ответе ей не место. Явный null, а не ноль, чтобы никто
не прочитал его как «бесплатно».quantity — количество звёзд для stars и число месяцев
для premium. Минимальный заказ звёзд — 50; меньшее
количество отклоняется с bad_quantity ещё до списания.GET /orders/{id} и
GET /orders?status=&type=&from=&to=&cursor=&limit=.
Статусы: processing | completed | partial | canceled | failed. Исходящие вебхуки
(order.completed | order.failed | order.refunded) подписаны заголовком
X-Signature: hex(hmac_sha256(body, ваш webhook_secret)) — проверяйте подпись
и обрабатывайте идемпотентно (доставка «как минимум один раз»). Метод, заголовки, примеры тела и
проверка подписи — в разделе Вебхуки.
Адрес доставки (webhook_url в теле заказа или адрес из кабинета) проверяется
дважды. На входе — мгновенно и без DNS: схема, хост, порт, отсутствие логина/пароля,
литеральный адрес; негодный адрес даёт 400 bad_webhook_url с машинной причиной в
reason, заказ при этом не создаётся. Перед КАЖДОЙ попыткой доставки адрес
проверяется ещё раз, уже с резолвом: если хост разрешается в локальный, приватный или
внутренний адрес, попытка не делается вовсе (в истории доставок status=failed,
rejected_reason), а соединение идёт ровно в проверенный адрес — между проверкой и
запросом DNS не перечитывается. Переезд домена или сбой DNS попытку не сжигают: она повторяется
по расписанию 1м/5м/30м/2ч/6ч. Поле label в ответах всегда по-русски.
Итог заказа мы присылаем на ваш адрес сами, опрашивать GET /orders/{id} не обязательно.
Адрес и секрет задаются в кабинете: вкладка «API», блок «Webhook» — поле URL и кнопка «Сохранить».
При первом сохранении создаётся секрет; он показывается один раз, сохраните его у себя. Чтобы выпустить
новый, включите «Перегенерировать секрет» и нажмите «Сохранить»: старый секрет перестаёт действовать сразу,
в том числе для повторов уже отправленных вебхуков. Для отдельного заказа адрес можно заменить полем
webhook_url в POST /orders, но секрет всё равно берётся из кабинета: если блок
«Webhook» ещё ни разу не сохраняли, нажмите «Сохранить» один раз, можно с пустым URL. Пока нет адреса или
секрета, вебхуки не отправляются, и события этого периода позже не досылаются — их итог смотрите в
GET /orders/{id}.
В кабинете можно указать до 5 адресов: кнопка «Добавить адрес» в блоке «Webhook». Каждое событие
уходит на все адреса, на каждый — отдельной доставкой: у неё свой X-Webhook-Id, свои попытки
и повторы, а сбой одного адреса не задерживает остальные. Секрет у всех адресов один. Если в заказе
передан webhook_url, события этого заказа уходят только на него, а адреса из кабинета для него
не используются.
POST на ваш адрес, Content-Type: application/json, тело — JSON в UTF-8.
Ответ ждём до 10 секунд. По редиректам не переходим: ответ 3xx считается неуспешным.
| Заголовок | Что в нём |
|---|---|
X-Signature | hex(hmac_sha256(тело, webhook_secret)) — подпись тела |
X-Timestamp | Время отправки в unix-секундах, у каждой попытки своё |
X-Signature-V2 | hex(hmac_sha256(X-Timestamp + "." + тело, webhook_secret)) — подпись
вместе со временем: по ней отсекается повторная отправка перехваченного запроса |
X-Signature-Version | 2 |
X-Webhook-Event | order.completed, order.failed или
order.refunded — то же, что event в теле |
X-Webhook-Id | Идентификатор доставки: строка из 24 hex-символов, одинаковая во всех повторах одного вебхука |
X-Webhook-Attempt | Номер попытки: 1, 2, … |
Подпись считается по сырым байтам тела в том виде, в каком оно пришло. Проверяйте её
до разбора JSON и не собирайте строку заново: в теле есть пробелы после : и ,,
а символы вне ASCII (…, ⭐, кириллица в label) идут в UTF-8 без экранирования.
Пересобранный JSON даст другую подпись.
Всегда {"event": …, "order_id": …, "data": {…}}. В order.completed и
order.failed поле data — объект заказа в том же формате, что в ответе
GET /orders/{id}, но без поля retail. Это снимок заказа на момент события.
Stars, заказ выполнен:
{
"event": "order.completed",
"order_id": "pa_6f1c2a9e-1b7d-4c3e-9a51-2f0d8e4b7c10",
"data": {
"order_id": "pa_6f1c2a9e-1b7d-4c3e-9a51-2f0d8e4b7c10",
"type": "stars",
"status": "completed",
"partner_price": "…",
"currency": "USD",
"quantity": 250,
"recipient": "@your_customer",
"created_at": "2026-10-04T12:59:07.329000",
"completed_at": "2026-10-04T12:59:15.616000+00:00",
"label": "250 ⭐ для @your_customer",
"refunded": false
}
}
Premium — тот же объект с "type": "premium": quantity — число месяцев,
label вида "Telegram Premium 3 мес для @your_customer".
partner_price — сумма, списанная с баланса, строкой в валюте currency.created_at — время UTC; сейчас приходит без смещения, но может прийти и с
+00:00, разбирайте оба варианта. completed_at — со смещением +00:00,
null, пока заказ не выполнен (бывает null и у заказа, закрытого вручную).
Дробной части секунд может не быть: используйте ISO-парсер, а не шаблон с фиксированной дробной частью.label — готовая подпись заказа, всегда по-русски.Заказ не выполнен: деньги автоматически возвращаются на баланс, и приходят два события —
order.refunded и order.failed. Порядок их прихода не гарантирован.
В order.failed — объект заказа со status failed или
canceled и refunded: true, если деньги уже вернулись на баланс. Возврат подтверждает
и отдельное событие order.refunded — у него тело другое:
{
"event": "order.refunded",
"order_id": "pa_6f1c2a9e-1b7d-4c3e-9a51-2f0d8e4b7c10",
"data": {
"order_id": "pa_6f1c2a9e-1b7d-4c3e-9a51-2f0d8e4b7c10",
"refund_amount": 1.23,
"reason": "stars_failed",
"currency": "USD"
}
}
refund_amount — число, а не строка: это исключение из правила о денежных строках,
оставленное ради совместимости. У возврата за NFT (currency: "TON") рядом приходит
refund_amount_ton — та же сумма строкой с тремя знаками; сверяйте деньги по ней.
reason — машинная причина, например stars_failed или premium_canceled.
Если перевод уже отправлен, а подтверждение выдачи не пришло, автоматического возврата нет: заказ уходит
на ручной разбор, и до его окончания вебхуков нет. Всё это время GET /orders/{id} показывает
status: "failed" и refunded: false — это ещё не итог, новый заказ взамен не
создавайте. Если товар дошёл, придёт order.completed и статус сменится на
completed; если нет — придёт возврат.
Доставленным считается любой ответ 2xx (200–299), полученный за 10 секунд. Тело ответа мы не читаем, оно может быть пустым. Всё остальное — 3xx, 4xx, 5xx, таймаут, ошибка соединения — неуспех: повторяем через 1 мин, 5 мин, 30 мин, 2 ч и 6 ч, всего до 6 попыток, затем доставку прекращаем. Отвечайте сразу после проверки подписи, а долгую обработку делайте после ответа.
Доставка «как минимум один раз»: один вебхук может прийти повторно. Отсеивайте дубли по
X-Webhook-Id или по паре order_id + event. Если вебхук так и не дошёл,
статус заказа всегда доступен в GET /orders/{id}.
Python:
import hmac, hashlib, time
def verify(raw_body: bytes, headers, secret: str) -> bool:
key = secret.encode()
sig = hmac.new(key, raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, headers.get("X-Signature", "")):
return False
# X-Signature-V2: подпись вместе со временем отсекает старые запросы
ts = headers.get("X-Timestamp", "0")
sig2 = hmac.new(key, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return (hmac.compare_digest(sig2, headers.get("X-Signature-V2", ""))
and abs(time.time() - int(ts)) < 300)
PHP:
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_TIMESTAMP'] ?? '0';
$sig = hash_hmac('sha256', $raw, $secret);
$sig2 = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')
|| !hash_equals($sig2, $_SERVER['HTTP_X_SIGNATURE_V2'] ?? '')
|| abs(time() - (int)$ts) > 300) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
http_response_code(200);
Node.js (Express; тело нужно получать сырым — express.raw({ type: 'application/json' })):
const crypto = require('crypto');
function verify(raw, headers, secret) {
const hex = (data) => crypto.createHmac('sha256', secret).update(data).digest('hex');
const eq = (a, b) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
const ts = headers['x-timestamp'] || '0';
return eq(hex(raw), headers['x-signature'] || '')
&& eq(hex(Buffer.concat([Buffer.from(ts + '.'), raw])), headers['x-signature-v2'] || '')
&& Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}
Проверить свою реализацию можно на этом примере. Секрет test_secret_123, тело — одна
строка, ровно эти байты:
{"event": "order.completed", "order_id": "pa_6f1c2a9e-1b7d-4c3e-9a51-2f0d8e4b7c10", "data": {"order_id": "pa_6f1c2a9e-1b7d-4c3e-9a51-2f0d8e4b7c10", "type": "stars", "status": "completed", "partner_price": "…", "currency": "USD", "quantity": 250, "recipient": "@your_customer", "created_at": "2026-10-04T12:59:07.329000", "completed_at": "2026-10-04T12:59:15.616000+00:00", "label": "…", "refunded": false}}
Ожидаемые подписи: X-Signature = 894ddfb9144d18d41b2965146364acc36b03295b8318d82951f672ce319bc20e; при X-Timestamp: 1791118800
X-Signature-V2 = dab0cc24bb63dd061ad60abeb7313d909be63541748287f3e2154d48e14c9c3f. Проверку возраста X-Timestamp для этого примера
отключите: время в нём прошедшее.
NFT-подарок — коллекционный подарок Telegram: единичный экземпляр с номером, моделью, фоном и символом, который живёт в сети TON и передаётся от аккаунта к аккаунту. Мы покупаем его на маркете коллекционных подарков и переводим получателю по username; кошелёк и очередь покупок — на нашей стороне. Подарок приходит получателю анонимно: имя отправителя скрыто, ваш бренд и наш сервис получателю не показываются. Платите с NFT-баланса в TON — отдельного счёта, который пополняется только монетой TON (см. Баланс и пополнение). Ключ тот же, что для Stars и Premium.
Каждый подарок — один экземпляр. Цена у каждого своя и живёт, пока подарок
в продаже. Между каталогом и заказом подарок может уйти к другому покупателю — тогда заказ,
как правило, отклоняется ещё до списания с кодом gift_not_for_sale; если продажа
случилась уже после списания, заказ станет failed, и сумма вернётся автоматически.
curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/nft/collections
curl -H "Authorization: Bearer $KEY" "https://pay.tgsuperstars.com/api/partner/v1/nft/gifts?collection=plushpepe&sort=price_asc"
{
"currency": "TON",
"items": [
{"gift": "plushpepe-1234", "name": "Plush Pepe", "num": 1234, "collection": "plushpepe",
"image": "https://…/plushpepe-1234.webp", "price_ton": "…", "partner_price": "5.366", "currency": "TON",
"price_usd_ref": "7.19"}
],
"count": 60, "next_cursor": "60", "source_status": "live"
}
partner_price — ваша цена в TON, она и спишется с NFT-баланса. price_usd_ref — справочный
эквивалент в долларах по текущему курсу, только для ориентира; может быть null, если курс временно
недоступен, — на заказ это не влияет.gift — идентификатор подарка; он же виден в публичной ссылке
t.me/nft/plushpepe-1234. В заказе можно передать и ссылку, и идентификатор.collection обязателен. Страница — до 60 подарков; следующую запрашивайте с
cursor=next_cursor. Порядок — sort=price_asc (по умолчанию) или price_desc.applied_filters в ответе. Там лежит то, что реально применено:
collection, sort и attr. Неизвестное имя параметра
попадает в ignored_params; неизвестное значение атрибута уходит поставщику как
есть, и если он его не знает, лента приходит НЕсуженной. Опечатка в фильтре — это не «нет
подходящих лотов», а «фильтра не было»: сверьте отправленное с применённым, прежде чем
заказывать.attr[Model]=…, attr[Backdrop]=…, attr[Symbol]=…
(можно несколько раз). Атрибуты гарантированно есть в карточке GET /nft/gifts/{gift}.partner_price в каталоге — ориентир на момент ответа. Точная сумма фиксируется
только в POST /orders. source_status: "stale" — данные каталога из кэша,
проверьте карточку перед заказом; "unavailable" — каталог временно недоступен,
items пуст, в ответе reason: "upstream_unavailable" и
retry_after (секунды) — столько и подождите.next_cursor: null — страниц больше нет.curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/nft/gifts/plushpepe-1234
{
"gift": "plushpepe-1234", "name": "Plush Pepe #1234", "num": 1234, "collection": "plushpepe",
"image": "https://…", "attributes": {"model": "Frog Prince", "backdrop": "Emerald", "symbol": "Crown"},
"available": true, "price_ton": "…", "partner_price": "5.366", "currency": "TON", "price_usd_ref": "7.19",
"quoted_at": "2026-09-17T12:00:00+03:00", "max_order_price": null
}
Цена подарка: partner_price — итоговая сумма в TON, одна для всех партнёров;
перевод подарка получателю и комиссия сети в неё уже входят, доплат нет. Округление вверх до 0.001 TON.
Курс TON к доллару в расчёте не участвует: вы платите TON с NFT-баланса, и цена в TON не зависит от
колебаний курса. Справочный эквивалент в долларах (price_usd_ref) — для отчётов, не для оплаты.
available: false означает, что подарок продан или снят с продажи; заказ на него
не примется.
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"type":"nft","username":"@your_customer"}' https://pay.tgsuperstars.com/api/partner/v1/validate/recipient
Получатель должен существовать и быть достижим. Во всех примерах на этой
странице стоит заглушка @your_customer — подставьте реальный username. Ник, который
не резолвится (опечатка, удалённый или скрытый аккаунт), даёт 400 recipient_not_found,
и она идёт РАНЬШЕ цены (синтаксис max_price разбирается первым) — то есть маскирует
ошибку в том же запросе. Проверяйте получателя отдельным вызовом ниже, прежде чем разбирать
остальные отказы.
Тот же резолв, что для Stars: получатель — обычный Telegram-аккаунт, кошелёк ему не нужен.
Это предварительная проверка: окончательно возможность передать подарок именно этому аккаунту
подтверждается при обработке заказа. В редком случае, когда аккаунт найден, но принять подарок не может,
заказ завершается failed со stage: "create", reason: "invalid_recipient"
и полным автоматическим возвратом — деньги не теряются, но проверьте username ещё раз.
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"type":"nft","idempotency_key":"ord-3","params":{"gift":"plushpepe-1234","recipient":"@your_customer","max_price":"5.400"}}' https://pay.tgsuperstars.com/api/partner/v1/orders
{
"order_id": "PA-12345",
"type": "nft",
"status": "processing",
"partner_price": "5.366",
"currency": "TON",
"price_usd_ref": "7.19",
"retail": null,
"quantity": 1,
"recipient": "@your_customer",
"label": "NFT Plush Pepe #1234 для @your_customer",
"created_at": "2026-09-17T12:00:05.120000",
"completed_at": null,
"refunded": false,
"gift": {"gift": "plushpepe-1234", "name": "Plush Pepe #1234", "num": 1234, "collection": "plushpepe",
"image": "https://…", "price_ton": "…",
"attributes": {"model": "Frog Prince", "backdrop": "Emerald", "symbol": "Crown"}},
"delivery": null,
"failure": null
}
label — готовая подпись состава заказа для показа человеку. Склеивать
gift.name с gift.num самостоятельно не нужно: номер уже входит в
name, и такая склейка печатает его дважды.created_at — историческая строка без смещения, величина в
UTC; completed_at (верхнего уровня) и delivery.completed_at —
всегда со смещением. Не вычитайте одно из другого без приведения к UTC: разница выйдет ровно
на ваш часовой пояс. Это ДВА разных момента: верхний completed_at — когда заказ
закрыли мы, delivery.completed_at — когда завершилась выдача. Они могут
отличаться на секунды; для сверки с вашей учётной системой берите верхний.idempotency_key возвращает тот же заказ и заголовок
Idempotent-Replay: true. Ориентируйтесь на этот заголовок, а не на код ответа:
свои побочные эффекты (списание у клиента, запись в свою базу, письмо) по такому ответу
выполнять НЕ нужно.402 insufficient_balance с currency: "TON";
долларовый баланс на NFT не расходуется.params.max_price — необязательный предохранитель в TON: если пересчитанная цена окажется
выше, заказ отклоняется до списания с кодом price_changed и актуальной
ценой в поле current_price. Удобно передавать сюда цену из последней котировки.
Если лот подешевел, спишется меньшая, текущая цена.quantity для nft всегда 1. На один подарок принимается
один активный заказ: повтор на тот же подарок до завершения первого — 409 gift_reserved.POST /orders с type=nft
свой счётчик — 60 запросов в минуту на партнёра (все ваши ключи вместе,
скользящее окно 60 секунд). Он отдельный от счётчика каталога и котировки (30 в минуту
на ключ) и действует помимо общего лимита 120/мин на ключ. Считается каждый запрос на создание
NFT-заказа, в том числе отклонённый, кроме идемпотентного повтора: запрос с
idempotency_key, по которому заказ уже создан, лимит не тратит — повтор после таймаута
доходит всегда. Проверка идёт до обращения к маркету и до резерва подарка. При исчерпании —
429 rate_limited с scope: "nft_orders", limit,
window_seconds, retry_after и заголовком Retry-After (через
столько секунд в окне освободится место); заказ не создаётся, деньги не списываются, подарок не
резервируется — повторите тот же запрос с тем же idempotency_key после паузы.
Заказов Stars и Premium этот счётчик не касается.
Статусы. processing — покупаем и переводим (обычно около минуты; при
сбое маркета или сети заказ ждёт в очереди — в редких случаях до часа); completed — подарок у
получателя и перевод подтверждён сетью, в объекте заказа появляется блок delivery:
"delivery": {"nft_public_url": "https://t.me/nft/plushpepe-1234",
"ton_explorer_url": "https://tonviewer.com/transaction/…",
"transfer_hash": "…", "completed_at": "2026-09-17T12:04:40+03:00"}
failed — подарок не куплен, сумма возвращена на NFT-баланс в TON автоматически (событие
order.refunded, reason: "nft_failed", refund_amount в TON, currency: "TON"), в объекте заказа блок failure с полями stage
и reason. stage ∈ create | confirm | queue | pricing;
reason — один из: gift_not_for_sale (лот ушёл), gift_reserved,
price_above_cap (лот подорожал сверх зафиксированной цены — мы не покупаем дороже),
amount_above_cap, invalid_price, invalid_upstream_price, pricing_failed (цена лота не подтвердилась),
gift_unavailable (маркет не ответил), invalid_recipient,
nft_disabled, hub_rejected, queue_rejected, delivery_failed (прочее).
Все они означают одно: покупки не было, TON вернулись на NFT-баланс.
Если покупка прошла, а перевод получателю — нет, заказ остаётся
в processing и уходит на ручной разбор: мы либо дошлём подарок, либо вернём деньги;
автоматического возврата в этом случае нет, чтобы не вернуть деньги за уже купленный подарок.
Единственное исключение из правила «failed = покупки не было» — итог такого разбора с возвратом:
заказ становится failed со stage ∈ create | purchase | transfer и
reason: "manual_refund", деньги возвращаются событием order.refunded
с reason: "nft_manual_refund".
Напишите в поддержку @partner_stars_bot, если заказ висит дольше часа.
Вебхуки — те же order.completed, order.failed,
order.refunded; в data приходит объект заказа с блоками gift,
delivery, failure.
Коды пополнения PlayStation, Xbox, Nintendo, App Store, Google Play, Steam, Roblox, Netflix, Spotify,
Discord, Battle.net, Valorant, Razer Gold, Amazon и других — с того же долларового баланса и тем же ключом,
что Stars и Premium. Цена — за одну карту, в USD; код приходит, как только заказ станет
completed (обычно за секунды).
curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/giftcards/brands curl -H "Authorization: Bearer $KEY" "https://pay.tgsuperstars.com/api/partner/v1/giftcards?brand=psn®ion=US"
{
"currency": "USD",
"brands": [
{"brand": "psn", "name": "PlayStation", "category": "games",
"regions": [
{"region": "US", "name": "США", "products": [
{"product_id": -301234, "name": "PlayStation 10 USD",
"denomination": {"amount": "10", "currency": "USD"}, "price": "9.32", "currency": "USD"}
]}
]}
],
"updated_at": "2026-11-15T10:00:00+00:00"
}
GET /giftcards/brands — бренды и регионы со счётчиками и ценой «от»; GET /giftcards —
позиции, фильтры brand и region (без фильтров — весь каталог).GET /giftcards/{product_id}, окончательная фиксируется в POST /orders.curl -X POST https://pay.tgsuperstars.com/api/partner/v1/orders \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"type": "giftcard", "params": {"product_id": -301234, "max_price": "9.32"},
"idempotency_key": "gc-0001"}'
max_price — необязательный предохранитель: если цена выросла, заказ отклоняется до списания
с кодом price_changed и новой ценой в current_price.above_limit, до списания); покупки карт за 24 часа —
без лимита.product и delivery. Кода в нём нет — ни в ответе,
ни в вебхуках.curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/orders/pa_…/codes
{"order_id": "pa_…", "product": "PlayStation 10 USD", "region": "US",
"codes": ["XXXX-XXXX-XXXX"], "delivered_at": "2026-11-15T10:00:03+00:00"}
completed ответ — 409 not_delivered; дождитесь вебхука
order.completed или опрашивайте GET /orders/{id}.failed, сумма возвращается на баланс автоматически
(order.refunded). Если поставщик уже мог принять оплату, возврат проходит после ручной сверки —
обычно в течение рабочего дня.Ключи игр, DLC и программ (Steam, Xbox, Nintendo, EA App, Ubisoft Connect, Epic Games, Battle.net, Windows, Office
и другие) и готовые игровые аккаунты (Steam, Epic Games, PlayStation, Xbox) — с того же долларового баланса и тем же
ключом API, что Stars и Premium. Цена — за одну позицию, в USD. Ключ или данные аккаунта доступны, как только заказ
станет completed (обычно за секунды).
curl -H "Authorization: Bearer $KEY" "https://pay.tgsuperstars.com/api/partner/v1/catalog/keys?q=example&country=KZ" curl -H "Authorization: Bearer $KEY" "https://pay.tgsuperstars.com/api/partner/v1/catalog/accounts?platform=Steam&country=RU&compat=1"
{
"type": "key", "currency": "USD", "total": 1834, "page": 1, "limit": 50, "country": "KZ",
"items": [
{"product_id": 48213, "type": "key", "kind": "key", "name": "Example Game Steam CD Key",
"platform": "Steam", "region": "GLOBAL", "dlc": false, "price": "31.40", "currency": "USD",
"in_stock": true, "ru": "no", "available_in": ["KZ", "TR", "US"],
"country": "KZ", "compat": "yes",
"image": "https://partner.tgsuperstars.com/api/partner/media/kg/48213.webp"}
],
"platforms": ["Steam", "Xbox", "…"], "platform_counts": {"Steam": 43227, "Xbox": 2230}
}
q — поиск по названию; platform — из списка platforms;
region — регион ключа (список regions приходит, когда выбрана платформа);
dlc=0|1 — только для ключей; sort=popular|price|price_desc|name|new;
page (до 200) и limit (до 100, по умолчанию 50).country — страна покупателя, две буквы ISO 3166-1 (RU, KZ, DE…).
С ней у каждой позиции есть compat: yes — работает, no — не работает,
unknown — не проверено. compat=1 — только позиции с compat: "yes";
compat=ok — скрыть только неподходящие (no), «не проверено» остаётся.ru — есть у каждой позиции: работает ли товар у покупателя из России (yes / no /
unknown).available_in — у ключей Steam, которые не работают в России: страны, где игра продаётся
(ключ подойдёт аккаунту Steam из этих стран).warranty — только у готовых аккаунтов: условие гарантии, см. ниже.GET /catalog/keys/{product_id} или GET /catalog/accounts/{product_id}
(можно с ?country=), окончательная фиксируется в POST /orders.no — ключ запрещено активировать в этой стране; или игра не продаётся в Steam этой страны (ключи Steam,
проверка раз в сутки); или регион ключа — СНГ, а покупатель из России (регион «СНГ» Россию не включает).unknown — данных не хватает: например, ключ привязан к региону, а список стран к нему не приложен.
Уточните у покупателя страну его аккаунта.curl -X POST https://pay.tgsuperstars.com/api/partner/v1/orders \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"type": "key", "params": {"product_id": 48213, "country": "KZ", "max_price": "31.40"},
"idempotency_key": "kg-0001"}'
type — key (ключи и программы) или account (аккаунты); product_id —
из каталога того же типа.country — страну покупателя. Если товар там точно не работает, заказ отклоняется
до списания: 409 region_mismatch, в ответе country, region и, если есть,
available_in. Купить всё равно можно, добавив "accept_region_risk": true в
params, — тогда претензии о несовместимости с регионом не принимаются. Без country проверки нет.country и accept_region_risk входят в параметры заказа: тот же idempotency_key
с другими значениями — 409 idempotency_key_reuse.max_price — необязательный предохранитель: если цена выросла, заказ отклоняется до списания с
price_changed и новой ценой в current_price.above_limit, до списания); покупки за 24 часа — без лимита.503 product_unavailable с retry_after — повторите
позже или выберите другую. Деньги при этом не списываются.product (в нём buyer_country и
region_compat, если страна передана) и delivery. Ключа и данных аккаунта в нём нет.curl -H "Authorization: Bearer $KEY" https://pay.tgsuperstars.com/api/partner/v1/orders/pa_…/codes
{"order_id": "pa_…", "product": "Example Game Steam CD Key", "region": "GLOBAL",
"codes": ["XXXXX-XXXXX-XXXXX"], "delivered_at": "2026-11-18T10:00:03+00:00"}
{"order_id": "pa_…", "product": "Example Game Steam Account", "region": "GLOBAL",
"credentials": [{"key": "login", "label": "Логин", "value": "…"},
{"key": "password", "label": "Пароль", "value": "…"}],
"codes": ["Логин: …", "Пароль: …"], "delivered_at": "2026-11-18T10:00:03+00:00"}
codes. Аккаунт — в credentials по полям (login, password,
mail, mail_password и другие), в codes — те же данные строками.completed ответ — 409 not_delivered; дождитесь вебхука
order.completed или опрашивайте GET /orders/{id}. Изредка выдачу проверяет оператор —
тогда заказ дольше остаётся в обработке.failed, сумма возвращается на баланс
(order.refunded); если оплата уже могла уйти дальше, возврат проходит после ручной сверки.Условие ниже относится только к готовым аккаунтам (type: "account"). Ключей и подарочных карт оно не
касается.
GET /orders/{id} и вебхуки) поле warranty: "video_from_payment_or_delivery" —
условие, действовавшее в момент покупки.| HTTP | code | Что значит |
|---|---|---|
| 400 | bad_country | country — не двухбуквенный код страны |
| 409 | region_mismatch | Товар не работает в стране покупателя; купить — только с accept_region_risk: true |
| 400 | above_limit | Цена выше лимита одного заказа |
| 409 | price_changed | Цена выше max_price; новая — в current_price |
| 400 | product_unavailable | Позиции нет в каталоге (нет в наличии, снята или дороже лимита) |
| 503 | product_unavailable | Позиция временно недоступна — повторите через retry_after секунд |
| 503 | rate_unavailable | Цена временно недоступна — повторите позже |
| 402 | insufficient_balance | На балансе меньше цены заказа |
| 409 | not_delivered | Заказ ещё не выдан — данные будут после completed |
| 409 | code_unavailable | Данные недоступны (возврат по заказу или нужна проверка) — напишите в поддержку |
Формат зависит от того, где ошибка возникла. Ошибки обработки заказа приходят плоскими:
{"code": "insufficient_balance", "detail": "Не хватает баланса"}
Ошибки уровня запроса — аутентификация, лимит частоты, неизвестный тип,
отсутствующий idempotency_key — тот же объект, но вложенный в поле
detail:
{"detail": {"code": "bad_type", "detail": "type ∈ stars|premium|nft"}}
Различие историческое и сохранено намеренно, чтобы не ломать существующих
клиентов. Надёжный разбор: взять detail, и если это объект — читать
code из него, иначе из корня.
| HTTP | code | Что значит |
|---|---|---|
| 401 | unauthorized | Нет или неверный Bearer-ключ |
| 403 | ip_not_allowed | IP не в whitelist ключа |
| 403 | partner_inactive | Кабинет не активирован — нужно первое пополнение от $10.00 |
| 429 | rate_limited | Превышен лимит запросов — снизьте частоту |
| 400 | idempotency_required | Не передан idempotency_key в POST /orders |
| 403 | partner_program_unavailable | Программа временно недоступна |
| 400 | bad_type | type не stars, premium и не nft |
| 400 | bad_quantity / bad_months | Неверное количество звёзд или срок подписки |
| 400 | bad_gift | Не распознан идентификатор подарка — берите gift из каталога |
| 400 | collection_required | В /nft/gifts не передан параметр collection |
| 400 | bad_cursor | Невалидный cursor в /nft/gifts — передавайте next_cursor из предыдущего ответа |
| 400 | bad_max_price | max_price не разобран — положительная сумма в TON строкой, например «5.400» (число знаков после точки не ограничено) |
| 400 | bad_sort | Неизвестный sort в /nft/gifts — только price_asc или price_desc |
| 400 | bad_attr / bad_param | Неизвестное имя фильтра или параметра запроса (сверьтесь с applied_filters и ignored_params в ответе) |
| 409 | gift_not_for_sale | Подарок уже продан или снят с продажи — деньги не списаны |
| 409 | gift_reserved | На этот подарок уже есть незавершённый заказ |
| 409 | price_changed | Цена выше переданного max_price — в ответе current_price (TON) |
| 400 | recipient_required / recipient_not_found | Получатель не указан или не найден. Получатель обязан существовать и быть достижим в Telegram; проверка получателя идёт раньше цены (первым разбирается только синтаксис max_price), поэтому сначала проверьте ник через /validate/recipient |
| 400 | bad_webhook_url | Адрес webhook_url в теле заказа не годится для доставки — заказ НЕ создан, адрес не сохранён. В теле reason: bad_url (не строка, пусто, пробел или управляющий символ, не-ASCII — IDN присылайте в punycode), bad_scheme (только http/https; запрет http включается настройкой), bad_host (нет хоста, хост не ASCII, процентные последовательности в хосте), bad_port (порт не число или вне 1..65535; ограничение до 80/443 включается настройкой), credentials_in_url (логин/пароль в адресе), private_host (адрес ведёт на localhost, в приватную сеть, во внутреннюю зону или на нашу собственную инфраструктуру), too_long (включается настройкой предела длины). Проверка на входе не спрашивает DNS: она мгновенная и детерминированная. Если адрес синтаксически верен, а его ДОМЕН разрешается в приватную сеть, заказ создаётся, но ни одна доставка не уходит — запись в истории доставок получает status=failed и rejected_reason=private_host, а следующий заказ с этим адресом получит 400 сразу |
| 409 | idempotency_key_reuse | Тот же idempotency_key с другими параметрами (в том числе когда по этому ключу уже взведено списание под другой заказ) |
| 409 | order_in_progress | Заказ с этим ключом ещё создаётся — повторите через секунду |
| 409 | deferred_order_exists | На этом аккаунте уже есть незавершённый заказ Premium — дождитесь его выдачи |
| 402 | insufficient_balance | Не хватает средств на счёте этого типа заказа: USD для Stars/Premium, TON для NFT — в ответе currency и balance — пополните нужный счёт |
| 404 | not_found | Заказ или подарок не найден (или заказ принадлежит другому партнёру) |
| 502 | resolver_error | Сбой резолва получателя — повторите позже |
| 503 | product_unavailable | Товар временно недоступен. В теле reason: product_disabled — выключено на нашей стороне, повтор не поможет, напишите в поддержку; upstream_unavailable — недоступен поставщик, в теле и в заголовке Retry-After число секунд до осмысленного повтора |
| 503 | ledger_unavailable | Проверка повторного использования idempotency_key временно недоступна (только POST /orders). Заказ НЕ создан, ключ не захвачен, деньги не тронуты — повторите ТОТ ЖЕ запрос с ТЕМ ЖЕ idempotency_key через несколько секунд. Пропускать такой запрос мимо проверки мы не станем: именно она не даёт повтору ключа под другой лот списать сумму прежнего заказа |
| 429 | rate_limited | Исчерпан лимит. В теле scope — какой именно (key — общий, validate_recipient, nft_catalog, nft_orders — создание NFT-заказов, на партнёра), плюс limit, window_seconds, retry_after; та же величина в заголовке Retry-After |
/validate/* — 30 в минуту;
/nft/* (каталог и котировка) — 30 в минуту на ключ;
POST /orders с type=nft — 60 в минуту на партнёра
(все ключи вместе, свой счётчик; идемпотентный повтор не считается).
При исчерпании — 429 с scope и заголовком Retry-After.429 с scope: "nft_orders" и Retry-After).Что со Stars при сбое доставки? Ведём так же, как розницу: при недоступности сети доставки заказы копятся и досдаются после восстановления — деньги не теряются.
Повторил запрос из-за таймаута — спишется дважды? Нет, если вы передали тот же
idempotency_key: вернётся тот же заказ и списание останется одно.
Отправил сумму не до копейки — что будет? Платёж не опознается автоматически и попадёт в ручной разбор. Напишите в поддержку @partner_stars_bot с хэшем транзакции.
Подарок ушёл, пока я оформлял заказ? Как правило, заказ отклоняется ещё до списания (gift_not_for_sale).
Если продажа случилась уже после списания — заказ станет failed, TON вернутся на NFT-баланс автоматически.
Нужен ли получателю кошелёк или Premium? Нет: подарок переводится на обычный Telegram-аккаунт по username.
От чьего имени приходит подарок? Анонимно: отправитель скрыт. Ни ваш бренд, ни наш сервис получателю не показываются.
Почему цена в каталоге отличается от карточки? Каталог кэшируется до минуты, цена лота плавает;
спишется сумма из ответа на заказ, не больше вашего max_price.
Почему для NFT отдельный счёт в TON? NFT-подарки покупаются и передаются только за TON. Если бы мы списывали доллары, между вашим заказом и покупкой курс успевал бы измениться, и кто-то терял бы на разнице. Счёт в TON снимает этот риск: сколько назвали в котировке, столько и спишется.
Можно ли перевести USDT на NFT-баланс или обратно, вывести TON? Нет. Счета независимы и закупочные: USDT пополняется и тратится только на Stars и Premium, TON — только на NFT-подарки; вывод с обоих счетов не предусмотрен.
Заказ NFT не выполнен — что с деньгами? Цена подарка возвращается на NFT-баланс в TON автоматически, как у Stars. Если покупка уже прошла, а перевод получателю — нет, заказ уходит на ручной разбор и мы напишем вам сами.
Отправил TON на адрес для USDT (или USDT на адрес для TON)? Такой перевод не зачислится автоматически. Напишите в поддержку @partner_stars_bot с хэшем транзакции.
Поддержка: @partner_stars_bot — по вопросам интеграции и платежей. Своих конечных клиентов поддерживаете вы.