--- title: "Частые вопросы" url: "https://docs.x-hub.online/reference/faq/" description: "Чеклист перед запуском и частые вопросы." relatedDocuments: - "https://docs.x-hub.online/reference/errors/" - "https://docs.x-hub.online/reference/nodejs/" - "https://docs.x-hub.online/reference/python/" - "https://docs.x-hub.online/webhooks/delivery/" - "https://docs.x-hub.online/payments/" - "https://docs.x-hub.online/payments/refunds/" --- # Чеклист перед запуском ### Обязательно - [ ] API-ключи хранятся в переменных окружения (не в коде) - [ ] Webhook endpoint доступен по HTTPS - [ ] Webhook подпись верифицируется через HMAC-SHA256 - [ ] Обработка вебхуков идемпотентна (дубликаты не ломают логику) - [ ] Webhook отвечает за < 10 секунд - [ ] `Idempotency-Key` передаётся в каждом POST-запросе (и **переиспользуется** при ретраях того же заказа) - [ ] Во всех POST-запросах есть `Content-Type: application/json` - [ ] Обработаны все статусы платежа (paid, settled, failed, cancelled, expired, amount_mismatch, refunded) - [ ] Обработчик переживает **повторную** смену статуса: `expired → paid`, `amount_mismatch → paid/failed`, `paid/settled → refunded` - [ ] Пометка заказа по `expired` **обратима** — поздняя оплата не оставит клиента без товара - [ ] Реализован fallback — GET /payments/:id если webhook не пришёл - [ ] Ожидание вебхука не завязано на «10 минут» — доставка может прийти через часы (см. [предохранитель](../webhooks/delivery.md#circuit-breaker)) ### Рекомендуется - [ ] Логирование всех входящих вебхуков - [ ] Мониторинг баланса (GET /balance) - [ ] Алерты при ошибках вебхуков (5xx ответы) - [ ] Exponential backoff при 429/500 от API --- # FAQ ### Можно ли принимать платежи без юрлица в России? Да, X-Hub выступает агрегатором. Мерчанту нужен только USDT-кошелёк для получения выплат. ### Какая минимальная сумма платежа? 30 ₽ для любого разового платежа, одинаково для всех аккаунтов. Списания по уже выданному мандату подписки этому порогу не подчиняются. Ниже минимума API отвечает `400 AMOUNT_BELOW_MINIMUM`. ### Как быстро деньги появятся на балансе? Рубли зачисляются мгновенно после оплаты клиентом (статус `paid`). Конвертация в расчётную валюту происходит на следующий день в 12:00 по московскому времени (T+1 settlement). ### Можно ли отменить платёж? Нет — эндпоинта отмены платежа в API нет. После создания платёж либо оплачивается клиентом, либо истекает по `expires_at` (по умолчанию 15 минут). Учти: `expired` — не финал. Если клиент заплатит позже, платёж может подняться в `paid` в течение 6 часов от создания — см. [expired](../payments/index.md#edge-case-expired). ### Как сделать возврат клиенту? { #kak-sdelat-vozvrat } Тремя способами, и все три ведут к одной заявке: `POST /refunds` в API, кнопка на платеже в [кабинете](https://app.x-hub.online), либо обращение в X-Hub с номером платежа. Ручка включается аккаунту по запросу; пока не включена — она отвечает `404`, и остаются кабинет и мы. Возврат — это **заявка**, а не мгновенная операция: ты её создаёшь, мы исполняем, исход приходит вебхуком. Пока она идёт, платёж отдаётся с `"refund_pending": true`, и основной `status` НЕ меняется — деньги ещё не вернулись, а возврат может и не состояться. Полностью — раздел [Возвраты](../payments/refunds.md#refunds): суммы и остаток, комиссия, четыре исхода и готовый обработчик. ### Что делать если пришёл `amount_mismatch`? Клиент заплатил не ту сумму. Средства в безопасности. Свяжитесь с поддержкой X-Hub для разрешения. ### Как я получаю выплаты? Автоматически. После подтверждения платежей средства зачисляются на баланс и выплачиваются ежедневным расчётом (settlement) — создавать запросы на вывод не нужно, ручные запросы `POST /api/v1/withdrawals` не поддерживаются (`410 WITHDRAWAL_DISCONTINUED`). Баланс виден в `GET /api/v1/balance` и в кабинете. ### Webhook не приходит — что делать? 1. Убедитесь что URL доступен по HTTPS и **не отвечает редиректом** — `3xx` считается провалом доставки. 2. Проверьте что сервер отвечает `200` за < 10 секунд. 3. Убедитесь, что в кабинете заданы **и** `webhook_url`, **и** `webhook_secret`. Пока пары нет, события копятся и не отправляются вовсе; как только конфигурация полная — уезжают сразу. 4. Дайте времени больше, чем кажется. Быстрая лестница — 10 попыток с суммарными паузами ~8.5 минут, но если ваш endpoint падал, [предохранитель](../webhooks/delivery.md#circuit-breaker) добавляет паузы, которые попытками не считаются, и доставка может прийти спустя **часы**. А денежное уведомление, отбитое вашим `4xx`, ретраится по медленному графику до **41 часа**. 5. Как fallback — используйте `GET /payments/:id`. Это единственный способ узнать статус здесь и сейчас; вебхук ждать не нужно. 6. Если событие всё-таки потеряно окончательно — напишите в X-Hub, доставку можно переотправить вручную. ### Можно ли использовать HTTP вместо HTTPS для вебхуков? Нет, только HTTPS в production. Используйте сервисы вроде ngrok для локальной разработки. --- ## Поддержка Вопросы, проблемы — пиши в ваш чат с командой X-Hub.