Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Guides

Guest payments

Use current native QR, preorder or reservation manage authority to review, explicitly accept and recover one original restaurant payment.

Enable the exact native payment source

An authorized operator configures the restaurant-owned merchant connection and eligible venue, channel, purpose and currency bindings in the organization's Payment connections screen. Bank credentials and Stripe enrollment remain in that protected workspace. An eligible choice in the guest bill comes from current server configuration, not a provider selected by client input.

For QR, enable paymentScope in the staff QR policy: DISABLED is the default; ASSIGNED_ITEMS permits the current guest's assigned portions; SESSION_BILL permits the session bill within current native authority. For public off-premise orders, enable allowGuestPayments in /venues/:venueId/settings/fulfillment → Resources → Public channel; it defaults to false. Neither setting creates a collectible Order or substitutes for current native eligibility.

The server's HALLIFY_GUEST_CHECKOUT_ORIGIN defaults to https://hallify.co. It must be an exact member of HALLIFY_APP_ORIGINS and match the backend's trusted PSP continuation origin. Invalid configuration makes checkout unavailable. Deployment configuration belongs to the responsible operator; these public APIs cannot configure it or bypass the unknown-host gate.

QR_MEMBERSHIP and PREORDER_MANAGE fund positive ORDER_BILL principal for accepted native Orders with AUTOMATIC capture. RESERVATION_MANAGE funds the exact native RESERVATION_GUARANTEE: DEPOSIT/PREPAID use AUTOMATIC capture and CARD_HOLD uses MANUAL authorization. Current eligible bindings determine provider support in USD or GEL. A public locator, draft, observer READ capability or Hallify account session cannot replace native payment authority. Examples are synthetic and send no requests from this documentation page.

Start with native access and a read-only bill

Use the current native guest context from your own private integration. The first request opens bounded payment access; it does not charge the guest. On another origin, complete the receiver-first handoff before reading the bill on the checkout origin.

  1. Call open-access with the native kind, exact resource UUID and its current private capability in the request body. Preserve the returned accessId, payment capability, transportOrigin and deadlines in the private tab context.
  2. Using that payment capability and the exact transport origin, call read-bill for the same accessId. Display the returned payee, collectible principal and eligible merchant choices; an empty choice list makes payment unavailable.
  3. Continue with the review example below. Obtain explicit consent before submitting one saved checkout command key; retain the original receipt for recovery.

Separate the original receipt, funds and native application

Checkout creation retains one original PREPARED acknowledgement. That immutable command result is separate from current provider progress, fundsState and native applicationState. Read and recover the original identity after a lost response or reload; a later provider event does not replace the original receipt.

Financial success requires retained server evidence for the funds and native application APPLIED. UNKNOWN, pending or blocked application remains unresolved. Expiry, denied authority and a browser return never prove success or authorize a replacement payment. Follow the original checkout recovery instructions and require fresh explicit native intent for any later payment.

Keep payment access separate from native access

Open access with kind, resourceId and the current private native capability in the JSON body. QR_MEMBERSHIP addresses the table-session UUID; PREORDER_MANAGE addresses the accepted native fulfillment UUID; RESERVATION_MANAGE addresses the native reservation UUID and its exact current guarantee. The server rechecks native payment eligibility and actual Origin. Save accessId, the private gpa1_ capability, transportOrigin and both deadlines inside the owning private flow; the access UUID alone grants no authority.

The original financialExpiresAt is at most fifteen minutes after access issuance, bounded by native and presentation authority. It limits preparation, acceptance and new financial permits. expiresAt is the separate own-original-receipt deadline, at most twenty-four hours and no later than native or presentation authority. Receipt disclosure still requires the exact consumed consent/Core links and current original-resource authority; a longer receipt deadline cannot authorize another payment.

The three access/handoff commands carry credentials only in their private bodies. The seven bill/quote/offer/checkout operations instead require Authorization: Bearer with the payment-access capability, accessId and the exact transport Origin. Browser requests use credentials: 'omit', cache: 'no-store' and redirect: 'error'; the browser supplies Origin. Keep request bodies, capabilities and private responses out of Redux actions/caches, URLs, cookies, logs, analytics and error payloads.

Use a receiver-first origin-bound handoff

Direct native entry is allowed only when the actual source origin equals the configured checkout origin. A cross-origin headless integration uses one top-level tab and a receiver-first roundtrip. Receiver pending data is UNVERIFIED: correlation, hashes and identifiers alone grant no authority. Backend issue and redeem must still verify current native and presentation authority.

