Skip to main content

EP-015: Integrations & Third-Party Connectors

Business Objective​

Hotels operate within an ecosystem of financial, government, hardware, and payment systems. Seamless integration with payment gateways (Razorpay, Stripe, PayU), accounting platforms (Tally, SAP), government compliance APIs (GST e-invoice via NIC portal, FSSAI license verification), door lock systems, POS terminals, and currency providers eliminates manual data entry, reduces reconciliation errors, and ensures regulatory compliance. For Indian hotels specifically, Tally integration is non-negotiable since over 70% of independent and mid-scale properties use Tally ERP/Prime for accounting. Webhook and API key management enables the platform to function as an extensible hub for the hotel's technology stack.

Audience​

  • Primary: Accounts Manager, General Manager, Admin
  • Secondary: Front Desk Agent (payment terminals, door locks), F&B Staff (POS printers, KOT), IT/Operations (webhook management, API keys)
  • Tertiary: External system developers consuming HMP webhooks

Scope​

In Scope​

  • Payment gateway integration (Razorpay primary, Stripe international roadmap, PayU backup)
  • Accounting sync: Tally ERP 9/Prime bi-directional sync (vouchers, ledgers, reconciliation)
  • Accounting sync: SAP Business One connector (journal entries, cost centers)
  • Government APIs: GST e-invoice generation via NIC portal (IRN, QR code)
  • Government APIs: FSSAI license verification for F&B outlets
  • Door lock systems: ASSA ABLOY Visionline (roadmap), Onity HT28 Smart
  • POS terminals and thermal printers (receipt printing, KOT printing)
  • Currency management: exchange rate auto-update via Open Exchange Rates / RBI reference
  • Webhook management: outbound webhooks with retry, signature verification
  • API key management: generation, rotation, scoping, rate limiting
  • Integration marketplace: plugin directory for third-party connectors

Out of Scope​

  • Deep ERP customization (custom Tally TDLs beyond standard voucher sync)
  • Building proprietary payment processing (we remain a gateway consumer)
  • Smart TV / IPTV integration (covered in EP-012 In-Room Tech)
  • OTA channel integrations (covered in EP-009 Channel Manager)

Current Implementation Status​

Backend (integration-service)​

  • Tally: TallyService with mock/live modes, Kafka subscription to FOLIO_SETTLED events, TallyReconciliationService for ledger reconciliation. Environment-driven config (TALLY_HOST, TALLY_PORT, TALLY_MOCK). Controllers and DTOs present.
  • SAP: SapService and SapReconciliationService with controllers. Placeholder implementation -- journal entry structure defined but HTTP client calls to SAP B1 Service Layer not connected.
  • Accounting Sync Logs: AccountingSyncLogService tracks sync history per integration.
  • Marketplace: MarketplaceService with plugin directory, install/uninstall, settings management. Controller with CRUD endpoints.
  • Webhooks: Webhook registration and delivery exist in integration service. WhatsApp webhook controller in notification-service.
  • Payments: RazorpayAdapter in @hmp-backend/payments lib. Used in reservation-service PaymentsService and auth-service BillingService.
  • Hardware: @hmp-backend/hardware lib with vendor abstractions. POS hardware controller in pos-service. Terminal payment controller in frontdesk-service.
  • Currency: CurrencyService and CurrencyHistoryService in analytics-service.
  • Smart Locks: SmartLockService in frontdesk-service.
  • Compliance: SeaComplianceService in integration-service for Southeast Asian regulatory requirements.

Dashboard (02-hmp-web-dashboard)​

  • Settings pages for Tally integration (/settings/integrations/tally)
  • Settings pages for SAP integration (/settings/integrations/sap)
  • Settings pages for WhatsApp integration (/settings/integrations/whatsapp)
  • Currency settings page (/settings/currency)
  • POS hardware page (/pos/hardware)
  • Smart locks page (/settings/smart-locks)
  • Marketplace plugin pages (/marketplace, /marketplace/[pluginId])

Booking Engine (03-hmp-booking-engine)​

  • Razorpay checkout integration for guest-facing payments

Gap Analysis​

