Перейти к содержимому
HallifyРазработчикамПоиск по документации
Открыть Hallify
Разделы

Руководства

Гостевые платежи

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

Включите оплату для конкретного нативного источника

Уполномоченный сотрудник настраивает эквайринг ресторана и допустимые привязки заведения, канала, назначения платежа и валюты в разделе организации «Платёжные подключения». Банковские credentials и подключение Stripe остаются в защищённом кабинете. Доступные гостю варианты определяются текущей серверной конфигурацией, а не названием провайдера из клиентского ввода.

Для QR включите paymentScope в политике сотрудников: по умолчанию DISABLED; ASSIGNED_ITEMS допускает оплату назначенных текущему гостю частей, SESSION_BILL — счёта сессии в пределах текущих нативных полномочий. Для публичного заказа вне зала включите allowGuestPayments в /venues/:venueId/settings/fulfillment → Ресурсы → Публичный канал; по умолчанию false. Настройки не создают доступный к оплате Order и не заменяют текущую проверку допустимости.

Серверный HALLIFY_GUEST_CHECKOUT_ORIGIN по умолчанию равен https://hallify.co. Он должен точно входить в HALLIFY_APP_ORIGINS и совпадать с доверенным backend origin продолжения PSP. При неверной конфигурации checkout недоступен. Настройкой развёртывания занимается ответственный оператор; публичные методы её не изменяют и не обходят запрет неизвестного хоста.

QR_MEMBERSHIP и PREORDER_MANAGE оплачивают положительный principal ORDER_BILL принятых нативных заказов через AUTOMATIC capture. RESERVATION_MANAGE оплачивает точную нативную RESERVATION_GUARANTEE: DEPOSIT/PREPAID используют AUTOMATIC capture, CARD_HOLD — MANUAL authorization. Текущие допустимые привязки определяют поддержку провайдера в USD или GEL. Публичный локатор, черновик, observer READ или аккаунт не заменяют нативные платёжные полномочия. Примеры синтетические и не отправляют запросы со страницы документации.

Начните с нативного доступа и чтения счёта

Используйте текущий нативный гостевой контекст своей приватной интеграции. Первый запрос открывает ограниченный платёжный доступ и не списывает деньги. При другом origin завершите handoff с подготовкой получателя до чтения счёта на checkout origin.

  1. Вызовите open-access с нативным kind, точным UUID ресурса и его текущим приватным токеном в теле запроса. Сохраните полученные accessId, платёжный токен, transportOrigin и сроки в приватном контексте вкладки.
  2. С этим платёжным токеном и точным transport origin вызовите read-bill для того же accessId. Покажите получателя, доступную к оплате основную сумму и разрешённые варианты оплаты; пустой список вариантов означает недоступность оплаты.
  3. Продолжите по примеру проверки ниже. Получите явное согласие до отправки одного сохранённого ключа команды checkout; сохраните исходный результат для восстановления.

Разделяйте исходный результат, средства и нативное применение

Создание checkout сохраняет одно исходное подтверждение PREPARED. Этот неизменяемый результат команды отделён от текущего состояния провайдера, fundsState и нативного applicationState. После потери ответа или reload читайте и восстанавливайте исходную операцию; позднее событие провайдера не заменяет первый результат.

Финансовый успех требует сохранённых серверных сведений о средствах и нативного применения APPLIED. UNKNOWN, ожидание или блокировка применения остаются незавершёнными. Истечение срока, отказ полномочий и возврат браузера не доказывают успех и не разрешают заменяющую оплату. Восстанавливайте исходный checkout; для последующей оплаты требуется новое явное нативное действие.

Отделяйте платёжный доступ от исходного гостевого доступа

Откройте доступ, передав kind, resourceId и текущую приватную нативную capability в JSON-теле. QR_MEMBERSHIP указывает UUID сессии стола; PREORDER_MANAGE — UUID принятого нативного fulfillment; RESERVATION_MANAGE — UUID нативной брони с её точной текущей гарантией. Сервер перепроверяет допустимость оплаты и фактический Origin. Храните accessId, приватную gpa1_ capability, transportOrigin и оба срока в своём приватном сценарии; UUID доступа сам не даёт прав.

