POS Checkout & Payment Collection

This guide explains how to accept payments in Xolapp using the POS (Point of Sale): terminal, cash, QR codes, and checkout links. It covers processing payment for an appointment or for walk-in sales. It is for owners, admins, and staff who run checkout.

Accept payments seamlessly with multiple payment methods. Process checkout for scheduled appointments or walk-in sales using terminal, cash, QR codes, or checkout links.

Available Payment Methods

💳 Terminal Payments

Accept in-person card payments using Stripe Terminal card reader.

• Physical card reader device
• Tap, swipe, or chip card payments
• Instant payment processing
• Automatic receipt generation
• Real-time payment confirmation
• PCI-compliant and secure

💵 Cash Payments

Collect cash payments with automatic change calculation.

• Manual cash collection
• Enter cash tendered amount
• Automatic change calculation
• Transaction notes included
• Digital receipt available
• Complete audit trail

📱 QR Code Payments

Generate QR code for customers to pay with their phone.

• Instant QR code generation
• Customer scans with phone
• No physical contact needed
• Secure online payment
• Automatic payment confirmation
• Receipt sent automatically

🔗 Checkout Links

Send payment link via email or SMS for remote payment.

• Shareable payment link
• Email or SMS delivery
• Pay from any device
• 24/7 payment availability
• Automatic reminders option
• Link expires after use

💡 Split Payments:

Combine multiple payment methods for a single transaction. For example, partial cash payment with remainder on card.

Appointment Checkout Process

How to Process Appointment Payment:

1. Navigate to Appointments page
2. Find the completed appointment in your list
3. Click "Process Payment" button on the appointment card
4. POS dialog opens with appointment details:
   • Service automatically added to cart
   • Client information pre-filled
   • Staff member pre-selected
   • Total amount shown
5. Add tips if applicable (optional)
6. Add any additional services or products (optional)
7. Select payment method:
   • Click "Pay via Terminal" for card payment
   • Click "Cash Payment" for cash
   • Or use QR Code / Checkout Link buttons
8. Complete payment based on method selected
9. Appointment automatically marked as Paid
10. Earning record created for staff member
11. Receipt generated and available for printing/email

✅ What Happens Automatically:

• Appointment status changes to "Paid" or "Completed"
• Payment recorded in merchant_payments table
• Earning created and linked to staff member
• Invoice updated with payment information
• Client receipt sent (if email provided)
• Revenue & Invoices page updated in real-time
• Team Earnings page updated with new earning

💡 Pro Tips:

• Check-in first: Mark appointment as "In Progress" before checkout
• Add tips: Ask clients about tips before finalizing payment
• Upsell opportunity: Suggest add-on services at checkout
• Receipt delivery: Ask client's preferred receipt method (print/email)
• Multiple services: Multiple services from same appointment show as one transaction

Standalone Checkout (Walk-in Sales)

Process payments without a scheduled appointment for walk-in clients or direct sales.

How to Process Standalone Checkout:

1. Navigate to Appointments page
2. Click "Open POS" button (top right)
3. POS dialog opens with empty cart
4. Add services to cart:
   • Click "+ Service" button
   • Search or browse services
   • Select service(s) to add
   • Adjust quantities if needed
5. Select staff member (REQUIRED):
   • Use staff dropdown at top of cart
   • This determines who receives the earning
   • Cannot complete checkout without staff selection
6. Optionally select client:
   • Use client dropdown
   • Or create new client if needed
   • Not required but helpful for record-keeping
7. Add notes if needed (optional)
8. Choose payment method and complete transaction
9. Earning record created with "Direct checkout" indicator
10. Transaction appears in both Revenue & Team Earnings

⚠️ Important Requirements:

• Staff member MUST be selected - Payment will not process without it
• Staff selection determines who gets credit for the earning
• Direct checkouts marked clearly in Team Earnings as "Direct checkout (no appointment)"
• Shows checkout timestamp instead of appointment time
• All payment methods available for standalone checkout