AreaCurrent StateGapImpact
Tally SyncConfig UI + mock service + Kafka listenerActual HTTP XML requests to Tally Gateway Server not implemented; voucher mapping incompleteAccounts team must manually re-enter folio settlements in Tally
SAP ConnectorService shell + reconciliation serviceNo HTTP calls to SAP B1 Service Layer; authentication (session-based) not builtEnterprise chains cannot automate GL posting
GST e-InvoiceGST slab calculation exists in analyticsNIC portal API integration missing (IRN generation, QR code, e-invoice cancellation)Properties with turnover > INR 5 Cr cannot generate e-invoices from HMP
FSSAI VerificationDocumentation-only complianceNo API call to FSSAI license lookup; no expiry alertingF&B license compliance is manual spreadsheet tracking
Door Lock SDKSmartLockService shell existsNo vendor SDK integration (ASSA ABLOY Visionline API, Onity DirectKey)Front desk must use separate lock management software
POS PrintersPOS hardware controller existsThermal printer drivers (ESC/POS commands) not tested with actual hardwareKOT and receipt printing untested in production
Currency ExchangeCurrencyService + history serviceNo auto-update from external provider (Open Exchange Rates, XE, RBI)Exchange rates must be manually entered; stale rates risk billing errors
Stripe/PayURazorpay onlyNo Stripe adapter for international guests; no PayU fallbackInternational guests face payment friction; no failover if Razorpay is down
API Key ScopingBasic API key in auth serviceNo per-endpoint permission scoping; no usage tracking; no dashboard UIThird-party integrators get all-or-nothing access
Webhook ReliabilityBasic webhook deliveryNo exponential backoff retry; no dead-letter queue; no delivery dashboardFailed webhooks silently lost; no visibility for external consumers

User Stories​

Story IDTitlePriorityPointsStatusSprint
US-015-001Razorpay Payment Gateway IntegrationP05Built3
US-015-002Tally ERP Bi-Directional SyncP013Partial8
US-015-003SAP Business One Journal PostingP18Partial10
US-015-004GST e-Invoice via NIC PortalP08Not Started9
US-015-005FSSAI License Verification & AlertingP25Not Started12
US-015-006Door Lock System Integration (ASSA ABLOY)P213Not Started14
US-015-007Thermal Printer & KOT Printing (ESC/POS)P15Partial7
US-015-008Currency Exchange Rate Auto-UpdateP15Not Started10
US-015-009Webhook Management with Retry & Dead-LetterP18Partial9
US-015-010API Key Management with Scoped PermissionsP15Partial9
US-015-011Stripe Payment Gateway (International)P28Not Started14

Dependencies​

  • EP-001 (Auth & Access): API key management depends on auth service token infrastructure
  • EP-004 (Front Desk & Folio): Tally sync triggers on folio settlement events
  • EP-007 (POS): KOT/receipt printing depends on POS order flow
  • EP-017 (Compliance): GST e-invoice depends on tax calculation engine
  • EP-019 (Platform Admin): Razorpay Subscriptions for SaaS billing

Acceptance Criteria (Epic Level)​

  • Folio settlements in HMP automatically create sale vouchers in Tally within 30 seconds
  • GST e-invoices generate valid IRN numbers via NIC portal for properties with turnover > INR 5 Cr
  • Razorpay payments process successfully with webhook confirmation and automatic folio update
  • Currency exchange rates auto-refresh daily from configured provider
  • Outbound webhooks retry with exponential backoff (1s, 2s, 4s, 8s, 16s) up to 5 attempts
  • API keys can be scoped to specific endpoints and rate-limited per key
  • All integration failures are logged with alerting for critical failures (payment, tax)

KPIs / Success Metrics​

  • Tally sync success rate > 99% (measured by reconciliation report)
  • Payment gateway uptime > 99.9% (Razorpay + failover)
  • e-Invoice generation success rate > 98% on first attempt
  • Webhook delivery rate > 99.5% within 5 retry attempts
  • Average sync latency (folio settle to Tally voucher) < 30 seconds
  • Currency rate staleness < 24 hours
  • API key audit: zero unauthorized access incidents

Detailed User Stories​

US-015-001: Razorpay Payment Gateway Integration​

As a Front Desk Agent, I want to process guest payments through Razorpay (UPI, cards, net banking), So that payments are recorded automatically in the folio without manual entry. Priority: P0 | Points: 5 | Sprint: 3 | Status: Built

Implementation Status​