Исходный financialExpiresAt наступает не позднее пятнадцати минут после выдачи доступа и ограничен нативными полномочиями и представлением. Он ограничивает подготовку, согласие и новые финансовые разрешения. expiresAt — отдельный срок раскрытия собственного исходного результата, не более двадцати четырёх часов и не позднее срока нативных полномочий или представления. Для раскрытия по-прежнему нужны точные связи принятого consent/Core и текущие полномочия на исходный ресурс; более долгий срок результата не разрешает новую оплату.

Три команды access/handoff передают credentials только в приватных телах. Семь операций bill/quote/offer/checkout требуют Authorization: Bearer с платёжным токеном, accessId и точным transport Origin. В браузере используйте credentials: 'omit', cache: 'no-store' и redirect: 'error'; Origin отправляет браузер. Тела, токены и приватные ответы не должны попадать в Redux actions/cache, URL, cookies, логи, аналитику и сообщения ошибок.

Используйте handoff с подготовкой получателя и точным origin

Прямой нативный вход разрешён, только если фактический source origin равен настроенному checkout origin. Headless-интеграция между разными origins использует одну вкладку верхнего уровня и сначала подготавливает получателя. Его pending-данные имеют статус UNVERIFIED: correlation, хеши и идентификаторы сами по себе не дают полномочий. Backend issue и redeem всё равно проверяют текущие нативные полномочия и представление.

Только получатель генерирует и приватно сохраняет свой новый gpa1_ токен до возврата его SHA-256 digest. Источник получает только digest и correlation, но не исходный токен получателя. Свои нативный и платёжный токены источник оставляет на исходном origin. Приватный gph1_ handoff сохраняется на источнике до issue, чтобы потеря ответа позволяла повторить то же предложение; первый срок погашения — не более шестидесяти секунд в пределах исходных access/native сроков.

На каждом переходе проверяйте фактические origins и полную correlation flow/access/scope/deadlines. Интегратор обязан реализовать source callback по безопасному пути на том же фактическом source origin. URL содержат только несекретный контекст; приватный handoff передаётся в deliver POST-теле. Получатель погашает его с уже сохранённым собственным токеном. Точный повтор восстанавливает тот же доступ/audience и не продлевает финансовые сроки или срок раскрытия результата.

Ресурс /guest/payments/bridge координирует обычный приватный POST handoff; /guest/payments/continue продолжает источник, /guest/payments/checkout открывает платёжную страницу. Изолированный виджет сначала подготавливает сохранённый приватный transition для top-level form POST на фиксированный адрес, затем receiver выполняет claim и обычный redeem handoff. Сырые native/payment-access capabilities не передаются parent или receiver. Не ослабляйте общий CSP и не полагайтесь на popup/opener.

  1. Передайте prepare от источника каноническому получателю с несекретным контекстом flow, access, scope и сроков.
  2. Получатель приватно сохраняет токен/readback-контекст и возвращает в callback источника только digest токена и correlation.
  3. Используя текущий нативный и приватный платёжный доступ, источник выдаёт сохранённый handoff с привязкой к digest получателя.
  4. Передайте deliver от источника получателю с приватным handoff и точной correlation; получатель использует сохранённый токен для redeem. Остановитесь при утрате состояния, несовпадении correlation, истечении срока или отказе текущих полномочий.

Проверьте серверный счёт, получателя и распределение позиций

Прочитайте доступный к оплате нативный счёт и merchant-варианты. Нулевая доступная основная сумма допустима и не предоставляет варианта оплаты; не создавайте вымышленный положительный счёт или платёж только из чаевых. Показывайте серверные payee.venueName и payee.legalName, а не клиентскую подпись, выведенную из названия провайдера. Доступность позиций ограничена уже оплаченными частями, активными holds и политикой назначения.

Для счёта Order запросите quote с допустимым merchantBindingId, одним–пятьюдесятью различными Order, requestedTipAmount и locale согласия en, ru или ka. Principal — положительные строки с двумя десятичными знаками; чаевые — неотрицательная такая строка. items обязателен: null выбирает каноническое распределение, массив задаёт положительные количества с четырьмя знаками. На все Order допускается не более пятисот позиций. Actor, payer, валюта, режим провайдера, AUTOMATIC capture и адрес возврата берутся из проверенного состояния сервера. Гарантия брони использует отдельную форму ниже.