📊 Use Cases for Standalone Checkout:

• Walk-in clients: Clients without appointment who want immediate service
• Product sales: Selling retail products without appointment
• Emergency bookings: Last-minute additions to schedule
• Package sales: Selling service packages or gift cards
• Add-on services: Additional services not in original appointment
• Waitlist fulfillment: Serving clients from waitlist immediately

Cash Payment Process

Step-by-Step Cash Payment:

1. Add services/products to cart in POS
2. Verify total amount with client
3. Click "Cash Payment" button
4. Cash payment dialog appears
5. Enter cash tendered amount:
   • Type the amount client gave you
   • Example: If total is $45 and client gives $50, enter 50
6. System automatically calculates change:
   • Change amount displayed instantly
   • Example: $50 tendered - $45 total = $5.00 change
7. Review the change amount shown
8. Click "Confirm Payment"
9. Give change to client
10. Payment recorded with notes: "Cash payment - Tendered: $50.00, Change: $5.00"
11. Receipt generated showing cash payment and change given

💵 Cash Payment Features:

• Automatic change calculation: No manual math needed
• Transaction notes: Records tendered and change amounts
• Instant confirmation: Payment recorded immediately
• Audit trail: All cash transactions tracked in database
• Receipt generation: Print or email receipt to client
• Earning creation: Staff earning recorded automatically

💡 Cash Handling Best Practices:

• Count cash twice: Before entering tendered amount
• Show change: Display calculated change to client before giving it
• Verify receipt: Offer receipt for client's records
• Secure storage: Place cash in secure location immediately
• End-of-day reconciliation: Count cash drawer and compare to system records
• Large bills: Have sufficient change available

Terminal Payment Process

Step-by-Step Terminal Payment:

1. Ensure Stripe Terminal reader is connected:
   • Green indicator shows connection status
   • If disconnected, click "Reconnect" button
2. Add services/products to cart in POS
3. Verify total amount with client
4. Click "Pay via Terminal" button
5. System creates payment intent and sends to terminal
6. Terminal reader displays:
   • Total amount to charge
   • "Present card" prompt
7. Client presents card to reader:
   • Tap (contactless)
   • Swipe (magnetic stripe)
   • Insert (chip card)
8. Terminal processes payment (usually 2-5 seconds)
9. Success confirmation appears:
   • On terminal reader screen
   • In POS dialog
   • Toast notification in app
10. Payment recorded automatically
11. Earning created for staff member
12. Receipt generated and available

💳 Terminal Payment Features:

• Instant processing: Payments approve in seconds
• Multiple card types: Visa, Mastercard, Amex, Discover, etc.
• Contactless support: Apple Pay, Google Pay, tap-to-pay cards
• PCI compliance: Secure, encrypted transactions
• Automatic receipts: Digital receipts sent immediately
• Real-time status: Payment status updates in real-time
• Error handling: Clear messages if card is declined

🔧 Terminal Troubleshooting:

• Reader not connected: Click "Discover Readers" to reconnect
• Payment failed: Ask client to try different card or payment method
• Terminal not responding: Check physical device is powered on
• Slow connection: Check internet connectivity
• Card declined: Suggest alternative payment method (cash, different card)

✅ Terminal Best Practices:

• Test connection: Check terminal connection before busy periods
• Keep charged: Ensure terminal battery is charged
• Verify amounts: Confirm total with client before processing
• Wait for approval: Don't cancel transaction prematurely
• Offer receipt: Ask if client wants printed or emailed receipt

Earnings Integration

All POS payments automatically create earning records and update earnings lists in real-time.

📊 Where Earnings Appear:

💰 Revenue & Invoices Page:

• All earnings listed in "Earnings" tab
• Shows amount, payment method, date/time
• Includes both appointment and direct checkout earnings
• Filterable by date range and payment method

👥 Team Earnings Page:

• Per-staff breakdown of earnings
• Summary totals updated in real-time
• Individual earning details show transaction info
• Includes service names, appointment times, payment methods

