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

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

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

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

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

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

POST /restaurants/{restaurantId}/intents — создать платёжный intent

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

Ответ — IntentSecretContract

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 — вернуть депозит

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

Тело — PaymentRefundContract

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.

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

POST /restaurants/{restaurantId}/cards — привязать карту

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

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} — карта по умолчанию

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

DELETE /restaurants/{restaurantId}/cards/{cardId} — удалить карту

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

GET /restaurants/{restaurantId}/charges — история списаний

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

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.

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

GET /restaurants/{restaurantId}/plans/{planId} — план по ID

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

POST /restaurants/{restaurantId}/plans/{planId}/email — отправить план на email

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

POST /restaurants/{restaurantId}/subscriptions — оформить подписку

Тело — PaymentCreateSubscriptionContract.

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.

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} — служебные вебхуки платёжной системы; в партнёрских интеграциях напрямую не вызываются.

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