RazorpayAdapter in @hmp-backend/payments lib handles order creation, payment verification, and refund processing. Used in reservation-service for advance payments and booking-engine for online checkout. Webhook controller receives payment confirmations. Dashboard shows payment status on folio view.

Acceptance Criteria​

Scenario: Guest pays advance via Razorpay UPI
  Given a confirmed reservation with balance due of INR 5,000
  And the front desk agent clicks "Collect Payment"
  When the agent selects Razorpay and enters amount INR 5,000
  And the guest completes UPI payment on the Razorpay checkout
  Then the Razorpay webhook confirms payment status "captured"
  And a PAYMENT transaction of INR 5,000 is posted to the folio
  And the reservation balance due updates to INR 0

Scenario: Payment refund on cancellation
  Given a reservation with a Razorpay payment of INR 5,000
  When the agent cancels the reservation with refund policy "Full Refund"
  Then HMP calls Razorpay Refund API for INR 5,000
  And the refund status is tracked until "processed"
  And a PAYMENT reversal transaction is posted to the folio

Scenario: Razorpay webhook signature verification
  Given an incoming webhook POST from Razorpay
  When the X-Razorpay-Signature header does not match HMAC-SHA256 of the body
  Then the webhook is rejected with HTTP 401
  And an alert is raised for potential tampering

US-015-002: Tally ERP Bi-Directional Sync​

As an Accounts Manager, I want to automatically sync folio settlements, payments, and revenue entries to Tally ERP, So that I do not have to re-enter transactions manually and month-end reconciliation is instant. Priority: P0 | Points: 13 | Sprint: 8 | Status: Partial

Implementation Status​

TallyService subscribes to FOLIO_SETTLED Kafka events and has mock mode for development. TallyReconciliationService compares HMP vs Tally ledger balances. Config UI exists in dashboard (/settings/integrations/tally). Gap: actual XML request construction for Tally Gateway Server (port 9000) not implemented; voucher type mapping (Sales, Receipt, Journal, Contra) incomplete; bi-directional read from Tally not built.

Acceptance Criteria​

Scenario: Folio settlement creates Tally sales voucher
  Given the Tally integration is configured with host "192.168.1.50" port 9000
  And the property has Tally ledger mappings for "Room Revenue", "F&B Revenue", "CGST", "SGST"
  When a folio is settled with room charges INR 10,000 + CGST INR 600 + SGST INR 600
  Then HMP sends a Tally XML request creating a Sales voucher
  And the voucher debits "Guest Ledger" INR 11,200 and credits "Room Revenue" INR 10,000 + "CGST Payable" INR 600 + "SGST Payable" INR 600
  And the sync log records status "SUCCESS" with Tally voucher number

Scenario: Reconciliation detects mismatch
  Given 50 folios were settled this month totaling INR 5,00,000
  When the accounts manager runs "Reconcile with Tally"
  Then HMP reads Tally ledger balances via XML export request
  And compares HMP revenue totals with Tally ledger totals
  And displays any mismatches with folio number, HMP amount, Tally amount, and variance

Scenario: Tally connection failure with retry
  Given the Tally Gateway Server is unreachable
  When a folio settlement event fires
  Then HMP queues the sync entry with status "PENDING"
  And retries every 5 minutes up to 10 attempts
  And marks the entry "FAILED" after exhausting retries
  And sends an alert to the Accounts Manager

US-015-003: SAP Business One Journal Posting​

As a Finance Controller at a chain hotel, I want to post daily revenue journals to SAP Business One, So that the corporate finance team has real-time visibility into property-level P&L. Priority: P1 | Points: 8 | Sprint: 10 | Status: Partial

Implementation Status​

SapService and SapReconciliationService exist with controller endpoints. Dashboard SAP settings page allows configuration of SAP B1 Service Layer URL, company DB, and credentials. Gap: actual HTTP calls to SAP B1 REST API (session login, journal entry posting, business partner sync) not implemented.

Acceptance Criteria​

Scenario: Night audit posts revenue journal to SAP
  Given SAP B1 integration is configured with Service Layer URL and credentials
  And GL account mappings exist for room revenue (40100), F&B revenue (40200), taxes (22100)
  When the night audit completes for property "Mumbai Downtown"
  Then HMP creates a Journal Entry in SAP B1 with line items matching night audit totals
  And the journal references the HMP night audit ID and date
  And the sync log records the SAP DocEntry number