📅 Appointments Page:

• Appointment status updates to "Paid" or "Completed"
• Payment badge shows on appointment card
• Payment method indicator visible

🔄 Automatic Updates:

• Instant sync: Earnings appear immediately after payment
• Real-time totals: Summary numbers update automatically
• Query invalidation: All related pages refresh to show new data
• No manual refresh needed: Changes appear without page reload

📋 Earning Record Details:

Each earning record includes:

• Amount: Total payment received
• Tips: Additional tips (if applicable)
• Payment Method: cash, terminal, card, qr_code, checkout_link
• Items: List of services/products purchased
• Staff Member: Who provided the service
• Client: Who made the purchase (if recorded)
• Date/Time: When transaction occurred
• Source: Appointment-based or direct checkout
• Notes: Transaction notes (e.g., cash change details)

Troubleshooting Common Issues

❌ Payment Not Showing in Earnings

Causes:

• Staff member not selected during standalone checkout
• Payment failed but appeared to succeed
• Database sync issue

Solutions:

• Always select staff member before processing standalone checkout
• Check payment status in merchant_payments table
• Verify payment succeeded in Stripe dashboard
• Refresh page to trigger data reload

⚠️ Terminal Not Connecting

Solutions:

• Click "Discover Readers" button to search for terminal
• Ensure terminal is powered on and charged
• Check internet connection on both device and terminal
• Restart terminal device if necessary
• Contact support if issue persists

⚠️ Cash Change Calculation Wrong

Note: Change is calculated automatically - no manual calculation needed.

Solutions:

• Double-check the "Cash Tendered" amount you entered
• Verify cart total is correct before processing
• System calculates: Cash Tendered - Total = Change
• If incorrect, cancel and restart cash payment

🔍 Payment Status Verification

How to verify payment succeeded:

• Check for success toast notification
• Appointment marked as "Paid" or "Completed"
• Earning appears in Revenue & Invoices page
• Staff earning shows in Team Earnings page
• Receipt was generated
• Database merchant_payments record shows "succeeded" status

💼 Payment Failed - What to Do

Steps to take:

• Note the error message displayed
• For card payments: Ask client to try different card
• Offer alternative payment method (cash, different card)
• Check terminal connection if using terminal payment
• For persistent issues: Process payment later or contact support

💡 POS Best Practices

✅ Before Every Transaction:

• Verify cart total with client
• Confirm correct services/products added
• Check staff member is selected (standalone checkout)
• Ask about tips before finalizing
• Ensure payment method is working (terminal connected, cash drawer ready)

📊 After Transaction:

• Confirm success notification appeared
• Offer receipt to client (print or email)
• Verify earning appeared in earnings lists
• For cash: Give correct change and secure cash
• For terminal: Wait for terminal approval screen

🎯 Efficiency Tips:

• Use keyboard shortcuts for faster checkout
• Create service favorites for quick access
• Keep terminal charged and connected
• Pre-load common services during slow times
• Train all staff on POS system

🔒 Security & Compliance:

• Never write down card information
• Keep cash drawer secure and locked
• Reconcile cash at end of each day
• Use PCI-compliant terminal for card payments
• Review transaction history regularly

Frequently asked questions

How do I process payment for an appointment?

Go to Appointments, find the appointment, and click Process Payment. The POS dialog opens with the service and client pre-filled. Add tips or extra items if needed, then choose a payment method (terminal, cash, QR, or checkout link) and complete the payment.

What payment methods can I use at checkout?

You can use terminal (card), cash, QR code (customer pays on phone), or checkout link (send link by email or SMS). Split payments are supported (e.g. part cash, part card).

Where do I see payment history?

All POS payments appear in Payments → History. You can also see payments linked to invoices on the Revenue & Invoices page and earnings on the Team earnings view.

Can I process a sale without an appointment?

Yes. Use the POS from the Payments page (Point of Sale tab) to run a walk-in sale. Add services or products to the cart, select or add a client, then complete payment. No appointment is required.