Quote — предварительная проверка, а не согласие, финансовый hold или запрос провайдеру. Покажите канонические сведения получателя, суммы, распределение позиций и точный terms.text. Вымышленный пример ниже иллюстрирует только форму запроса; его UUID не относятся к реальным merchant или Order.

Примеры запросов
const selection = {
  merchantBindingId: '2604de3a-da74-4ad5-89f6-2dfe000d5391',
  requestedTipAmount: '0.00',
  locale: 'ru',
  targets: [
    {
      orderId: '3604de3a-da74-4ad5-89f6-2dfe000d5391',
      principalAmount: '12.50',
      items: null,
    },
  ],
};

Проверьте настоящую гарантию брони

Для входа брони нужен текущий приватный manage-доступ с нативным scope READ и фактическими правами источника/presentation. Это не observer ticket, который может выдаваться на основании READ, не доступ листа ожидания и не ID предложения. Допустимость определяют текущий нативный статус, принятые условия и срок гарантии; сам manage-доступ не означает разрешение списать деньги.

Счёт гарантии содержит purpose: RESERVATION_GUARANTEE, данные guarantee и orders: []. Quote сохраняет тот же purpose/обзор и пустые цели Order. Передайте только purpose, merchantBindingId и locale; полностью опустите targets и requestedTipAmount, включая null или нулевые подстановки. Нативная гарантия задаёт точный полный principal, валюту, нулевые чаевые и capture method. Синтетический пример ниже не указывает на реальный эквайринг или бронь.

Покажите исходные termsHash/terms гарантии, срок оплаты, получателя и точную формулировку согласия из quote. termsHash брони и planHash соглашения не заменяют quoteHash или сохранённый платёжный manifestHash. Согласие и checkout используют тот же протокол исходной команды, что и оплата счёта; клиент не может выбрать другую гарантию, сумму или capture mode.

DEPOSIT/PREPAID требуют фактического capture и нативного применения. CARD_HOLD — MANUAL authorization отдельно от списанных средств. Для выполнения гарантии нужны аутентифицированные данные авторизации на точный принятый principal и действующий captureBefore, покрывающий принятый период защиты; исходный authorizationExpiresAt может быть null. Редиректа, одной метки AUTHORIZED/PREPARED или запланированного capture недостаточно. Читайте funds/application и текущую нативную гарантию отдельно. Capture, освобождение, возврат, удержание и зачёт к Order рассаженной компании остаются защищёнными операциями сотрудников.

Примеры запросов
const selection = {
  purpose: 'RESERVATION_GUARANTEE',
  merchantBindingId: '2604de3a-da74-4ad5-89f6-2dfe000d5391',
  locale: 'en',
};

Сохраните одну исходную команду и её подтверждение

До явного запроса принятия сохраните один клиентский idempotency-key и точное тело согласия внутри приватного сценария. Create потребляет именно это согласие и сохраняет исходный checkout, holds и постоянное Core acknowledgement. Точный replay возвращает первое PREPARED acknowledgement с исходными идентификаторами checkout/operation; он не пересчитывает цену и не создаёт другую оплату.

PREPARED в acknowledgement описывает первый сохранённый результат, даже если финансовое состояние уже изменилось. Новое создание может попытаться отправить запрос провайдеру в пределах текущих полномочий. Потерянный HTTP-ответ не доказывает, что создание или отправка не состоялись. Сохраняйте исходный ключ, не создавая заменяющую команду и не принимая новое предложение автоматически.

Отделяйте чтение результата от финансового восстановления

После перезагрузки, продолжения или возврата провайдера передайте сохранённый исходный commandKey в commands/recover, затем прочитайте исходный checkout через GET progress. Эти чтения не создают новый intent или запрос провайдеру. Раскрытие собственного результата требует текущего токена, Origin, исходного нативного ресурса и связей потреблённого consent/Core; идентификатора или старого acknowledgement недостаточно.