Scenario: SAP session expiry and re-authentication
  Given the SAP B1 session token has expired (default 30 min timeout)
  When HMP attempts to post a journal entry
  Then HMP detects the 401 response and re-authenticates via POST /Login
  And retries the journal posting with the new session
  And the operation completes transparently without user intervention

US-015-004: GST e-Invoice via NIC Portal​

As an Accounts Manager, I want to generate GST e-invoices (IRN + QR code) directly from HMP, So that the property complies with mandatory e-invoicing for turnover above INR 5 Crore without using a separate portal. Priority: P0 | Points: 8 | Sprint: 9 | Status: Not Started

Implementation Status​

GST slab-based tax calculation exists in analytics-service (Gstr3bExportService) and frontdesk-service e-invoice module. GSTIN is stored per property in the Prisma schema. Gap: NIC e-Invoice API integration (sandbox + production) not built. IRN generation, signed QR code embedding, e-invoice cancellation within 24 hours, and e-invoice print format not implemented.

Acceptance Criteria​

Scenario: Generate e-invoice on folio settlement
  Given the property GSTIN is "27AADCB2230M1ZT" and is registered on NIC e-Invoice portal
  And a folio is settled with taxable value INR 12,000 at 12% GST (room tariff INR 1,000-7,500 slab)
  When the system calls NIC e-Invoice API (/eiapi/v1/Invoice) with the signed JSON payload
  Then the NIC portal returns a valid IRN (64-character hash) and signed QR code
  And the IRN and QR code are stored against the folio invoice
  And the printed invoice includes the IRN, Ack No, Ack Date, and QR code

Scenario: e-Invoice cancellation within 24 hours
  Given an e-invoice was generated with IRN "abc123..." at 10:00 AM today
  When the accounts manager cancels the invoice before 10:00 AM tomorrow
  Then HMP calls NIC Cancel API with IRN and cancellation reason
  And the e-invoice status updates to "CANCELLED" in HMP
  And a credit note e-invoice is generated if required

Scenario: NIC portal downtime fallback
  Given the NIC e-Invoice API returns HTTP 503
  When a folio is settled requiring e-invoice generation
  Then HMP queues the e-invoice request with status "PENDING_GENERATION"
  And retries every 15 minutes
  And alerts the Accounts Manager if unresolved after 4 hours

US-015-005: FSSAI License Verification & Alerting​

As a General Manager, I want to track FSSAI license status for all F&B outlets and receive renewal alerts, So that the property avoids penalties for operating with expired food safety licenses. Priority: P2 | Points: 5 | Sprint: 12 | Status: Not Started

Implementation Status​

FSSAI compliance documentation exists in 09-hmp-compliance but there is no automated verification. The property schema stores license details in the settings JSON field but no dedicated FSSAI fields or API integration exist.

Acceptance Criteria​

Scenario: FSSAI license expiry alerting
  Given outlet "Spice Garden Restaurant" has FSSAI license number "12345678901234" expiring on 2026-06-15
  When the current date is 60 days before expiry (2026-04-16)
  Then the system sends an email alert to the General Manager
  And a dashboard notification appears with "FSSAI license expiring in 60 days"
  And alerts repeat at 30 days, 15 days, and 7 days before expiry

Scenario: FSSAI license verification via API
  Given the General Manager enters FSSAI license number "12345678901234"
  When the system calls the FSSAI verification API
  Then the response confirms license validity, holder name, and expiry date
  And HMP stores the verification result with timestamp
  And displays a green "Verified" badge on the outlet compliance page

US-015-006: Door Lock System Integration (ASSA ABLOY)​

As a Front Desk Agent, I want to encode digital room keys directly from the check-in screen, So that I do not need to switch to a separate lock management application. Priority: P2 | Points: 13 | Sprint: 14 | Status: Not Started

Implementation Status​

SmartLockService in frontdesk-service exists as a shell. Dashboard has a smart locks settings page (/settings/smart-locks). The @hmp-backend/hardware lib defines vendor abstractions. Gap: no actual SDK integration with ASSA ABLOY Visionline, Onity DirectKey, or Salto KS APIs. Key encoding, key invalidation on checkout, and mobile key issuance not implemented.

Acceptance Criteria​

