PayKiosk Documentation

Introduction

PayKiosk is a point-of-sale (POS) application designed for self-service kiosks. It allows customers to browse products, add items to a cart, and complete payments through multiple methods including credit cards, cash, gift cards, and Stripe Terminal hardware readers.

The app is available in two versions:

• PayKiosk for macOS — Ideal for desktop or Mac Mini kiosks in retail, events, or hospitality.
• PayKiosk for iPad — Optimized for tablet-based kiosks with touch-first interaction.

Both versions share the same core features: product catalog, shopping cart, checkout, promotions, quantity discounts, and extensive customization options for store branding and design.

Getting Started

When you first launch PayKiosk, you will see either the Welcome screen (if no products exist) or the Product Catalog.

First-time setup

1. Add products — Go to Settings → Products and create your first products. Assign names, prices, categories, and optional images.
2. Configure payment — In Settings → Payment (Stripe), enter your Stripe API keys and enable the payment methods you want (card, cash, gift card, hardware reader).
3. Customize your store — Use Settings → Store for store name, logo, and welcome message; Settings → Design for colors, fonts, and labels.

Accessing Settings

• macOS: Press ⌘+⌥+P (Command+Option+P) from anywhere, or click the "Open Settings" button on the Welcome screen. If password protection is enabled, you will be prompted for the password.
• iPad: Triple-tap anywhere on the store name, welcome message, or logo in the header to open Settings. A password prompt appears if password protection is enabled.

Main Interface

Product Catalog

The product catalog displays your active products in a grid or list layout. Each product card shows:

• Product image (if enabled)
• Name and description
• Price (with sale price if applicable)
• Category badge
• Stock status (low stock / out of stock)
• Add to Cart button

When you enable search and category filters in Settings → Options, customers can search by name, description, SKU, or barcode, and filter by category. Products can be shown in grid or list view on macOS.

Shopping Cart

The cart sidebar appears on the right (macOS) or as a panel (iPad). It shows:

• Product image, name, and price per item
• Quantity controls (unless "Disable Quantities" is on in Settings)
• Line total
• Remove item button
• Promo code field (if enabled)
• Subtotal, discount, tax, and total
• Proceed to Checkout button

When Promo Codes are enabled, customers can enter a code to apply discounts. The cart applies the best promotion automatically when applicable.

Checkout

Checkout opens as a modal or full-screen overlay. It includes:

• Order summary with all items
• Payment method selection (Credit/Debit Card, Cash, Gift Card, Hardware Reader)
• Complete Payment button

For Credit/Debit Card payments, Stripe's secure payment form is used. For Cash, the payment is recorded immediately. For Stripe Terminal, the app connects to a configured reader. After a successful payment, a confirmation screen appears with a "Continue Shopping" button.

Settings

Settings are organized into tabs. Use the sidebar to switch between sections.

Store

Configure your store’s identity and tax:

• Store Logo — Upload a square PNG (recommended 128×128 px minimum).
• Store Name — Displayed in the header.
• Welcome Message — Shown below the store name.
• Tax Rate — Enter as decimal (e.g. 0.08 for 8%).
• Tax Included in Price — Toggle whether prices already include tax.

Products

Manage products and categories with a split-view layout:

• Products — Add, edit, or delete products. Each product has: name, description, price, cost, sale price, category, SKU, barcode, images, stock quantity, and tax category.
• Categories — Organize products into categories (e.g. General, Food, Drinks).
• Sync from Stripe — If enabled, sync products from your Stripe catalog.

Product images can be added from the Photos app (iPad) or via file picker (macOS). Images are stored as base64 and update immediately in the catalog.

Promotions

Create time-based discounts with optional category restrictions:

• Discount Type — Percentage or fixed amount.
• Discount Value — e.g. 10 for 10% off or $5 off.
• Start/End Date — Optional validity period.
• Category — Restrict to specific categories (e.g. "Drinks").

Promotions can be exported and imported as JSON for backup or sharing.

Quantity Discounts

Define volume discounts for bulk purchases:

• Minimum Quantity — e.g. buy 5 or more.
• Discount Type — Percentage, fixed amount per item, or price per item.
• Start/End Date — Optional validity period.

Quantity discounts apply automatically when the cart meets the minimum. Export/import is supported.

Payment (Stripe)

Configure Stripe payment processing:

• Mode — Test or Live. Use test keys (pk_test_...) for development.
• Publishable Key — Used in the app; safe to expose.
• Secret Key — Used server-side; never share publicly.
• Default Currency — ISO 4217 code (e.g. usd, eur, gbp).
• Sync Products from Stripe — If enabled, products can be synced from Stripe.

