Prepare the restaurant's payment connection
Open your organization and choose Payment connections. An authorized operator selects the legal entity that owns the acquiring account. Each restaurant remains the merchant; configuring a connection does not make Hallify the merchant.
For Bank of Georgia or TBC, create the connection and add its credentials in the protected workspace. Select the intended credential version, review the policy and configure the venue, sales channel, payment purpose and currency bindings. A new bank connection starts in PENDING. A successful token connectivity check alone does not qualify it for payment collection.
For Stripe Connect, choose the exact available platform profile and version, then follow the enrollment flow. Return through /payment-connections/stripe-return in the same browser context. If the result is uncertain or the callback material is unavailable, use the workspace's recovery path; a browser redirect alone does not prove authorization or payment.
Provider contracts, platform profiles and server-held key configuration must be prepared by the responsible administrator. The workspace does not issue public integration keys. Never paste bank credentials, OAuth code/state or provider secrets into documentation examples, public browser API calls or your site's frontend. Enter credentials only through the authorized protected workspace.
These settings APIs are authenticated staff operations and are intentionally absent from this public API reference. Merchant configuration does not establish a complete guest checkout integration. Real Stripe/BOG/TBC merchant, callback and device qualification remains a separate activation requirement.
Use native bill and reservation guarantee payments
Restaurant-owned merchant setup is also a prerequisite for guest-payments. Current QR_MEMBERSHIP or PREORDER_MANAGE authority funds positive native ORDER_BILL principal through AUTOMATIC capture. Genuine RESERVATION_MANAGE funds the exact RESERVATION_GUARANTEE: DEPOSIT/PREPAID use AUTOMATIC capture, CARD_HOLD uses MANUAL authorization. Every flow requires an eligible purpose/currency/provider binding, server-authoritative legal payee and explicit retained consent; configuring a provider creates none of these guest grants or acceptances.
The guest checkout uses its own private access, immutable command receipt, provider operation and original recovery. It does not use this page's simulator HMAC recipe to execute native Stripe, BOG or TBC payments, and exposes no public guest capture/void/refund. The provider return path /guest/payments/return is navigation only; it is separate from the protected merchant enrollment return /payment-connections/stripe-return.
Authorization, capture and native guarantee satisfaction remain separate. A CARD_HOLD needs proven live provider authorization for the exact amount and protection interval; a captured DEPOSIT/PREPAID needs actual native application. Staff forfeitGuarantee/applyGuaranteeCredit are protected and are not public/headless payment commands. Read original command receipts and current provider/native state through their owning flows.
Isolated widgets do not run PSP checkout inside the embedding parent. Their exact prepare/claim transition moves only a private transport permit to the server-selected top-level receiver, then continues the original handoff/checkout. The SDK exposes the canonical operations without manufacturing success, replacement consent or another payment.
Configure access
Use a configured payment-provider profile and the provider key associated with the attempt. Provider secrets stay in the sending server and Hallify configuration. A documented simulator contract is not proof of a certified production provider integration.
The restaurant works with payment attempts in /venues/:venueId/pos. Issuing a provider webhook secret is deployment/provider configuration, not a public self-service key action in the cabinet. Arrange this setup with the Hallify administrator before sending callbacks.
First successful workflow
Follow these steps in order. Open each method for its exact body, required headers and response schema.
- Prepare the Hallify payment attempt ID, unique provider event ID, provider status and occurrence time.
- For this endpoint's documented simulator contract, sign stable JSON with the configured UTF-8 secret, RFC3339 timestamp and v1=<hex> signature. Do not reuse this signing recipe for Stripe, BOG or TBC native callbacks.
- POST to the provider webhook endpoint and check whether the event was applied or recognized as a replay.
State, retries and recovery
Reusing an event identity with another payload is a conflict. An unknown attempt is not created implicitly. A failure reported after capture creates settlement-exception evidence instead of silently reversing captured money.
This callback method serves its documented payment-attempt adapter contract. An attempt already bound to the restaurant provider-operation workflow is rejected with PAYMENT_PROVIDER_OPERATION_REQUIRED; it must continue through its owning workflow. The simulator endpoint is not a substitute for provider-specific signature verification, financial recovery or certified native callbacks.