Пополнение по ID игрока через API: контракт полей и почему заказы падают на Zone ID

Пополнение — не код: доставлять нечего и отозвать нельзя

Когда через API заказан код гифт-карты, в выполненном заказе приходит массив codes: вы отдаёте строку покупателю, а если он её потерял — присылаете ту же самую ещё раз. У заказа пополнения массива codes нет и не будет: ценность уходит прямо на аккаунт игрока. Вместо кодов возвращается ваш же ввод — в заказе типа game_topup приходят category_id, offer_id и объект fields с теми значениями, которые вы отправили.

Из этого следует всё остальное. Гарантия замены закрывает код, который не сработал, и не закрывает пополнение, отправленное на неверно введённый ID: алмазы к этому моменту уже на чужом аккаунте — так прямо и написано в нашем FAQ. Значит: собрать правильные поля, подтвердить их с покупателем до списания и прописать правило в условиях магазина до первой ошибки.

Контракт полей: категория объявляет, вы собираете

GET /api/v1/top-ups/categories/{id}/offers отдаёт два списка: offers — пакеты с ценой, в которой уже учтена ваша наценка, и fields — то, что нужно получить от покупателя. У каждого поля есть key, человекочитаемый label и type. В POST /api/v1/top-ups/order уходят category_id, offer_id и объект fields, ключи которого обязаны совпадать с fields[].key: сервер сверяет его с объявленным списком поле за полем ещё до списания.

Зашьёте player_id в код — соберёте интеграцию ровно под одно семейство игр. В документации пример показан на PUBG Mobile (Auto) с единственным player_id, но это пример, а не схема. Показывайте label, отправляйте key и никогда не выводите смысл поля из названия ключа: в живом каталоге на 8 сентября 2026 одна и та же идея «номер игрока» приходит как player_id в PUBG Mobile и Free Fire, как user_id в 8 Ball Pool (подпись — «Unique ID»), а в одной из категорий с входом по логину ключи user_id и server_id подписаны как «Email» и «Password».

Тип тоже не всегда text: часть категорий объявляет поле select с фиксированным списком вариантов (сервер: Asia / Europe / America), и отправить нужно одно из объявленных значений. В том же ответе приходит note — собственная инструкция категории: какой номер вводить, к какому региону привязаны пакеты. Показывайте её тому, кто заполняет форму.

Три семейства требований на живом каталоге

Проверено по живому каталогу 8 сентября 2026 — любая категория попадает в одну из трёх групп:

• Одно поле. PUBG Mobile (Auto) и все региональные категории Free Fire объявляют единственный player_id. Под этот случай все и пишут — и именно поэтому интеграция ломается на второй игре.
• ID плюс сервер или зона. Mobile Legends (Global) и Mobile Legends (RU) объявляют player_id и server_id, Ace Racer — user_id и server_id. Не хватает одного числа — не уходит ничего.
• Доступ по логину. Семь категорий идут с пометкой «(Auto Via Login)»: Genshin Impact, Solo Leveling: Arise, Tower of Fantasy, Love and Deepspace, Mongil: Star Dive, Neverness to Everness и Arknight: Endfield. ID игрока они не спрашивают вовсе: им нужны почта и пароль от аккаунта, а сверху UID, Role ID или сервер из списка.

Почему Zone ID — причина отказов номер один

Аккаунт в Mobile Legends определяется двумя числами, а игрок видит их одной строкой: в профиле длинное число — это ID игрока, а короткое в скобках рядом — Zone ID, он же сервер. В API это поле называется server_id с подписью «Server ID», а игра и наша собственная страница Mobile Legends зовут его Zone ID. Поэтому покупатель и присылает одно число из двух в полной уверенности, что прислал всё.

Лечится это в форме, а не в поддержке: два отдельных поля, подписанных теми словами, которые игрок видит в игре, плюс строка подсказки — «короткое число в скобках: 123456789 (5678) значит ID 123456789, зона 5678». Если принимаете строку целиком, разберите её сами и покажите разбор на подтверждение.

Проверки ID игрока в API нет — что делать вместо неё

Прямой ответ: в API RSC нет эндпоинта, который проверит, существует ли ID игрока и кому он принадлежит. Единственная предварительная проверка на платформе — POST /api/v1/steam-topup/check-login, и она про пополнение кошелька Steam, а не про игровые пополнения. Первая система, которая отличит верный ID от неверного, — сама игра, и происходит это уже после того, как деньги ушли.

Значит, проверять должен человек, которому принадлежит аккаунт, и до списания. Возвращайте покупателю всё введённое отдельным шагом подтверждения — «Mobile Legends (Global) · ID 123456789 · зона 5678 · 172 алмаза», — называйте игру и регион, требуйте явное «да» и сохраняйте ответ вместе с заказом. В боте это одно лишнее сообщение, в вебе — один экран.

Что отвечает сервер, когда поле заполнено неверно

