Процесс покупки

Для покупки используется один универсальный маршрут: POST /orders/create. Набор полей зависит от module.

Telegram Stars и Premium

Для Stars передавайте stars_amount (50–100000), для Premium — months (3, 6 или 12). В обоих случаях нужен публичный Telegram username получателя, а не его числовой ID. Символ @ в начале допустим.

Перед покупкой вызовите /recipient/check с тем же username и параметрами модуля. При покупке получатель проверяется повторно.

{
  "api_key_id": 1,
  "module": "stars",
  "stars_amount": 50,
  "username": "example_user",
  "api_user_id": "customer-789",
  "partner_order_id": "order-456"
}

{
  "api_key_id": 1,
  "module": "tg_premium",
  "months": 3,
  "username": "example_user",
  "api_user_id": "customer-789",
  "partner_order_id": "order-456"
}

Для этих модулей не передавайте nominal_id, quantity и recipient_data. В истории у заказа будет quantity=1, а количество звёзд или срок подписки — в stars_amount или months.

Пополнения и поля получателя

Выберите товар через /catalog/list с module=topups.
Получите его номиналы через /catalog/details.
Вызовите /catalog/nominal, передав item_id и nominal_id.
Соберите данные клиента по полученным input_fields.

Пример поля:

{
  "key": "server",
  "label": "Server",
  "type": "select",
  "required": true,
  "options": [
    {"key": "eu", "label": "Europe"},
    {"key": "asia", "label": "Asia"}
  ]
}

Для отображения используйте label, для запроса — key. Ключи чувствительны к регистру и могут отличаться у разных товаров. Не фиксируйте playerId или server как обязательные имена для всех игр.

Тип поля	Что передавать в `recipient_data`
`input`	Введённый текст строкой
`select`, `radio`, `check`	Один выбранный `options[].key` строкой, не подпись и не массив

Все значения recipient_data — строки, включая UID из цифр. При подготовке покупки получайте актуальные поля и варианты серверов.

{
  "api_key_id": 1,
  "module": "topups",
  "nominal_id": 11,
  "quantity": 1,
  "recipient_data": {
    "playerId": "123456789",
    "server": "eu"
  },
  "api_user_id": "customer-789",
  "partner_order_id": "order-456"
}

Этот пример подходит только для номинала, у которого действительно есть такие ключи.

compliance_info — необязательное поле только для пополнений, принимающих дополнительные сведения о платеже. Внутри — paymentMethod, playerIp и sellerName. Не передавайте его, если оно не нужно в вашем сценарии и не поддерживается номиналом: неподдерживаемый номинал вернёт HTTP 400. Оно не заменяет recipient_data. Если поле передаётся, playerIp должен быть реальным IP клиента, не адресом вашего сервера.

Как читать результат проверки получателя

Одного HTTP 200 недостаточно для подтверждения получателя.

Результат	Действие
`success=true`, `valid=true`	Получатель проверен
`success=true`, `valid=false`, `supported=false`, `code=validation_unsupported`	Проверка пополнения для товара не поддерживается; покупка разрешена, но данные клиента не подтверждены
`valid=false` с `recipient_not_found`, `recipient_invalid`, `invalid_username`, `invalid_recipient_fields`	Исправьте данные получателя
`recipient_ineligible` или `premium_already_active`	Получатель не может получить выбранный товар
`success=false`	Проверка не завершилась успешно; учитывайте `code` и `retryable`

Также могут возвращаться recipient_fields_unavailable, nominal_unavailable, price_unavailable и recipient_check_unavailable. message — пояснение для человека; для логики используйте code. Признак retryable=true относится к проверке, а не повторной покупке.

Коды

Выберите module=codes и nominal_id из каталога. Username, данные получателя и его проверка не нужны.

{
  "api_key_id": 1,
  "module": "codes",
  "nominal_id": 12,
  "quantity": 1,
  "api_user_id": "customer-789",
  "partner_order_id": "order-456"
}

У пополнений и кодов quantity по умолчанию 1. JSON-схема принимает положительные целые числа, но у номинала может быть меньший лимит количества, а у кодов — ограниченный остаток. В частности, некоторые номиналы разрешают не более 10 единиц в заказе; превышение возвращает HTTP 400.

Цена и баланс

Цены каталога — ваши API-цены с уже включённой наценкой платформы. /orders/quote рассчитывает итог, но не резервирует остаток, не проверяет ваш баланс и не фиксирует цену.

При покупке сумма пересчитывается и списывается с баланса интеграции. Вы не передаёте цену или допустимый максимум. amount_usd сохранённого заказа — фактическое списание.

При нехватке баланса API возвращает HTTP 400 с detail="Insufficient balance": заказ не создаётся, списания нет. Подтверждённый отказ после списания переводит заказ в refunded и возвращает списанную сумму.

Идентификаторы заказа

api_user_id — ID клиента в вашей системе, обязательная строка.
partner_order_id — необязательный ID заказа в вашей системе.
order_id — ID заказа AdaptGroup, который возвращает API.

partner_order_id не является ключом идемпотентности. Повторный запрос с тем же значением создаёт новую покупку. Параметра request_id нет.

Статусы заказа

Статус	Значение
`processing`	Покупка принята, ожидается окончательный результат
`completed`	Покупка успешно выполнена
`refunded`	Получен подтверждённый отказ, списанная сумма возвращена
`review`	Результат пока не подтверждён. Автоматического возврата нет; не запускайте другую покупку как повтор
`pending`	Неокончательный статус, допустимый в фильтре истории
`failed`	Статус, допустимый в фильтре истории; сам по себе не подтверждает возврат

Текущий процесс создания возвращает processing, completed, refunded или review. В ответе HTTP 200 маршрута /orders/create значение success=true соответствует processing/completed, а success=false — refunded/review.

В /orders/status признак success=true означает только успешное чтение сохранённого заказа. Проверяйте order.status.

Потерянный ответ или таймаут

Не повторяйте /orders/create автоматически: каждый вызов — отдельная покупка.

Есть order_id — запросите /orders/status.
HTTP 503 содержит detail.order_id — используйте этот ID.
Ответ потерялся — ищите через /orders/list по своему partner_order_id, при необходимости добавив api_user_id и период создания.
Пустой список не доказывает, что выполняющийся запрос не был принят. Если результат остаётся неясным, обратитесь в поддержку перед новой покупкой.

Пример ответа при неопределённом результате создания:

{
  "detail": {
    "message": "Order creation result unknown; check order status",
    "order_id": 125,
    "partner_order_id": "order-456"
  }
}

Получение результата

Используйте Статус заказа или настройте Вебхуки в дашборде.

Для завершённого заказа codes маршрут /orders/status возвращает order.codes:

[
  {"content": "EXAMPLE-CODE", "number": null, "pin": null},
  {"content": null, "number": "EXAMPLE-CARD-NUMBER", "pin": "1234"}
]

У кода может быть содержимое, номер, PIN или сочетание полей. Необязательные отсутствующие поля в ответе статуса сериализуются как null; вебхук может их не включать. Для других модулей и незавершённых заказов массив пустой.

В списке истории нет выданных кодов и данных получателя. Telegram-уведомления тоже не содержат выданных кодов: они доступны через API и итоговый вебхук.

Telegram Stars и Premium​

Пополнения и поля получателя​

Как читать результат проверки получателя​

Коды​

Цена и баланс​

Идентификаторы заказа​

Статусы заказа​

Потерянный ответ или таймаут​

Получение результата​