Skip to content

Payments

The payments domain handles payment processing for SMACKZ orders. Payment integration is primarily handled through POS adapters (currently Clover) with PCI-compliant card handling.

Payment Flow

Customer selects items and proceeds to checkout
       |
       v
Frontend collects payment method
       |
       +---> Saved card (stored via POS adapter)
       +---> New card (tokenized client-side)
       |
       v
Order placed via Yum API
       |
       v
Payment processed through POS adapter
       |
       +---> Success: order confirmed
       +---> Failure: order marked as payment failed

Clover Payment Integration

The POS Adapters service handles Clover payment processing:

  • Card tokenization -- Uses the Clover JavaScript SDK on the frontend to tokenize card details client-side (PCI-compliant -- raw card numbers never touch SMACKZ servers)
  • Payment method storage -- Customers can save cards for future use via POST /api/v1/clover/users/{userId}/payment-methods
  • Payment execution -- When an order is placed, the adapter creates a Clover order and processes payment

Key Endpoints (POS Adapter)

Endpoint Method Description
/clover/users/{userId}/payment-methods POST Store a payment method
/clover/users/{userId}/payment-methods GET List saved payment methods
/clover/restaurants/{id}/orders POST Create order with payment in Clover

Security

  • Card details are tokenized client-side using the Clover JavaScript SDK
  • Raw card numbers never reach SMACKZ backend servers
  • Stored payment tokens are encrypted at rest
  • Only authenticated users can access their own payment methods
  • SuperAdmin cannot access customer payment data

Order Financial Data

Order totals in the orderMaster table include:

Field Description
subtotal Sum of line item prices
tax_amount Total tax
tax_breakdown JSONB array of per-rate tax details
discount_amount Applied offers/loyalty discounts
delivery_fee Delivery charge (if applicable)
total_price Final amount charged
refund JSONB with refund details (if refunded)

Analytics

Payment and revenue data flows to the lakehouse for analytics:

  • Revenue metrics exclude cancelled and refunded orders
  • AOV (average order value) tracked daily, weekly, monthly
  • Tax breakdown available for reporting

Key Files

  • Smackz-POS-Adapters/src/services/ -- Payment processing logic
  • yum/api/db/models/orderMaster.ts -- Order financial fields
  • smackz-lakehouse/metabase/metrics/revenue_daily.sql -- Revenue metric definition