Оплаты и депозиты

Платёжная часть Hostme: депозиты и предоплаты по бронированиям, сборы и статусы оплат.

Раздел описывает платёжную часть Hostme: депозиты и предоплаты по бронированиям (платёжные intent, секреты, статусы оплаты, возвраты), а также сервисные эндпоинты для платёжных карт, тарифных планов и подписки самого ресторана.

Все эндпоинты — под Bearer-токеном (см. Аутентификация) и расположены под базовым путём /api/core/payment. Платёжные операции по броням напрямую связаны с полями BookingContract: depositToken, depositStatus, paymentType, intentClientSecret, paymentLinkUrl, details.paymentLinkUrl — см. раздел Бронирования.

Метод	Путь	Назначение
`POST`	`/restaurants/{restaurantId}/intents`	Создать платёжный intent (получить секрет)
`POST`	`/restaurants/{restaurantId}/reservations/{reservationId}/refund`	Вернуть депозит по броне
`GET`	`/restaurants/{restaurantId}/cards`	Список платёжных карт
`POST`	`/restaurants/{restaurantId}/cards`	Привязать карту
`PUT`	`/restaurants/{restaurantId}/cards/{cardId}`	Сделать карту картой по умолчанию
`DELETE`	`/restaurants/{restaurantId}/cards/{cardId}`	Удалить карту
`GET`	`/restaurants/{restaurantId}/charges`	История списаний
`GET`	`/restaurants/{restaurantId}/plans`	Список тарифных планов
`GET`	`/restaurants/{restaurantId}/subscriptions`	Подписки ресторана

Депозиты и предоплаты по бронированиям

Если в ресторане настроены предоплаты или депозиты, в брони (BookingContract) появляются платёжные поля. Они заполняются при создании/обработке брони и обновляются по ходу оплаты:

Поле брони	Тип	Назначение
`paymentType`	string	Тип оплаты по броне
`depositToken`	string	Токен депозита (передаётся при создании брони с предоплатой)
`depositStatus`	string	Статус оплаты депозита
`isDeposit`	boolean	Признак того, что платёж — депозит
`amount`	number	Сумма к оплате
`receiptAmount`	number	Фактическая сумма чека
`currency`	string	Валюта
`cardAttached`	boolean	Привязана ли карта гостя
`paymentCustomerId`	string	Идентификатор плательщика в платёжной системе
`intentClientSecret`	string	Клиентский секрет платёжного intent (для подтверждения оплаты на стороне гостя)
`paymentLinkUrl`	string	Ссылка на оплату
`redirectLinkUrl`	string	URL для редиректа после оплаты
`details.paymentLinkUrl`	string	Ссылка на оплату внутри блока `details`
`details.paymentError`	string	Текст ошибки оплаты, если она была

Поле depositToken передаётся при создании брони и привязывает предоплату к бронированию. Дальнейший статус смотрите в depositStatus и details.paymentError.

Создать платёжный intent

POST /restaurants/{restaurantId}/intents

Создаёт платёжный intent и возвращает секрет, которым гость подтверждает оплату на своей стороне (в платёжном виджете). Используется при оформлении депозита/предоплаты.

Параметр	Где	Тип	Описание
`restaurantId` *	path	integer	Идентификатор ресторана

Ответ — `IntentSecretContract`

Поле	Тип	Описание
`secret`	string	Клиентский секрет для подтверждения платежа
`paymentMethod`	object `GuestPaymentMethod`	Способ оплаты (enum: `0`, `1`)

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/intents \
  -H "Authorization: Bearer $TOKEN"

Полученный secret соответствует полю intentClientSecret в BookingContract и используется фронтендом гостя для завершения оплаты.

Вернуть депозит

POST /restaurants/{restaurantId}/reservations/{reservationId}/refund

Возвращает депозит (полностью или частично) по конкретной броне. Сумма возврата задаётся в теле запроса; в ответ приходит обновлённая бронь.

Параметр	Где	Тип	Описание
`restaurantId` *	path	string	Идентификатор ресторана
`reservationId` *	path	string	Идентификатор брони

Тело — `PaymentRefundContract`

Поле	Тип	Описание
`amount`	number	Сумма возврата

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/reservations/RID/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25.00 }'

Ответ. Возвращается обновлённая бронь (BookingContract) — проверьте поля depositStatus, receiptAmount и details.paymentError, чтобы убедиться в успехе возврата. Полную структуру BookingContract см. в разделе Бронирования.

Платёжные карты ресторана

Карты используются для оплаты подписки и сервисных списаний самого ресторана.

Список карт

GET /restaurants/{restaurantId}/cards

Возвращает массив карт PaymentCard.

Поле	Тип	Описание
`id`	string	Идентификатор карты
`name`	string	Название/владелец
`brand`	string	Платёжная система (Visa, Mastercard, …)
`last4`	string	Последние 4 цифры
`expirationMonth`	integer	Месяц истечения
`expirationYear`	integer	Год истечения
`isDefault`	boolean	Карта по умолчанию