The receiver alone generates and privately saves its fresh gpa1_ capability before returning its SHA-256 digest. The source receives only that digest and correlation, never the receiver's raw capability. The source keeps its own native and payment-access capabilities on the original origin. The private gph1_ handoff is saved on the source before issue so a lost response can repeat the exact proposal; its initial redemption deadline is at most sixty seconds within the original access/native deadlines.

Validate the actual origins and complete flow/access/scope/deadline correlation on every leg. The integrator must implement its source callback at a safe path on the same actual source origin. URLs carry only nonsecret context; the private handoff travels in the deliver POST body. The receiver redeems using its already saved raw capability. Exact replay recovers the same access/audience and never renews financial or receipt deadlines.

The /guest/payments/bridge resource coordinates ordinary private POST handoff; /guest/payments/continue is source continuation and /guest/payments/checkout the hosted payment view. Isolated widgets instead prepare a saved private transition for a fixed-destination top-level form POST before the receiver claims and redeems the ordinary handoff. Raw native/payment-access capabilities never cross to a parent or receiver. Do not relax app-wide CSP or depend on popup/opener access.

  1. Prepare source → canonical receiver with nonsecret flow, access, scope and deadline context.
  2. The receiver privately saves its capability/readback context and returns only its capability digest and correlation to the source callback.
  3. Using current native/private payment access, the source issues its saved handoff bound to that receiver digest.
  4. Deliver source → receiver with the private handoff and exact correlation; the receiver redeems using its saved capability. Stop on missing state, mismatched correlation, expiry or denied current authority.

Review the server bill, payee and item allocations

Read the collectible native bill and eligible merchant choices. Zero collectible principal is valid and offers no payment choice; do not manufacture a positive bill or submit a tip-only payment. Show the server-authoritative payee.venueName and payee.legalName, not a client label inferred from the provider. Native paid portions, active holds and assignment policy constrain item availability.

For an Order bill, request a quote for one eligible merchantBindingId, one to fifty distinct Orders, requestedTipAmount and consent locale en, ru or ka. Principals must be positive two-decimal strings; tip is a nonnegative two-decimal string. items is required: null requests canonical allocation, while an explicit array contains positive four-decimal quantities. At most five hundred selected items are permitted across all Orders. Actor, payer, currency, provider mode, AUTOMATIC capture and return destination come from verified server state. Reservation guarantee selection uses the separate shape below.

The quote is a review, not consent, a financial hold or a provider request. Render its canonical payee, amounts, item allocations and exact terms.text. The synthetic selection below only illustrates request shape; its UUIDs identify no real merchant or Order.

Request examples
const selection = {
  merchantBindingId: '2604de3a-da74-4ad5-89f6-2dfe000d5391',
  requestedTipAmount: '0.00',
  locale: 'en',
  targets: [
    {
      orderId: '3604de3a-da74-4ad5-89f6-2dfe000d5391',
      principalAmount: '12.50',
      items: null,
    },
  ],
};

Review a genuine reservation guarantee

Reservation entry requires a current private reservation manage grant with native READ scope and actual source/presentation authority. It is not the observer ticket that can be issued from READ, a waitlist grant or a proposal ID. Current native status, accepted terms and guarantee deadline control eligibility; do not treat management access alone as permission to charge.

The guarantee bill has purpose: RESERVATION_GUARANTEE, a guarantee review and orders: []. Its quote has the same purpose/review and empty Order targets. Submit only purpose, merchantBindingId and locale: omit both targets and requestedTipAmount, including null or zero placeholders. The native guarantee supplies the exact full principal, currency, zero tip and capture method. The synthetic selection below identifies no live merchant or booking.

Show the original guarantee termsHash/terms, payment due time, payee and the quote’s exact consent wording. Reservation termsHash and agreement planHash do not replace quoteHash or the retained payment manifestHash. Consent and checkout use the same original-command protocol as bill payment; no client input can select a different guarantee, amount or capture mode.

DEPOSIT/PREPAID require actual capture and native application. CARD_HOLD is a MANUAL authorization, separate from captured funds. Native satisfaction requires authenticated authorization evidence for the exact accepted principal and a live captureBefore covering the accepted protection interval; initial authorizationExpiresAt may be null. A redirect, AUTHORIZED/PREPARED label alone or scheduled capture is insufficient. Read funds/application state and current native guarantee separately. Staff capture, release, refund, forfeiture and seated-Order credit remain protected operations.

