Перейти к содержанию
mdМаркдаун

Магазины

Магазин — отдельное направление приёма платежей внутри одного аккаунта: сайт, приложение, бот. У магазина своё название, свой shop_id и свой оборот в кабинете. Каждый платёж относится ровно к одному магазину.

Что общее, а что своё

Общее для всех магазинов аккаунта Своё у каждого магазина
API-ключ и секрет (X-Api-Key, X-Api-Secret) Название — приходит в вебхуках как shop_name
Адрес вебхука и секрет подписи shop_id
Баланс Оборот и число оплаченных платежей
Выплаты Состояние: «Работает» или «Выключен»

У каждого аккаунта есть магазин по умолчанию, в кабинете он с меткой «Основной». Платёж по ключу аккаунта без shop_id попадает в него. К нему же относятся все платежи, созданные до появления магазинов. Магазин по умолчанию выключить нельзя.

Магазины одни и те же в тестовом и боевом режиме: при переключении режима shop_id не меняется.

Подключение раздела

Раздел «Магазины» X-Hub подключает аккаунту по заявке. Пока раздел не подключён, пункта «Магазины» в меню кабинета нет, а страница https://app.x-hub.online/shops показывает «Раздел недоступен для вашего профиля» и кнопку «Оставить заявку в поддержку». Заявку можно отправить и письмом на support@x-hub.online.

После подключения раздел появляется в меню кабинета: «Настройки → Магазины».

Типичная схема

Три бота продают через один аккаунт. Первый работает в магазине по умолчанию, для двух других заведены магазины «Бот доставки» и «Бот подписок».

  1. Все три бота создают платежи одним ключом аккаунта. Второй и третий передают в shop_id свой магазин, первый может shop_id не передавать.
  2. Уведомления всех трёх ботов приходят на один адрес вебхука. Обработчик проверяет подпись одним секретом и по shop_id передаёт событие нужному боту.
  3. Оборот каждого бота виден в «Магазинах». Баланс и выплаты общие на аккаунт.

Ключ и секрет общие, поэтому перевыпуск секрета в кабинете («Разработчикам → API») меняет его сразу для всех магазинов.

Шаг 1. Создать магазин

«Настройки → Магазины» → «Новый магазин». Введи название и нажми «Создать». Откроется карточка нового магазина, магазин сразу в состоянии «Работает».

Требования к названию:

  • от 1 до 120 символов; пробелы по краям отбрасываются, управляющие символы (перевод строки, табуляция) не допускаются;
  • не совпадает с названием другого магазина аккаунта без учёта регистра: «Бот» и «бот» считаются одним названием.

Переименовать магазин можно в карточке кнопкой «Переименовать», требования те же. Название может меняться, shop_id не меняется никогда — в своём коде опирайся на shop_id, а не на shop_name.

Шаг 2. Узнать shop_id

Карточка магазина → блок «ID магазина» → «Скопировать». Это UUID без префикса, тот же, что приходит в поле shop_id вебхуков и объекта платежа.

Метода API со списком магазинов нет. У уже созданного платежа shop_id есть в ответе GET /api/v1/payments/{id} и в вебхуках по нему.

Шаг 3. Принимать платежи в магазин

Передай shop_id в теле POST /api/v1/payments:

curl -X POST https://api.x-hub.online/api/v1/payments \
  -H "X-Api-Key: xh_live_..." -H "X-Api-Secret: ..." \
  -H "Idempotency-Key: 5b1f0c1e-9a3b-4c2d-8e4f-0123456789ab" \
  -H "Content-Type: application/json" \
  -d '{"amount_rub": "500.00", "payment_method": "sbp", "shop_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

Без shop_id платёж попадает в магазин по умолчанию. Как выбирается магазин и какие бывают отказы — Магазин платежа.

  • Подписка. shop_id передаётся при создании в POST /api/v1/subscriptions, все списания по подписке попадают в её магазин — Подписки: API.
  • Платежи одного магазина. GET /api/v1/payments?shop_id=<uuid> отдаёт только платежи этого магазина; для магазина по умолчанию — вместе с платежами, созданными до появления магазинов. Параметры списка — Платежи.
curl "https://api.x-hub.online/api/v1/payments?shop_id=7c9e6679-7425-40de-944b-e07fc1f90ae7&status=paid" \
  -H "X-Api-Key: xh_live_..." -H "X-Api-Secret: ..."

Шаг 4. Разбирать вебхуки по магазину

Адрес вебхука и секрет подписи задаются один раз на аккаунт: «Разработчикам → Вебхуки». Уведомления всех магазинов приходят туда. В payment.status_changed и в событиях refund.* есть поля shop_id и shop_name:

{
  "event": "payment.status_changed",
  "payment_id": "pay_550e8400-e29b-41d4-a716-446655440000",
  "external_id": "order-12345",
  "status": "paid",
  "previous_status": "processing",
  "amount_rub": "500.00",
  "actual_amount_rub": "500.00",
  "amount_usdt": null,
  "payment_method": "sbp",
  "refund_pending": false,
  "timestamp": "2026-04-14T13:05:12Z",
  "metadata": {"user_id": "usr_abc"},
  "shop_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "shop_name": "Бот доставки"
}

Направляй событие в нужный магазин по shop_id. В остальных событиях полей магазина нет. Подробнее — Магазин в теле события.

Шаг 5. Смотреть оборот по магазинам

«Настройки → Магазины» — список магазинов с оборотом за период: «Всё время», текущий месяц, «7 дней», «Сегодня» или «Свой период».

  • Оборот считается по оплаченным платежам: в рублях — до комиссии, в USDT — после начисления. Пока начисления не было, вместо суммы в USDT написано «итог после начисления».
  • «Платежей» — число оплаченных платежей. «Доля» — доля магазина в обороте аккаунта за период.
  • Период считается по календарным суткам UTC.
  • В тестовом режиме показаны цифры тестовой среды.

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

Выплата одна на аккаунт. Из каких магазинов она сложилась, видно в «Выплатах»: раскрой выплату, блок «Состав выплаты».

Шаг 6. Выключить магазин

Карточка магазина → «Выключить» → подтвердить. Обратно — кнопкой «Включить» в той же карточке.

Пока магазин выключен:

  • POST /api/v1/payments и POST /api/v1/subscriptions с его shop_id получают 403 SHOP_DISABLED, платёж и подписка не создаются;
  • платежи без shop_id по ключу аккаунта принимаются как обычно и попадают в магазин по умолчанию;
  • уже созданные платежи магазина проходят как обычно;
  • история, оборот и GET /api/v1/payments?shop_id= по магазину остаются доступны;
  • оформленные подписки магазина не отменяются; чтобы остановить списания, отмени подписки — Пауза и отмена.
HMAC-SHA256 CABINET ↗