English version

Партнёрская программа TgSuperstars

Оптовые Telegram Stars, Telegram Premium и другие цифровые товары через REST API. Третий тип товара — NFT-подарки Telegram, см. раздел ниже. Модель — предоплата: вы пополняете закупочный баланс, с него списывается партнёрская цена каждого заказа, конечному клиенту продаёте по своей. О программе в целом — партнёрская программа, новости и разборы — блог.

Все денежные величины передаются строками с валютой в поле currency: "13.50", а не 13.5. Для Stars и Premium это доллары США (USDT), currency: "USD", два знака. Для NFT-подарков — монета TON, currency: "TON", три знака. Строка, а не число, — намеренно: суммы считаются десятичной арифметикой, и перевод их во float исказил бы копейки.
Как это работаетЦенаБаланс и пополнение API v1ВебхукиNFT-подаркиПодарочные картыКлючи и аккаунтыКоды ошибокЛимиты Частые вопросы

Как это работает

  1. Пополняете закупочный баланс: в USDT — для Stars и Premium, в TON — для NFT-подарков (это два отдельных счёта).
  2. Создаёте заказ: POST /orders с обязательным idempotency_key. В этот момент с баланса списывается партнёрская цена.
  3. Мы доставляем Stars или Premium либо NFT-подарок указанному получателю.
  4. Если доставка не удалась — партнёрская цена возвращается на баланс автоматически.

Оплату конечного клиента вы принимаете сами, в своей системе. Ваша маржа — разница между вашей ценой и партнёрской.

Цена

Цена одинакова для всех партнёров. Уровней, порогов оборота и персональных скидок нет, торга тоже: одна цифра для каждого, кто подключился.

Цены 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 этого счёта): деньги не резервируются, заказ не подвисает в ожидании.

API v1

База: 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.

Заказ Stars

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

Заказ Premium

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

Отложенная выдача Premium

Если у получателя уже активна подписка Telegram Premium, заказ всё равно принимается. Подписку нельзя вручить поверх действующей, поэтому выдача откладывается и проходит сама, как только текущая подписка получателя закончится. Включать это отдельно не нужно — так работают все ключи.

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

Если отсрочка вам не подходит, вызывайте 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
}

Статусы и вебхуки

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-Signaturehex(hmac_sha256(тело, webhook_secret)) — подпись тела
X-TimestampВремя отправки в unix-секундах, у каждой попытки своё
X-Signature-V2hex(hmac_sha256(X-Timestamp + "." + тело, webhook_secret)) — подпись вместе со временем: по ней отсекается повторная отправка перехваченного запроса
X-Signature-Version2
X-Webhook-Eventorder.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".

Заказ не выполнен: деньги автоматически возвращаются на баланс, и приходят два события — 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-подарки

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"
}

Цена подарка

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 ещё раз.

Заказ NFT

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
}

Статусы. 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&region=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"
}

Заказ

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"}'

Получить код

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"}

Ключи игр и аккаунты

Ключи игр, 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}
}

Как определяется совместимость

Заказ

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"}'

Получить ключ или данные аккаунта

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"}

Гарантия на готовые аккаунты

Условие ниже относится только к готовым аккаунтам (type: "account"). Ключей и подарочных карт оно не касается.

Коды ошибок ключей и аккаунтов

HTTPcodeЧто значит
400bad_countrycountry — не двухбуквенный код страны
409region_mismatchТовар не работает в стране покупателя; купить — только с accept_region_risk: true
400above_limitЦена выше лимита одного заказа
409price_changedЦена выше max_price; новая — в current_price
400product_unavailableПозиции нет в каталоге (нет в наличии, снята или дороже лимита)
503product_unavailableПозиция временно недоступна — повторите через retry_after секунд
503rate_unavailableЦена временно недоступна — повторите позже
402insufficient_balanceНа балансе меньше цены заказа
409not_deliveredЗаказ ещё не выдан — данные будут после completed
409code_unavailableДанные недоступны (возврат по заказу или нужна проверка) — напишите в поддержку

