---
title: "Магазины"
url: "https://docs.x-hub.online/shops/"
description: "Несколько магазинов на одном аккаунте: создать магазин, направить в него платёж, различать магазины в вебхуках и в обороте."
relatedDocuments:
  - "https://docs.x-hub.online/payments/"
  - "https://docs.x-hub.online/subscriptions/api/"
  - "https://docs.x-hub.online/webhooks/"
  - "https://docs.x-hub.online/subscriptions/manage/"
---

# Магазины { #shops }

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

## Что общее, а что своё { #shared }

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

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

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

## Подключение раздела { #enable }

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

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

## Типичная схема { #typical-setup }

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

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

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

## Шаг 1. Создать магазин { #create }

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

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

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

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

## Шаг 2. Узнать `shop_id` { #shop-id }

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

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

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

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

```bash
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` платёж попадает в магазин по умолчанию. Как выбирается магазин и какие бывают отказы — [Магазин платежа](../payments/index.md#shop-refusals).

- **Подписка.** `shop_id` передаётся при создании в `POST /api/v1/subscriptions`, все списания по подписке попадают в её магазин — [Подписки: API](../subscriptions/api.md).
- **Платежи одного магазина.** `GET /api/v1/payments?shop_id=<uuid>` отдаёт только платежи этого магазина; для магазина по умолчанию — вместе с платежами, созданными до появления магазинов. Параметры списка — [Платежи](../payments/index.md).

```bash
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. Разбирать вебхуки по магазину { #webhooks }

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

```json
{
  "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`. В остальных событиях полей магазина нет. Подробнее — [Магазин в теле события](../webhooks/index.md#webhook-shop).

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

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

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

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

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

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

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

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

- `POST /api/v1/payments` и `POST /api/v1/subscriptions` с его `shop_id` получают `403 SHOP_DISABLED`, платёж и подписка не создаются;
- платежи без `shop_id` по ключу аккаунта принимаются как обычно и попадают в магазин по умолчанию;
- уже созданные платежи магазина проходят как обычно;
- история, оборот и `GET /api/v1/payments?shop_id=` по магазину остаются доступны;
- оформленные подписки магазина не отменяются; чтобы остановить списания, отмени подписки — [Пауза и отмена](../subscriptions/manage.md).