API игровых пополнений — схема обработки заказа

Пополнение — единственная категория цифровых товаров, где вы отдаёте не товар, а действие на чужом аккаунте. Кода нет, отката нет, а получатель определяется строкой, которую покупатель ввёл руками. Ниже — полная схема обработки такого заказа и те места, где эта разница ломает архитектуру, скопированную с продажи ключей.

Чем пополнение отличается от кода

Отсюда следует главное проектное правило: вся защита переносится на этап до списания денег. В продаже кодов вы можете исправить многое постфактум. В пополнениях — почти ничего.

Шаг 1. Валидация player ID до списания

Это самая важная часть всей интеграции, и она целиком на вашей стороне.

Валидация формата

Минимум, который вы обязаны проверить до того, как возьмёте деньги:

• Длина и набор символов. У каждой игры свой формат идентификатора — где-то только цифры, где-то буквенно-цифровой, где-то с разделителем.
• Серверный регион. Многие игры требуют указать сервер или зону вместе с ID. Без этого пополнение уйдёт не туда либо не пройдёт вовсе.
• Отсутствие мусора. Пробелы по краям, вставленный из буфера префикс «ID:», лишние символы из мессенджера. Нормализуйте строку перед отправкой.

Проверка существования аккаунта

Некоторые поставщики предоставляют отдельный эндпоинт проверки идентификатора, который возвращает никнейм игрока. Некоторые — нет, и реализация зависит от конкретной игры. Уточните у своего поставщика, доступна ли такая проверка для нужных вам игр.

Там, где проверка есть, используйте её обязательно и показывайте покупателю ник до оплаты. Это самый дешёвый способ предотвратить спор: человек, увидевший чужое имя, исправляет ID сам.

Подтверждение покупателем

Даже без проверки ника, экран подтверждения перед списанием обязателен. На нём:

• ID в том виде, в котором он уйдёт поставщику.
• Регион / сервер.
• Явная формулировка о том, что зачисление необратимо.
• Отметка времени подтверждения, которая уходит в ваш журнал.

Этот журнал — то, чем вы отвечаете, когда покупатель через неделю утверждает, что вводил другой номер.

Шаг 2. Создание заказа

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

curl -X POST "https://public-api.foxreload.com/api/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "product_01krgfgww8eth9xvvysd6y7r4j",
        "quantity": 1,
        "note": {"player_id": "123456"}
      }
    ],
    "isMock": false
  }'

У FoxReload идентификатор игрока передаётся в поле note позиции — объект до 10 ключей для дополнительных данных. Какие именно ключи ожидает конкретный товар, смотрите в его attributes и userGuide.

Про идемпотентность. Некоторые API принимают заголовок Idempotency-Key, чтобы повторная отправка не создала второй заказ. Проверьте, поддерживает ли это ваш поставщик — далеко не все. FoxReload его не поддерживает, поэтому при таймауте на создании заказа нельзя ретраить вслепую: сначала запросите список заказов и убедитесь, что заказ не создался. В пополнениях цена такой ошибки выше, чем в кодах, — дубль означает второе зачисление, которое вы уже не вернёте.

Шаг 3. Асинхронное завершение

Заказ проходит состояния последовательно и однонаправленно:

Статус узнаётся опросом:

curl "https://public-api.foxreload.com/api/orders/{order_id}" \
  -H "X-API-Key: YOUR_API_KEY"

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

Схема опроса: часто в первую минуту, затем растущий интервал, свой предельный срок и очередь превысивших его заказов. Для пополнений эта очередь особенно важна — покупатель, не увидевший валюту в игре, пишет в поддержку быстрее, чем покупатель ключа.

Подробный разбор проектирования таких машин состояний — в статье про state machine заказа.

Шаг 4. Терминальные и повторяемые ошибки

Разделение ошибок на два класса — то, что отличает работающую интеграцию от сжигающей деньги.

Терминальные — повторять бессмысленно

• Неверный player ID. Аккаунт не существует или формат не тот. Повтор даст тот же результат. Возврат покупателю, просьба проверить ID.
• Регион не поддерживается. Товар не может быть зачислен на аккаунт из этого региона. Возврат.
• Товар недоступен для этого аккаунта. Например, пакет не продаётся игрокам ниже определённого уровня или в этой стране.
• Ошибки авторизации и валидации запроса — HTTP 400, 401, 403. Это ваш баг, а не сбой.

По терминальным ошибкам немедленно снимайте заказ с опроса и передавайте в сценарий возврата.

Повторяемые — имеет смысл попробовать снова

• HTTP 429 — превышен rate limit. Экспоненциальный backoff с джиттером.
• HTTP 5xx — сбой на стороне поставщика. Backoff, ограниченное число попыток.
• Сетевой таймаут. Здесь особая осторожность: сначала проверьте состояние заказа, потом решайте.
• Временная недоступность игры. Технические работы у издателя — характерная причина зависших processing. Ждать, а не пересоздавать заказ.

Ключевая ошибка, которую делают почти все на старте: обрабатывать таймаут как повторяемую ошибку и сразу создавать новый заказ. В пополнениях это означает двойное зачисление и деньги, которых вы не вернёте.

Шаг 5. Возвраты и реверсы

Здесь нужно честно принять реальность: автоматического отката зачисления не существует.

Возможные сценарии и что с ними делать:

• Заказ ушёл в cancelled или failed до зачисления. Деньги покупателю возвращаются вашими средствами платежа, средства поставщика возвращаются на ваш баланс по его правилам — уточните эти правила заранее.
• Зачисление прошло, но покупатель недоволен. Товар предоставлен. Возврат — ваше коммерческое решение, а не техническая операция.
• Зачисление ушло на ID, который покупатель указал неверно. Технически неисправимо. Ваша позиция — журнал подтверждения. Именно поэтому экран подтверждения не является опциональным.
• Частичное выполнение многопозиционного заказа. Обрабатывайте позиции независимо: выполненные оставляйте, по невыполненным делайте возврат.

Заложите в юнит-экономику небольшой резерв на спорные случаи. При объёме они неизбежны, и лучше видеть их отдельной строкой, чем удивляться просадке маржи. Как это считается — в материале про юнит-экономику реселлера.

Шаг 6. Сверка

Ежедневная сверка — обязательная гигиена, а не опция.

Забирайте список заказов у поставщика:

curl "https://public-api.foxreload.com/api/orders/?statuses=completed,failed,cancelled&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

И сравнивайте с тем, что у вас в базе. Что искать:

• Заказы у поставщика, которых нет у вас. Классический след дубля от слепого ретрая.
• Заказы у вас со статусом «в процессе», которые у поставщика уже терминальные. Ваш опрос сломался или процесс упал.
• Расхождения по суммам. Цена на момент заказа отличается от вашей записи — значит, вы фиксируете цену не в тот момент.
• Списания с баланса без соответствующего заказа. Разбирать немедленно.

Сверка находит проблемы за часы, а не в конце месяца, когда сходить будет уже нечему.

Где брать пополнения оптом

Пополнения имеет смысл брать там же, где и остальной ассортимент, — одна интеграция вместо нескольких. FoxReload — оптовый поставщик цифровых товаров с 900+ SKU: пополнения игровых аккаунтов, подарочные карты, ключи, eSIM и лицензии, всё через один REST API с автоматической выдачей и мультирегиональными SKU. Одна модель заказа и один формат статусов на все категории, включая товары, требующие передачи ID игрока.

Читать дальше

• Как подключить API поставщика цифровых товаров
• API игровых пополнений для реселлеров
• Схема обработки заказа FoxReload
• Проектирование state machine заказа
• Как избежать чарджбэков в цифровых товарах