Payment Methods: Enable or disable Credit/Debit Card, Cash, Gift Card, and Hardware Reader (Stripe Terminal). At least one method must remain enabled.

Options (Display)

Control what appears in the product catalog:

• Product images, name, description, price, category, SKU
• Products per row (2–5)
• Search bar
• Category filters
• Promo codes
• Disable Quantities — Single item only per product (no quantity selector)

Design

Design is split into Appearance and Labels:

Appearance: Button styles (gradient, colors, corner radius, border), card styles (background, shadow, border), product image display (fill/fit, height), category button colors, background colors (gradient, accent), and text colors.

Labels: Customize all UI labels (Add to Cart, Checkout, Total, etc.) for localization or branding.

Security (Kiosk)

Configure kiosk behavior and security:

macOS: Hide menu bar, hide dock, prevent force quit, disable quit menu, prevent app switching, keep app in front, prevent system/display sleep, open at login; password protect settings with optional hint.

iPad: Password protect settings; prevent device sleep; and instructions for using Guided Access as a full kiosk experience.

macOS-Specific Features

Kiosk Mode

The macOS version includes robust kiosk options:

• Hide Menu Bar / Dock — Reduces distractions for customers.
• Prevent Force Quit — Blocks Cmd+Option+Esc.
• Keep App in Front — Prevents other apps from covering PayKiosk.
• Open at Login — App starts automatically when the Mac boots.

Keyboard Shortcut

Press ⌘+⌥+P (Command+Option+P) from anywhere to open Settings. This works even when the app is not focused, so staff can use a hidden keyboard to access settings.

Trial Mode

If not purchased from the Mac App Store, a trial mode limits the number of products. A banner appears at the bottom. Purchase a license to unlock unlimited products.

Updates

The "Check for Updates" button in the Settings footer checks for new versions. Visit xproline.io to download updates.

iPad-Specific Features

Triple-Tap to Open Settings

Triple-tap on the store name, welcome message, or logo in the header to open Settings. This works even when the app is in kiosk mode.

Guided Access

For a full kiosk setup, use iPad’s built-in Guided Access:

1. Settings → Accessibility → Guided Access
2. Enable Guided Access
3. Triple-click the side/top button to start Guided Access in your app

This prevents users from leaving the app or accessing other apps.

Power Management

Enable "Prevent Device Sleep" in Settings → Security to keep the iPad awake during use.

Layout

The Settings panel adapts to portrait and landscape. In portrait, the sidebar is compact (icons only). In landscape, the full sidebar with labels is shown.

Technical Details

Data Storage

All data is stored locally using UserDefaults:

• Products and categories
• Promotions and quantity discounts
• Store configuration (colors, labels, Stripe keys, etc.)

No cloud sync is built in. Data is stored per device.

Stripe Integration

PayKiosk uses Stripe for:

• Payment Intents — For card payments, a PaymentIntent is created on your backend.
• Stripe Terminal — For hardware readers, the app connects to a configured reader. Requires Stripe Terminal SDK setup.

Your Stripe secret key is stored locally and used for creating PaymentIntents. Ensure your backend or Stripe configuration supports the Payment Intents flow.

Payment Flow

1. Customer adds items to cart and proceeds to checkout.
2. Customer selects a payment method.
3. For card: Stripe Payment Element loads and collects card details.
4. For Terminal: App connects to reader and processes payment.
5. For cash/gift card: Payment is recorded immediately.
6. Transaction is saved locally; cart is cleared; success screen is shown.

Product Images

Images are stored as base64 strings in the product data. Supported formats include PNG and JPEG. Images update immediately when changed; no app restart is required.

Promotions vs Quantity Discounts

• Promotions — Code-based or category-based; can have time limits.
• Quantity Discounts — Apply automatically when cart quantity meets a minimum (e.g. buy 5, get 10% off).

Both can apply to the same cart. The system applies the best discount for the customer.

Currency

The default currency is set in Settings → Payment. Supported codes include USD, EUR, GBP, CAD, AUD, JPY, CHF, and many others.

Tips & Best Practices

• Use Test Mode in Stripe until you are ready for live payments.
• Set a strong password for Settings if the kiosk is unattended.
• Organize products with categories for easier browsing.
• Keep product images square and at least 200×200 px for best display.
• Export promotions and quantity discounts as JSON for backup.
• On macOS, use Open at Login so the kiosk starts automatically.