Scenario: Encode room key on check-in
  Given the ASSA ABLOY Visionline server is configured and connected
  And guest "Rajesh Kumar" is checking into room 405
  When the front desk agent clicks "Encode Key" on the check-in screen
  Then HMP sends a CreateKey request to Visionline with room 405, valid from now to checkout date
  And the key encoder hardware writes the key card
  And the system confirms "Key encoded successfully for Room 405"

Scenario: Invalidate keys on checkout
  Given guest "Rajesh Kumar" has 2 active key cards for room 405
  When the front desk agent completes checkout
  Then HMP sends an InvalidateKeys request to Visionline for room 405
  And all active keys for room 405 are deactivated
  And the lock audit log records the invalidation timestamp

US-015-007: Thermal Printer & KOT Printing (ESC/POS)​

As an F&B Staff member, I want to print KOT slips to kitchen stations and guest bills to the receipt printer, So that kitchen orders are communicated instantly and guests receive printed bills. Priority: P1 | Points: 5 | Sprint: 7 | Status: Partial

Implementation Status​

PosHardwareController and PosHardwareService exist in pos-service with endpoints for printer discovery, test print, and print job submission. Dashboard POS hardware page (/pos/hardware) shows printer configuration. Gap: ESC/POS command generation not tested with actual thermal printers (Epson TM-T82, TVS RP 3160); network printer discovery (TCP port 9100) not validated; KOT format with station routing not finalized.

Acceptance Criteria​

Scenario: KOT prints to correct kitchen station
  Given outlet "Main Restaurant" has printers: "Kitchen-Hot" at 192.168.1.101, "Kitchen-Cold" at 192.168.1.102, "Bar" at 192.168.1.103
  And menu item "Butter Chicken" is mapped to station "Kitchen-Hot"
  When a new KOT is generated with "Butter Chicken x2, Caesar Salad x1, Mojito x1"
  Then "Butter Chicken x2" prints on "Kitchen-Hot" printer
  And "Caesar Salad x1" prints on "Kitchen-Cold" printer
  And "Mojito x1" prints on "Bar" printer
  And each KOT slip shows order number, table number, time, and item details

Scenario: Receipt printing with GST details
  Given a POS order is billed at INR 2,500 + 5% GST = INR 2,625
  When the F&B staff clicks "Print Bill"
  Then the thermal printer outputs a receipt with property name, GSTIN, FSSAI number
  And itemized charges with individual GST breakdown (CGST 2.5% + SGST 2.5%)
  And payment summary, bill number, and timestamp

US-015-008: Currency Exchange Rate Auto-Update​

As an Accounts Manager, I want to have currency exchange rates update automatically daily, So that foreign guest invoices reflect accurate conversion rates without manual lookup. Priority: P1 | Points: 5 | Sprint: 10 | Status: Not Started

Implementation Status​

CurrencyService and CurrencyHistoryService exist in analytics-service. Dashboard currency settings page (/settings/currency) allows viewing and manual editing of rates. Property schema supports multi-currency (currency field with default "INR"). Gap: no external API integration for rate fetching; no scheduled job for daily updates; no rate margin configuration.

Acceptance Criteria​

Scenario: Daily exchange rate refresh from provider
  Given the property has configured Open Exchange Rates API with app_id
  And supported currencies include USD, EUR, GBP, AED, SGD
  When the daily scheduler runs at 06:00 IST
  Then HMP fetches latest rates for all configured currencies against INR
  And stores the rates with effective date and source identifier
  And the currency history log shows the update entry

Scenario: Exchange rate used for foreign guest billing
  Given the current USD-INR rate is 83.50 (fetched today at 06:00)
  And a foreign guest's folio has charges totaling INR 25,000
  When the guest requests billing in USD
  Then the invoice shows both INR 25,000 and USD 299.40 (25,000 / 83.50)
  And the exchange rate, source, and effective date are printed on the invoice

US-015-009: Webhook Management with Retry & Dead-Letter​

As a third-party developer, I want to register webhook URLs to receive real-time events from HMP, So that my external system stays synchronized without polling. Priority: P1 | Points: 8 | Sprint: 9 | Status: Partial

Implementation Status​

Basic webhook registration and delivery exist in integration-service. WhatsApp webhook controller handles inbound WhatsApp events. Gap: no exponential backoff retry; no dead-letter queue for permanently failed deliveries; no webhook delivery dashboard; no HMAC signature on outbound webhooks; no event filtering per subscription.