curl https://api.hostmeapp.com/api/core/payment/restaurants/123/cards \
  -H "Authorization: Bearer $TOKEN"

Привязать карту

POST /restaurants/{restaurantId}/cards

Тело — TokenContract: токенизированные данные карты.

Поле	Тип	Описание
`value`	string	Платёжный токен карты
`email`	string	Email плательщика
`fullName`	string	Имя владельца

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/cards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "tok_ABC_ID", "email": "owner@example.com", "fullName": "Иван Петров" }'

Карта по умолчанию

PUT /restaurants/{restaurantId}/cards/{cardId}

Делает указанную карту картой по умолчанию.

Параметр	Где	Тип
`restaurantId` *	path	integer
`cardId` *	path	string

Удалить карту

DELETE /restaurants/{restaurantId}/cards/{cardId}

Отвязывает карту от ресторана.

Параметр	Где	Тип
`restaurantId` *	path	integer
`cardId` *	path	string

История списаний

GET /restaurants/{restaurantId}/charges

Возвращает список списаний с пагинацией.

Параметр	Где	Тип	Описание
`restaurantId` *	path	integer	Идентификатор ресторана
`skip`	query	integer	Сколько записей пропустить
`take`	query	integer	Сколько записей вернуть

curl -G https://api.hostmeapp.com/api/core/payment/restaurants/123/charges \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "skip=0" \
  --data-urlencode "take=20"

Точная схема успешного ответа (200) в спецификации не зафиксирована — структура списаний возвращается платёжной системой.

Тарифные планы и подписка ресторана

Эта группа эндпоинтов управляет подпиской самого ресторана на Hostme (тарифы, оформление, отмена). Для большинства партнёрских интеграций она не требуется.

Список планов

GET /restaurants/{restaurantId}/plans

Возвращает массив PaymentPlanContract.

Поле	Тип	Описание
`id`	string	Идентификатор плана
`name`	string	Название
`currency`	string	Валюта
`amount`	integer	Стоимость
`interval`	string	Период списания
`intervalCount`	integer	Количество периодов
`status`	string	Статус плана
`liveMode`	boolean	Боевой режим (не тест)
`trialPeriodDays`	integer	Дней пробного периода
`created`	date-time	Дата создания
`metadata`	object `ExtraPlanData`	Доп. данные плана: `appId`, `features`, `price`, `discount`, `pos`, `mailing` и др.

curl https://api.hostmeapp.com/api/core/payment/restaurants/123/plans \
  -H "Authorization: Bearer $TOKEN"

План по ID

GET /restaurants/{restaurantId}/plans/{planId}

Возвращает один план по идентификатору (planId — path).

Отправить план на email

POST /restaurants/{restaurantId}/plans/{planId}/email

Тело — PaymentPlanMailContract: { "email": "..." }. Отправляет описание плана на указанный адрес.

Оформить подписку

POST /restaurants/{restaurantId}/subscriptions

Тело — PaymentCreateSubscriptionContract.

Поле	Тип	Описание
`planId`	string	Идентификатор тарифного плана
`couponId`	string	Купон/скидка
`fullName`	string	Имя плательщика
`email`	string	Email
`intentId`	string	Идентификатор платёжного intent
`paymentCustomerId`	string	Идентификатор плательщика

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "planId": "plan_ABC_ID", "fullName": "Иван Петров", "email": "owner@example.com" }'

Текущие подписки

GET /restaurants/{restaurantId}/subscriptions

Возвращает подписки ресторана.

Использование подписки

GET /restaurants/{restaurantId}/subscription/usage

Возвращает данные об использовании в рамках подписки (квоты, расход).

Отменить подписку

DELETE /restaurants/{restaurantId}/subscriptions/{subscriptionId}

Тело — CancelationReasonContract.

Поле	Тип	Описание
`reason`	string	Причина отмены
`newVendorName`	string	Имя нового поставщика (если переход)
`customReasonMessage`	string	Свободный комментарий

Отзыв при отмене

POST /restaurants/{restaurantId}/subscriptions/{subscriptionId}/feedback

Тело — CancelationFeedbackContract: experience, customExperienceMessage. Собирает обратную связь после отмены подписки.

Напоминание об оплате

POST /restaurants/{restaurantId}/remind

Отправляет напоминание о необходимости оплаты подписки.

Прочее

POST /restaurants/{restaurantId}/accounts — создание платёжного аккаунта (тело — TokenContract: value, email, fullName).
GET /restaurants/{restaurantId}/customer — данные плательщика ресторана.
DELETE /restaurants/{restaurantId}/customer — удаление плательщика.

Эндпоинты POST /payment/events и POST /payment/events/{appId} — служебные вебхуки платёжной системы; в партнёрских интеграциях напрямую не вызываются.

Общие правила запросов и кодов ошибок — в разделах Соглашения и Ошибки. Поля платежей в составе брони описаны в разделе Бронирования.