Коды ошибок

Формат зависит от того, где ошибка возникла. Ошибки обработки заказа приходят плоскими:

{"code": "insufficient_balance", "detail": "Не хватает баланса"}

Ошибки уровня запроса — аутентификация, лимит частоты, неизвестный тип, отсутствующий idempotency_key — тот же объект, но вложенный в поле detail:

{"detail": {"code": "bad_type", "detail": "type ∈ stars|premium|nft"}}

Различие историческое и сохранено намеренно, чтобы не ломать существующих клиентов. Надёжный разбор: взять detail, и если это объект — читать code из него, иначе из корня.

HTTPcodeЧто значит
401unauthorizedНет или неверный Bearer-ключ
403ip_not_allowedIP не в whitelist ключа
403partner_inactiveКабинет не активирован — нужно первое пополнение от $10.00
429rate_limitedПревышен лимит запросов — снизьте частоту
400idempotency_requiredНе передан idempotency_key в POST /orders
403partner_program_unavailableПрограмма временно недоступна
400bad_typetype не stars, premium и не nft
400bad_quantity / bad_monthsНеверное количество звёзд или срок подписки
400bad_giftНе распознан идентификатор подарка — берите gift из каталога
400collection_requiredВ /nft/gifts не передан параметр collection
400bad_cursorНевалидный cursor в /nft/gifts — передавайте next_cursor из предыдущего ответа
400bad_max_pricemax_price не разобран — положительная сумма в TON строкой, например «5.400» (число знаков после точки не ограничено)
400bad_sortНеизвестный sort в /nft/gifts — только price_asc или price_desc
400bad_attr / bad_paramНеизвестное имя фильтра или параметра запроса (сверьтесь с applied_filters и ignored_params в ответе)
409gift_not_for_saleПодарок уже продан или снят с продажи — деньги не списаны
409gift_reservedНа этот подарок уже есть незавершённый заказ
409price_changedЦена выше переданного max_price — в ответе current_price (TON)
400recipient_required / recipient_not_foundПолучатель не указан или не найден. Получатель обязан существовать и быть достижим в Telegram; проверка получателя идёт раньше цены (первым разбирается только синтаксис max_price), поэтому сначала проверьте ник через /validate/recipient
400bad_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 сразу
409idempotency_key_reuseТот же idempotency_key с другими параметрами (в том числе когда по этому ключу уже взведено списание под другой заказ)
409order_in_progressЗаказ с этим ключом ещё создаётся — повторите через секунду
409deferred_order_existsНа этом аккаунте уже есть незавершённый заказ Premium — дождитесь его выдачи
402insufficient_balanceНе хватает средств на счёте этого типа заказа: USD для Stars/Premium, TON для NFT — в ответе currency и balance — пополните нужный счёт
404not_foundЗаказ или подарок не найден (или заказ принадлежит другому партнёру)
502resolver_errorСбой резолва получателя — повторите позже
503product_unavailableТовар временно недоступен. В теле reason: product_disabled — выключено на нашей стороне, повтор не поможет, напишите в поддержку; upstream_unavailable — недоступен поставщик, в теле и в заголовке Retry-After число секунд до осмысленного повтора
503ledger_unavailableПроверка повторного использования idempotency_key временно недоступна (только POST /orders). Заказ НЕ создан, ключ не захвачен, деньги не тронуты — повторите ТОТ ЖЕ запрос с ТЕМ ЖЕ idempotency_key через несколько секунд. Пропускать такой запрос мимо проверки мы не станем: именно она не даёт повтору ключа под другой лот списать сумму прежнего заказа
429rate_limitedИсчерпан лимит. В теле scope — какой именно (key — общий, validate_recipient, nft_catalog, nft_orders — создание NFT-заказов, на партнёра), плюс limit, window_seconds, retry_after; та же величина в заголовке 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 — по вопросам интеграции и платежей. Своих конечных клиентов поддерживаете вы.