Configure access
Ask the venue administrator to configure and publish the reservation public channel, booking rules, allowed website origins and contact-verification delivery. Use the resulting publicHandle. Browser requests preserve the actual allowed Origin; an absent or disallowed origin can be rejected. When the operation declares x-hallify-connection-id, it is an optional nonsecret header selecting the configured presentation and does not replace an issued grant's authority.
Cabinet route: /venues/:venueId/reservations → Rules → Public channel. Configuration requires reservations.rules.manage. A website origin is the scheme, hostname and optional port, without a path.
Configure the guarantee on its owning service period in Rules → Service periods: NONE, DEPOSIT, PREPAID or CARD_HOLD, fixed or per-guest amount, minimum party size, payment and free-cancellation deadlines, and permitted late-cancellation/no-show forfeiture. Existing accepted terms remain frozen when policy changes. Restaurant-owned merchant bindings for RESERVATION_GUARANTEE are a separate protected setup prerequisite.
Widget configuration, availability, guarantee offers and new intents use the actual isolated frame Origin and current storefrontWidgetContext. Ordinary canonical/headless flows keep native Origin admission. Original intent replay and private manage continuation retain the exact parent/connection provenance; refreshing presentation proof never renews native deadlines.
First successful workflow
Follow these steps in order. Open each method for its exact body, required headers and response schema.
- Read configuration, native contact-verification options and availability for the venue-local date and party size. Select an exact native service period and slot.
- Read guarantee-offer for that servicePeriodId, scheduledAt and partySize. When required, show its exact terms and ask the guest to accept them before creating a booking intent.
- Create the booking intent with the accepted guaranteeTermsHash when required, current terms/privacy versions and an Idempotency-Key. Remote waitlist admission uses its separate intent contract.
- Retain the original intent identity and expiry. Read its current verification state and ask for the actual delivered code before the applicable code and hold deadlines.
- Verify the intent with its own saved command key. Keep the original result and manage capability separately from nullable current management enrichment.
- Read the owned reservation. If its current native guarantee requires payment, enter the separate guest-payments flow with genuine RESERVATION_MANAGE authority. Confirm only when the current allowedActions and server rules permit it.
Review the exact slot and guarantee digest
The offer read creates no reservation, capacity hold or payment. It binds the selected slot, party size, native service-period revision, guarantee kind, amount basis, exact two-decimal principal/currency, absolute dueAt, freeCancellationAt and noShowAfter, forfeiture policy and terms/privacy versions.
When required is true, show the returned terms before an explicit affirmative action and copy termsHash verbatim into guaranteeTermsHash on the booking intent. Do not calculate your own amount or digest. A changed slot, party or policy requires a new review; stale acceptance is rejected instead of silently repricing.
NONE, or a party below the policy threshold, returns required: false with terms: null and termsHash: null. This is an explicit no-obligation result. A missing response, rejected origin or unavailable merchant is not NONE. The fragment below is a synthetic NONE response, not a live booking.
{
"required": false,
"terms": null,
"termsHash": null
}Keep original intent receipts and current verification separate
Create-intent returns original intentId, verificationId and expiresAt plus currentState/current enrichment. A lost response is retried with the original key and identical body. currentState: UNAVAILABLE with current: null does not undo the original command or authorize another intent.
read-intent discloses only redacted state for the owning channel and original request fingerprint under current Origin/presentation authorization. The identifier alone grants no authority. It returns no contact, code, reservation details or manage token, creates no booking and extends no deadline. It declares public access; do not invent a separate intent Bearer credential.
Use serverTime, expired and canVerify together with verification.expiresAt, attemptsRemaining, canResend and resendAvailableAt. Code expiry and intent/hold expiry are separate. Queued/sending delivery is unfinished; sent/delivered does not verify the code. UNKNOWN or failure does not justify a replacement send. A resend acknowledgement is the original acceptance, with separate current delivery metadata.
After an uncertain verify response, replay that exact verify command to recover its original result. A consumed intent read cannot disclose or renew the manage capability. Start a fresh intent after proven expiry only when no conversion remains unresolved, then refresh availability and review current terms.
Read actual management state before acting
The verify result retains its original entity identity, reference, revision, status, events and original manage grant. Its separate currentState/current is a current authorized management view; it may be unavailable without changing the committed receipt. Subsequent management commands also retain their original business result and expose manageAccessState for the original successor capability.
Use the current management read for revision, allowedActions, serverTime, guarantee and pendingAgreement. A historical receipt cannot advertise current confirmation, payment or restoration. Reads never renew grantExpiresAt. If management authority is expired, superseded or requires reproof, do not reuse historical status as authorization or fabricate a replacement token.
For a guest-initiated financial slot/party change, review a fresh exact offer and send guaranteeTermsHash with the current expectedRevision to change-reservation. The current manage grant supplies that guest acceptance. An agreementChange receipt can remain ACCEPTED while the actual reservation keeps its old slot pending disposition and activation. Follow current state rather than resubmitting the change.
Waitlist management remains separate. A notified entry can be claimed only within its current claim window and allowedActions; CLAIM changes it to CLAIMED and does not create a reservation. A public handle never grants access to the restaurant’s full reservation list.
Explicitly verify and accept a CHANGE or RESTORE proposal
A staff-proposed financial CHANGE or RESTORE uses an exact frozen agreement identified by changeId. A proposal link or contact value supplies no management or financial authority. These public operations review and accept an existing proposal; they do not expose a public staff proposal or restoration command.
The challenge uses the existing guest contact type/value and display name. Verify with its returned capability and the actual delivered code in the same Origin/request context. Successful verification matches the existing native guest before revealing the frozen agreement and issuing a separate acceptance capability. Verification alone accepts no terms and restores no reservation.
Show the verified agreement’s action, proposed slot/end, party size and offer. After a deliberate affirmative action, accept with that capability and the exact agreement.planHash. planHash binds the full proposal; it is distinct from offer.termsHash and from a payment consent digest. Each of challenge, verify and accept has its own saved Idempotency-Key and exact retry body.
Acceptance returns original plus separate manageToken, manageTokenExpiresAt, manageAccessState and currentState/current. Original ACCEPTED is durable acceptance evidence. Old captured funds must actually be refunded, or an old authorization released, and unresolved original payment work must settle before native capacity admission can activate the proposal. Scheduling a disposition is unfinished work.
Current proposal states include PENDING, ACCEPTED, ACTIVATED, EXPIRED and SUPERSEDED. A canceled/no-show/expired reservation remains terminal until activation; acceptance alone does not restore it. Activation rechecks the frozen source, deadlines, commercial access and capacity. Failure or expiry does not renew a deadline, silently replace terms or permit a new guarantee charge. Read current management and retain the original command for recovery.
Pay the actual native guarantee
Open guest payment access with kind: RESERVATION_MANAGE, resourceId equal to the native reservation UUID and its current private manage capability, under the actual source Origin. The server resolves its exact current native guarantee. A waitlist, proposal identifier, observer ticket, contact code or account session cannot substitute for this source.
The genuine guarantee bill/quote has purpose: RESERVATION_GUARANTEE and guarantee review, with no Order targets. Submit only purpose, an eligible merchantBindingId and locale for the guarantee quote; omit targets and requestedTipAmount entirely. The server derives principal, zero tip, currency and capture mode. Review the legal payee and exact retained payment consent in addition to the original reservation terms.
DEPOSIT and PREPAID use AUTOMATIC capture. CARD_HOLD uses MANUAL authorization; it is not captured money. Native satisfaction requires authenticated provider evidence for the exact amount and a live authorization whose expiry covers the accepted protection period. A provider redirect, original PREPARED checkout receipt or terms acceptance proves none of these outcomes.
Retain the original payment command and distinguish read-only receipt/progress recovery from explicit financial recovery. UNKNOWN keeps the original unresolved; no automatic new command or charge is allowed. Refetch current reservation guarantee and allowedActions from native management; never convert a checkout acknowledgement into confirmation or ACTIVATED agreement state.
Keep guest and staff financial authority separate
forfeitGuarantee and applyGuaranteeCredit are protected staff operations, absent from the public/headless allowlist. Late cancellation or no-show never triggers a public automatic card debit. Staff forfeiture follows the original accepted policy and real provider/Financial evidence. Credit applies captured DEPOSIT/PREPAID principal to an actual seated Order under staff authorization; a guest cannot submit a guessed Order or payer. The staff credit form obtains the real current Order revision through protected Order GetById and submits it with the reservation revision. That read field grants no public guest/headless permission and introduces no guest endpoint.
Examples are synthetic and execute no booking, contact verification or provider request. Source supports hosted/shared/custom and isolated widget booking with the same native terms, explicit acceptance and original recovery. The JS/TS SDK adds no staff permissions or financial consent. Database, browser, deployed-domain and merchant/provider qualification remain separate.