Оптовые 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 принимаем в сетях TON, TRC-20 и BEP-20; TON — только монету TON в сети TON, на отдельный адрес, который выдаётся в кабинете; минимальное пополнение — 10 TON. Зачисление автоматическое, обычно в течение минуты после подтверждения сети.
Не перепутайте адреса. На адрес для USDT зачисляется только USDT, на адрес для TON — только монета TON. Другие токены и монеты, отправленные на эти адреса, не зачисляются и не возвращаются.
Активация. Первое пополнение — от $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 в ответах всегда по-русски.
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 | balance;
reason — один из: gift_not_for_sale (лот ушёл), gift_reserved,
price_above_cap (лот подорожал сверх зафиксированной цены — мы не покупаем дороже),
amount_above_cap, invalid_price, invalid_upstream_price, pricing_failed (цена лота не подтвердилась),
gift_unavailable (маркет не ответил), invalid_recipient,
insufficient_funds (временно недостаточно средств на покупку на стороне сервиса — ваш баланс тут ни при чём),
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".
Напишите в поддержку @tg_super_support_bot, если заказ висит дольше часа.
Вебхуки — те же order.completed, order.failed,
order.refunded; в data приходит объект заказа с блоками gift,
delivery, failure.
Формат зависит от того, где ошибка возникла. Ошибки обработки заказа приходят плоскими:
{"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: вернётся тот же заказ и списание останется одно.
Отправил сумму не до копейки — что будет? Платёж не опознается автоматически и попадёт в ручной разбор. Напишите в поддержку @tg_super_support_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)? Такой перевод не зачислится автоматически. Напишите в поддержку @tg_super_support_bot с хэшем транзакции.
Поддержка: @tg_super_support_bot — по вопросам интеграции и платежей. Своих конечных клиентов поддерживаете вы.