Чеклист перед запуском

Обязательно

[ ] 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 минут» — доставка может прийти через часы (см. предохранитель)

FAQ

Можно ли принимать платежи без юрлица в России?

Да, X-Hub выступает агрегатором. Мерчанту нужен только USDT-кошелёк для получения выплат.

Какая минимальная сумма платежа?

30 ₽ для любого разового платежа, одинаково для всех аккаунтов. Списания по уже выданному мандату подписки этому порогу не подчиняются. Ниже минимума API отвечает 400 AMOUNT_BELOW_MINIMUM.

Как быстро деньги появятся на балансе?

Рубли зачисляются мгновенно после оплаты клиентом (статус paid). Конвертация в расчётную валюту происходит на следующий день в 12:00 по московскому времени (T+1 settlement).

Можно ли отменить платёж?

Нет — эндпоинта отмены платежа в API нет. После создания платёж либо оплачивается клиентом, либо истекает по expires_at (по умолчанию 15 минут).

Учти: expired — не финал. Если клиент заплатит позже, платёж может подняться в paid в течение 6 часов от создания — см. expired.

Как сделать возврат клиенту?

Тремя способами, и все три ведут к одной заявке: POST /refunds в API, кнопка на платеже в кабинете, либо обращение в X-Hub с номером платежа. Ручка включается аккаунту по запросу; пока не включена — она отвечает 404, и остаются кабинет и мы.

Возврат — это заявка, а не мгновенная операция: ты её создаёшь, мы исполняем, исход приходит вебхуком. Пока она идёт, платёж отдаётся с "refund_pending": true, и основной status НЕ меняется — деньги ещё не вернулись, а возврат может и не состояться.

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

Что делать если пришёл `amount_mismatch`?

Клиент заплатил не ту сумму. Средства в безопасности. Свяжитесь с поддержкой X-Hub для разрешения.

Как я получаю выплаты?

Автоматически. После подтверждения платежей средства зачисляются на баланс и выплачиваются ежедневным расчётом (settlement) — создавать запросы на вывод не нужно, ручные запросы POST /api/v1/withdrawals не поддерживаются (410 WITHDRAWAL_DISCONTINUED). Баланс виден в GET /api/v1/balance и в кабинете.

Webhook не приходит — что делать?

Убедитесь что URL доступен по HTTPS и не отвечает редиректом — 3xx считается провалом доставки.
Проверьте что сервер отвечает 200 за < 10 секунд.
Убедитесь, что в кабинете заданы и webhook_url, и webhook_secret. Пока пары нет, события копятся и не отправляются вовсе; как только конфигурация полная — уезжают сразу.
Дайте времени больше, чем кажется. Быстрая лестница — 10 попыток с суммарными паузами ~8.5 минут, но если ваш endpoint падал, предохранитель добавляет паузы, которые попытками не считаются, и доставка может прийти спустя часы. А денежное уведомление, отбитое вашим 4xx, ретраится по медленному графику до 41 часа.
Как fallback — используйте GET /payments/:id. Это единственный способ узнать статус здесь и сейчас; вебхук ждать не нужно.
Если событие всё-таки потеряно окончательно — напишите в X-Hub, доставку можно переотправить вручную.

Можно ли использовать HTTP вместо HTTPS для вебхуков?

Нет, только HTTPS в production. Используйте сервисы вроде ngrok для локальной разработки.

Поддержка

Вопросы, проблемы — пиши в ваш чат с командой X-Hub.