Валидация серверная и адресная. Пропущенное или пустое значение возвращает HTTP 400, ошибку типа invalid_request и сообщение «Field server_id is required (see the category's fields).» Значение длиннее 200 символов даёт «Field server_id is invalid.» Значения передаются строками; число в JSON примут и приведут к строке, а всё остальное считается пустым.

Покупателю это сообщение показывать не нужно: достаньте из него ключ поля, найдите ключ в массиве fields, который вы уже закешировали, и напечатайте свою фразу — «Нужен Zone ID: короткое число в скобках рядом с ID». И помните, что HTTP 200 не означает «доставлено»: если категория отказала на этапе создания, списание возвращается на баланс, а в том же ответе приходит заказ со статусом «refund» и заполненным status_reason. Ветвитесь по статусу заказа, а не по HTTP-коду.

Регион — вторая причина отказов

Многие игры — это не одна категория, а полка региональных. На 8 сентября 2026 в каталоге четырнадцать региональных категорий Free Fire (BD, BR, CIS, EU, ID, LATAM, MENA, MY/SG, PH, PK, SG, TH, TW, VN) и двенадцать у Mobile Legends. Регион стоит в названии и проговорён в note: у индонезийской категории Free Fire прямо написано, что пакеты привязаны к региону. GET /api/v1/top-ups/brands группирует каталог по брендам и отдаёт region и variant для каждой подкатегории.

Спрашивайте регион до того, как показали цены: индонезийский пакет, купленный для европейского аккаунта, — те же потерянные деньги, что и неверный ID. И читайте variant: PUBG Mobile существует как (Auto), (Fast), (Manual) и (Reserve) — поле везде одно, player_id, а поведение разное. У категории Manual в её собственном note написано, что среднее время доставки 5–15 минут, успешность примерно 50/50 в зависимости от состояния канала, а при невозможности выполнить заказ деньги возвращаются.

Жизненный цикл заказа пополнения

created → processing → completed. Статус failed означает, что доставить не получилось, а refund — что списание вернулось на баланс: в истории баланса появляется строка возврата, тикет для этого не нужен. POST /api/v1/top-ups/order списывает деньги сразу и возвращает заказ, а дальше источник правды — GET /api/v1/orders/{number}, который отдаёт ещё и status_history с причиной по каждому шагу. Кодов в конце не будет.

Опрашивайте статус, но не долбите его. Платформа перепроверяет живой заказ каждые 20 секунд первые три минуты, затем раз в минуту до десятой минуты, дальше раз в десять минут — более частый запрос вернёт тот же статус и просто съест лимит. Новый ключ получает 30 запросов в минуту и 5 000 в сутки; в ответах приходят заголовки X-RateLimit, в 429 — Retry-After. Зачисление обычно занимает минуты, но покупателю вы показываете статус.

Кто платит, когда ID оказался неверным

Выполненное пополнение не отзывается — ни нами, ни игрой. На нашей странице Mobile Legends написано именно так, а в общем FAQ этот случай назван единственным, который не покрывает гарантия замены. Пока заказ не выполнен, шанс есть: тикет в кабинете или Telegram @supportresellcodes — мы попробуем его отменить.

Поэтому один абзац в условиях магазина стоит написать до первого заказа, а не после первого скандала: ID, зону и регион даёт и подтверждает покупатель; после подтверждения выполненное пополнение возврату не подлежит; ID, который перепутал ваш оператор, — ваша ответственность. Храните подтверждение: это вся ваша защита.

Как собрать интеграцию на 316 категорий, а не на четыре

На 8 сентября 2026 в каталоге 316 категорий, так что жёсткий switch по четырём из них — это переписывание, отложенное на пару месяцев. Синхронизируйте GET /api/v1/top-ups/categories в свою таблицу по расписанию, запрашивайте offers в момент, когда покупатель открыл категорию, и кешируйте fields рядом с ценой на несколько минут. Форму стройте из массива в рантайме: имя поля из key, подпись из label, обычный ввод или выпадающий список из type.

• Новая категория из очередной синхронизации должна доезжать до витрины без выкатки, а незнакомый ключ — превращаться в подписанное текстовое поле, а не в падение.
• Цены в ответе offers уже включают вашу наценку, а «одно пополнение на заказ» означает, что два пакета — это два заказа и два списания.
• Прогоняйте весь путь настоящим заказом на аккаунт, которым управляете сами: 60 UC для PUBG Mobile стоили $0.88 в публичной таблице цен на 8 сентября 2026.
• Баланс пополняется заранее в USDT (TRC-20, BEP-20, TON, Aptos) от 3 долларов, чтобы подтверждённый заказ не ждал денег.

Чек-лист интеграции пополнений

• Читайте fields по каждой категории и стройте форму из них: про конкретную игру в коде нет ничего, кроме текста подсказки.
• Показывайте label, отправляйте key: названия ключей — идентификаторы без смысла.
• Возвращайте эхом ID, зону, регион и пакет и требуйте явное подтверждение до списания.
• Переводите ошибки 400 по полям в человеческую подпись; сырое сообщение покупателю не показывайте.
• Ветвитесь по статусу заказа, включая refund, а не по HTTP 200.
• Опрашивайте GET /api/v1/orders/{number} с шагом от 20 секунд и следите за заголовками лимитов.
• Опубликуйте правило про неверный ID до того, как оно понадобится, и храните все подтверждения.

Списки полей, количество категорий и приведённая цена — это то, что каталог отдал 8 сентября 2026: набор полей у категории может измениться, а цены двигаются, поэтому источник правды — сам эндпоинт. Полная документация — resell.codes/docs, интерактивный Swagger — resell.codes/docs/reference.