Request examples
const selection = {
  purpose: 'RESERVATION_GUARANTEE',
  merchantBindingId: '2604de3a-da74-4ad5-89f6-2dfe000d5391',
  locale: 'en',
};

Retain one original command and acknowledgement

Before the explicit acceptance request, save one client-generated idempotency-key and the exact acceptance payload in the owning private flow. Create consumes that precise consent and retains the original checkout, holds and permanent Core acknowledgement. Identical command replay preserves the first PREPARED acknowledgement and original checkout/operation identities; it does not reprice or create another payment.

PREPARED in the acknowledgement describes the first retained result, even when financial progress has since changed. Fresh creation can attempt provider dispatch under current authority. A lost HTTP response does not prove that creation or dispatch failed. Retain the original key rather than allocating a replacement command or automatically accepting a new offer.

Separate receipt reads from financial recovery

After reload, continuation or provider return, use the saved original commandKey with commands/recover, then GET the original checkout progress. These reads create no new intent or provider request. Own-receipt disclosure remains bound to current capability, Origin, original native resource and consumed consent/Core links; an identifier or an old acknowledgement alone is insufficient.

POST checkouts/:checkoutId/recover is an explicit user action with possible financial effects. Already dispatched operations can use retained SYSTEM readback. An unsent original, or an exact original Stripe CREATE retry without a surviving provider locator, requires current spending authority and an original frozen-request permit within the saved financial deadline. Never invoke this mutation automatically on mount, reload or return.

UNKNOWN, a retryable decline or a transport failure does not authorize a new command, release holds or establish terminal failure. Show the server's state, fundsState, applicationState, terminal and retryAt separately. Reconciliation-required progress needs the owning operational recovery; a scheduling hint grants no spending authority.

Resume the saved flow without extending authority

The private source journal uses a stable sourceScopeKey derived from the original origin, native kind/resource and stable nativeActorContext. Access or transport rotation must not create another scope. Retain each original key, acceptance and receipt; unresolved work blocks replacing the flow. Resume saved work after reload, continuation and UNKNOWN instead of automatically opening fresh access or extending deadlines.

For an ASAP or scheduled native preorder, use manage.paymentActorReference as the server-issued stable actor partition, with sourceContextKey preorder:<hint>. This optional nullable value is an opaque SHA-256 reference of exactly sixty-four lowercase hexadecimal characters, supplied only for verified initial public EXCHANGE and original CREATE acceptance lineage. Keep the same partition through SESSION exchange or capability rotation; do not derive it from a changing client contextKey, access ID or fulfillmentId. A missing/null reference or LEGACY/unprovable lineage makes payment entry unavailable, without a fulfillmentId fallback. The hint is not a credential or financial authority, and the manage GET mints no payment access.

An explicit native Pay action may open fresh access for a new intent; each access has one financial consent. Only proven server-terminal progress permits an explicit new payment with fresh native access. Keep prior checkout_id entries recoverable within their own disclosure deadlines, and never treat missing local state as proof of a terminal server result. Private persistence belongs to the domain's bounded tab context, outside account cookies and global application state.

Treat provider navigation as navigation only

Use only provider navigation returned for the original checkout and its retained deadline. /guest/payments/return is the canonical frozen PSP return path. checkout_id and outcome are noncredential navigation context; redirects, return parameters and a successful browser page do not prove authorization, capture or native financial application.

Return to saved read-only command recovery/progress. Financial success requires the server's retained funds evidence and native APPLIED application, not the immutable PREPARED acknowledgement or operation state alone. Neither provider navigation nor handoff renews a financial, offer, access or receipt deadline.

Handle denied authority and preserve scope

Follow each operation's documented status and stable machine code. Bad input and stale financial review are different from hidden unavailability of a native source, private capability or original checkout. A 404 must not trigger account fallback, a guessed native resource, an Origin rewrite or an automatic replacement payment. A conflict requires inspecting the original command and current review, not blindly choosing a new key.

No public guest capture, void, refund, forfeiture or seated-Order credit operation is exposed. Widget payment uses its private top-level transition, ordinary receiver-bound handoff, explicit consent and original checkout recovery. The SDK supplies those exact methods without a second ledger, cache or replacement-command policy. Courier dispatch, npm publication and live DB/HTTP, browser/storage/domain or Stripe/BOG/TBC qualification remain separate.

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.