Platform

Integrations

Payment providers, messaging providers, accounting sync, and adapter architecture.

Overview

SalonOS uses an adapter pattern for all third-party integrations. Each integration category has a defined interface; the underlying provider can be swapped or extended without changing product logic. This makes the platform provider-agnostic and prepared for new markets.

Payment Integration

PaymentProvider Interface

All payment flows go through a PaymentProvider adapter with these capabilities:

  • createPaymentLink(amount, metadata) → link for UPI/card payment
  • capturePayment(paymentId) → confirms a captured payment
  • issueRefund(paymentId, amount) → full or partial refund
  • getPaymentStatus(paymentId) → check payment state

Providers

Provider Status Use case
Cash Always available On-premise cash payments
Razorpay Primary UPI, cards, net banking (India)
Stripe Planned International markets

Razorpay Integration

  • Payment links generated at checkout and sent via WhatsApp or displayed on the POS screen
  • Client pays via UPI, debit/credit card, or net banking
  • Webhook receives payment confirmation and updates the invoice
  • Refunds processed via Razorpay API and reflected in SalonOS

Webhook Security

Payment webhooks are verified using provider-issued signing secrets. Only verified webhook payloads are processed. All webhook events are logged with idempotency keys to prevent duplicate processing.

Messaging Integration

MessagingProvider Interface

The messaging adapter exposes:

  • sendTemplate(to, templateId, params) → send a WhatsApp template message
  • sendText(to, text) → send a free-form text (within session window)
  • sendMedia(to, mediaUrl, caption) → send an image or document
  • getDeliveryStatus(messageId) → check delivery state

Providers

Provider Channel Status
WhatsApp Business API WhatsApp Primary
Twilio SMS Fallback / voice
SendGrid Email Campaigns and notifications

WhatsApp Business API Setup

  1. Brand registers a WhatsApp Business Account (WABA) via Meta Business Manager
  2. Phone number verified and linked to SalonOS
  3. Pre-approved message templates submitted to Meta
  4. Inbound messages received via webhook to SalonOS
  5. SalonOS routes inbound messages to the inbox and the AI booking agent

Webhook Handling

WhatsApp webhooks deliver:

  • Message delivery status (sent, delivered, read, failed)
  • Inbound messages from clients
  • Template status changes (approved, rejected)

All webhook events are verified using the HMAC signature in the X-Hub-Signature-256 header.

Accounting Integration — Zoho Books

AccountingProvider Interface

  • createSalesInvoice(invoice) → push an invoice to the accounting system
  • createExpense(expense) → push an expense entry
  • createBill(bill) → push a vendor bill
  • syncChartOfAccounts() → pull account codes for mapping

Zoho Books Sync

What syncs Direction Schedule
Sales invoices SalonOS → Zoho Daily or on-demand
Vendor bills SalonOS → Zoho Daily or on-demand
Expenses SalonOS → Zoho Daily or on-demand
Chart of accounts Zoho → SalonOS (mapping) On setup, manual refresh

Sync is one-directional: SalonOS is the operational source of record; Zoho Books is the accounting system of record. Corrections made in Zoho are not synced back.

Account Mapping

Each SalonOS account (revenue, expense, COGS) is mapped to the corresponding Zoho chart of accounts code. The mapping is configured in Settings → Integrations → Zoho Books.

Attribution — Google Ads and Meta Ads

AttributionReader Interface (Read-Only)

  • getCampaignSpend(dateRange) → pull ad spend by campaign
  • getConversions(dateRange) → pull conversion events

Google Ads Integration

  • SalonOS imports campaign spend and impression data via Google Ads API
  • UTM parameters on booking links attribute bookings to campaigns
  • Data is paired with SalonOS booking records to compute ROAS

Meta Ads Integration

  • Similar to Google Ads: import spend, pair with booking attributions
  • Meta click IDs in booking URLs link to ad impressions

This is read-only — SalonOS never writes to ad platforms.

Calendar Sync — Google Calendar

CalendarSync interface provides optional two-way sync:

  • Export confirmed appointments to the staff member's Google Calendar
  • New events created in Google Calendar can optionally block time in SalonOS

Currently planned; specific provider is Google Calendar.

Review Integration — Google Business Profile

ReviewsProvider interface:

  • getReviews(locationId, dateRange) → fetch reviews
  • postReply(reviewId, text) → post a reply

Used by the reputation module to surface and respond to Google reviews. Requires Google Business Profile OAuth connection per location.

Data Import — Zylu and CSV

ImportProvider Interface

  • parseExport(file) → parse a Zylu-format export
  • validateRecords(records) → validate before import
  • importBatch(records) → bulk-import clients and bookings

Zylu Import

Zylu is a widely used salon software in India. SalonOS can import:

  • Client records (name, phone, email, tags)
  • Historical appointments
  • Service catalogue (mapped to SalonOS services)
  • Membership and package balances

The import wizard:

  1. Upload the Zylu export CSV
  2. Map Zylu fields to SalonOS fields (auto-suggested)
  3. Preview first 20 records; validate errors
  4. Run the import; progress shown in real time
  5. Review import summary (records created, skipped, errored)

Imported clients are flagged with import provenance. Consent for marketing is not assumed from the import — only transactional consent is granted unless the import data includes explicit proof of consent.

CSV Import

Generic CSV import for clients and services:

  • Download the SalonOS import template
  • Fill with data
  • Upload and validate
  • Import

Configuring Integrations

All integrations are configured in Settings → Integrations:

  • Connect/disconnect providers
  • Enter API keys and webhooks
  • Map accounts and fields
  • Test connections
  • View sync history and error logs

Permissions

Action org_owner brand_manager location_manager
Configure payment provider Yes Yes No
Configure messaging provider Yes Yes No
Configure Zoho Books sync Yes Yes No
Connect Google Business Profile Yes Yes Yes (location)
Connect ad attribution Yes Yes No
Run data import Yes Yes No
View sync history Yes Yes Yes