Acceptance Criteria​

Scenario: Webhook delivery with HMAC signature
  Given external system "ChannelBridge" has registered webhook URL "https://cb.example.com/hmp-events"
  And subscribed to events ["reservation.created", "reservation.cancelled"]
  When a reservation is created in HMP
  Then HMP sends POST to "https://cb.example.com/hmp-events" with JSON payload
  And the request includes header X-HMP-Signature containing HMAC-SHA256 of the body
  And the request includes header X-HMP-Event with value "reservation.created"
  And the delivery is logged with status "DELIVERED" and response time

Scenario: Failed webhook with exponential backoff
  Given webhook URL "https://cb.example.com/hmp-events" returns HTTP 500
  When the first delivery attempt fails
  Then HMP retries after 1 second, then 2s, 4s, 8s, 16s (5 retries total)
  And each retry is logged with attempt number and response code
  And after all retries fail, the event is moved to dead-letter queue
  And the webhook subscription status changes to "DEGRADED"

Scenario: Webhook delivery dashboard
  Given the admin navigates to Settings > Integrations > Webhooks
  Then the dashboard shows all registered webhooks with status (ACTIVE/DEGRADED/DISABLED)
  And delivery metrics: total sent, success rate, average response time
  And a log of recent deliveries with ability to replay failed events

US-015-010: API Key Management with Scoped Permissions​

As an Admin, I want to generate API keys for third-party systems with specific endpoint permissions, So that integrators have least-privilege access and I can track their usage. Priority: P1 | Points: 5 | Sprint: 9 | Status: Partial

Implementation Status​

API key generation exists in auth-service with basic validation. LicenseController and LicenseService in api-gateway handle key verification. Gap: no per-endpoint scoping (keys grant full access); no usage metering per key; no dashboard UI for key management; no key rotation workflow.

Acceptance Criteria​

Scenario: Generate scoped API key
  Given the admin navigates to Settings > API Keys
  When they click "Generate New Key" with name "POS-Vendor-ABC"
  And select permissions: "pos.orders.read", "pos.orders.create", "pos.menu.read"
  And set rate limit to 100 requests/minute
  Then the system generates a key "hmp_live_abc123..." displayed once
  And the key record stores the scoped permissions and rate limit
  And the key is hashed (SHA-256) before database storage

Scenario: Scoped key blocked from unauthorized endpoint
  Given API key "hmp_live_abc123" has permissions ["pos.orders.read", "pos.orders.create"]
  When the key is used to call GET /api/v1/guests
  Then the API gateway returns HTTP 403 with message "Insufficient API key permissions"
  And the access attempt is logged in the audit trail

Scenario: API key rotation
  Given API key "hmp_live_abc123" was created 90 days ago
  When the admin clicks "Rotate Key"
  Then a new key "hmp_live_def456" is generated with the same permissions
  And the old key "hmp_live_abc123" remains valid for 7 days (grace period)
  And after 7 days the old key is automatically deactivated

US-015-011: Stripe Payment Gateway (International)​

As a Revenue Manager, I want to offer Stripe as a payment option for international guests, So that guests from outside India can pay with their preferred international cards and wallets. Priority: P2 | Points: 8 | Sprint: 14 | Status: Not Started

Implementation Status​

Only Razorpay adapter exists in @hmp-backend/payments. No Stripe SDK integration, no multi-gateway routing logic, no currency-based gateway selection.

Acceptance Criteria​

Scenario: International guest pays via Stripe
  Given the property has both Razorpay and Stripe configured
  And a guest from the UK is booking a room priced at INR 15,000
  When the guest selects "Pay with International Card" on the booking engine
  Then the system routes to Stripe Checkout with amount converted to GBP
  And Stripe processes the payment with 3D Secure if required
  And the payment confirmation is recorded in HMP with Stripe charge ID

Scenario: Gateway failover from Razorpay to Stripe
  Given Razorpay API returns HTTP 503 (service unavailable)
  When an Indian guest attempts to pay INR 10,000
  Then HMP detects the Razorpay failure and shows fallback option
  And the guest can complete payment via Stripe (INR processing)
  And the failover event is logged with original gateway and fallback gateway