POST checkouts/:checkoutId/recover — явное действие пользователя с возможными финансовыми последствиями. Уже отправленные операции могут использовать сохранённый SYSTEM readback. Неотправленный original или точный повтор исходного Stripe CREATE без сохранившегося provider locator требуют текущих полномочий расходования и исходного frozen-request permit в пределах сохранённого финансового срока. Не вызывайте эту мутацию автоматически при mount, reload или return.

UNKNOWN, повторяемый decline или ошибка транспорта не разрешают новую команду, освобождение holds и вывод об окончательном отказе. Показывайте отдельно серверные state, fundsState, applicationState, terminal и retryAt. Reconciliation-required требует восстановления в соответствующем операционном процессе; подсказка расписания не даёт права расходования.

Продолжайте сохранённый сценарий без продления полномочий

Приватный журнал источника использует стабильный sourceScopeKey, полученный из исходного origin, нативных kind/resource и стабильного nativeActorContext. Смена access или transport не создаёт другой scope. Сохраняйте каждый исходный ключ, acceptance и receipt; незавершённая операция блокирует замену сценария. После reload, continuation и UNKNOWN продолжайте сохранённую работу, не открывая новый доступ и не продлевая сроки автоматически.

Для ASAP или планового нативного предзаказа используйте manage.paymentActorReference как выданный сервером стабильный раздел actor с sourceContextKey preorder:<hint>. Необязательное nullable-значение — непрозрачная SHA-256 ссылка ровно из шестидесяти четырёх шестнадцатеричных символов нижнего регистра, выдаваемая только для проверенного исходного публичного EXCHANGE и линии первоначального принятия CREATE. Сохраняйте раздел при SESSION exchange и ротации токена; не вычисляйте его из меняющегося клиентского contextKey, access ID или fulfillmentId. Отсутствие/null ссылки, LEGACY или недоказуемая линия делают платёжный вход недоступным без fallback на fulfillmentId. Подсказка не является токеном или финансовым полномочием; manage GET не выдаёт платёжный доступ.

Явное нативное действие «Оплатить» может открыть свежий доступ для нового intent; каждому access соответствует одно финансовое согласие. Только доказанный серверный terminal допускает явную новую оплату со свежим нативным доступом. Сохраняйте возможность восстановить прежние checkout_id в пределах их сроков раскрытия; отсутствие локального состояния не доказывает завершение на сервере. Приватное сохранение принадлежит ограниченному контексту вкладки домена, вне cookies аккаунта и глобального состояния приложения.

Возврат провайдера означает только навигацию

Используйте только навигацию провайдера, выданную для исходного checkout с сохранённым сроком. /guest/payments/return — канонический зафиксированный путь возврата PSP. checkout_id и outcome — несекретный навигационный контекст; redirects, параметры возврата и успешная страница браузера не доказывают авторизацию, capture или применение нативных финансовых эффектов.

Возвращайтесь к сохранённым read-only command recovery/progress. Финансовый успех требует сохранённых серверных сведений о средствах и нативного application APPLIED, а не неизменяемого PREPARED acknowledgement или одного operation state. Навигация провайдера и handoff не продлевают финансовый срок, offer, access или срок раскрытия результата.

Обрабатывайте отказ полномочий в пределах контракта

Следуйте документированным статусам и стабильным машинным кодам каждого метода. Неверный ввод и устаревшее финансовое предложение отличаются от скрытой недоступности нативного источника, приватного токена или исходного checkout. При 404 нельзя подставлять аккаунт, угадывать нативный ресурс, переписывать Origin или автоматически создавать заменяющую оплату. Конфликт требует проверки исходной команды и текущего предложения, а не слепого выбора нового ключа.

Публичных гостевых операций capture, void, refund, удержания или зачёта к Order рассаженной компании нет. Widget payment использует приватный top-level переход, обычный receiver-bound handoff, явное согласие и восстановление исходного checkout. SDK предоставляет точные методы без второго ledger, cache или политики заменяющих команд. Курьерская диспетчеризация, npm publication и live DB/HTTP, browser/storage/domain или Stripe/BOG/TBC-квалификации остаются отдельными.

Hallify использует обязательные cookies и опциональную аналитику.

Обязательные cookies поддерживают вход, язык и тему. Аналитика выключена, пока вы явно ее не разрешите.