RobloCash API

Документация для разработчиков, подключающих магазин или бота к RobloCash.

Быстрый старт

От нуля до первого заказа — за 10 минут.

1. Получите X-Api-Key (sk_live_...) и {BASE_URL}.
2. Проверьте доступность: GET {BASE_URL}/health → "ok": true.
3. Отправьте POST {BASE_URL}/collect с login, password, donat и recovery_code.
4. Получите 201 с verification_in_progress: true.
5. Дождитесь коллбека collect.completed на ваш callback_url.

curl -s -X POST "{BASE_URL}/collect" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_live_your_key" \
  -H "Idempotency-Key: order-20260518-001" \
  -H "X-Request-ID: req-20260518-001" \
  -d '{
    "login": "PlayerOne",
    "password": "secret_password",
    "donat": 500,
    "recovery_code": "ABCD-EFGH-1234",
    "callback_url": "https://your-server.example/hooks/buffer"
  }'

Аутентификация

Только для POST /collect и POST /collect/challenge:

X-Api-Key: sk_live_your_key

Или:

Authorization: Bearer sk_live_your_key

Неверный ключ → 401 Authentication Failed

GET /health

Проверка доступности. API-ключ не требуется.

curl -s "{BASE_URL}/health"

{
  "ok": true,
  "status": "up",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "collect_queue": {
    "active": 0,
    "waiting": 0,
    "max_concurrent": 4
  }
}

POST /collect

Создать заказ Robux и запустить верификацию Microsoft 2FA.

Тело запроса

Ответ 201 — верификация в процессе

{
  "ok": true,
  "order_id": "ord_xxxxxxxx",
  "verification_in_progress": true,
  "donat": 500,
  "bundle_description": "Requested 500 R$: 500 R$",
  "correlation_id": "req-20260518-001",
  "callback_registered": true,
  "verification_url": "{BASE_URL}/v/tok_xxxxxxxx"
}

Пока verification_in_progress: true, поле status отсутствует — это не финал.

Ответ после завершения

status: success — верификация пройдена, Robux доставляются.

status: fail — ошибка. Смотрите credential_note и requires_new_request.

{
  "ok": true,
  "status": "success",
  "verification_in_progress": false,
  "order_id": "ord_xxxxxxxx",
  "order_status": "completed",
  "donat": 500,
  "bundle_description": "Requested 500 R$: 500 R$",
  "correlation_id": "req-20260518-001"
}

Что делать при status: fail

Номиналы donat

Полный список — на странице Номиналы. Другое значение → 400.

Идемпотентность

• Каждый новый заказ — свой Idempotency-Key (UUID или уникальная строка).
• Повтор с тем же ключом и тем же телом → тот же ответ + "idempotent_replay": true.
• Тот же ключ с другим телом → 409.

Game challenge

Когда Microsoft запрашивает выбор плиток на изображении:

1. Ответ POST /collect содержит awaiting_game_challenge: true и game_challenge.
2. Покажите изображение: GET /challenges/{token}.png (требует API-ключ).
3. Отправьте выбор: POST /collect/challenge с order_id и game_choice_ids.

Webhooks

RobloCash отправляет POST на ваш callback_url. Ваш сервер должен ответить 2xx в течение ~15 секунд.

Подпись: заголовок X-Buffer-Signature (HMAC-SHA256) при настроенном CLIENT_WEBHOOK_SECRET.

{
  "object": "buffer_callback",
  "event_type": "collect.completed",
  "status": "success",
  "correlation_id": "req-20260518-001",
  "order_id": "ord_xxxxxxxx",
  "donat": 500,
  "bundle_description": "Requested 500 R$: 500 R$",
  "source": "buffer",
  "created_at": 1715000000,
  "data": {
    "collect": {
      "ok": true,
      "status": "success",
      "order_id": "ord_xxxxxxxx",
      "donat": 500,
      "verification_in_progress": false,
      "order_status": "completed"
    }
  }
}

Страница верификации /v/{token}

При включённом BUFFER_VERIFICATION_PAGE=1 в ответе POST /collect возвращается verification_url.

• GET /v/{token} — HTML-страница для покупателя
• GET /v/{token}/state — JSON-состояние (polling)
• POST /v/{token}/submit — отправка credentials, recovery, OTP, выбор метода 2FA
• GET /v/{token}/challenge.png — изображение game challenge

Коды HTTP

Заголовки запроса