Operator Guide

This guide is for technical operators maintaining the eCommerce backend. It links to the detailed runbooks in the repository.

NOTE

"Technical operator" is a reader persona, not a codebase role. The operational tasks below are performed with admin/infra access.

Setup

• The commerce engine is LunarPHP (lunarphp/lunar).
• Stripe PHP SDK is stripe/stripe-php at ^19.4.

The current commerce boundary is Hono → private Laravel internal endpoints → Lunar adapters. Follow the internal integration runbook for service networking, INTERNAL_API_BASE_URL, and the shared HONO_INTERNAL_API_TOKEN contract. Do not install or configure a Shopper service.

For payment setup, register the Laravel endpoint /api/webhooks/stripe in Stripe and subscribe only to the documented events in the Stripe Webhook Reference. Use the webhook rotation runbook for secret rotation. Configure Apple Pay and Google Pay in their respective Stripe and platform dashboards; do not place payment secrets in this guide.

Webhooks

• Stripe sends events to /api/webhooks/stripe (Laravel route — no /v1 segment).
• The event's event_id is inserted atomically before the processing job is dispatched, so repeat deliveries do not enqueue a second job.
• The 300-second signature tolerance only validates the Stripe signature timestamp; it is not the idempotency window.

Rotation runbook: docs/operations/stripe-webhook-rotation.md — rotate with a 24-hour overlap window.

Secret rotation

• APP_KEY: rotating it breaks the encrypted account_number on disbursements. Re-encrypt affected records after rotation. Runbook: docs/operations/app-key-rotation.md
• Ingestion tokens: rotate weekly.
• Hono/Laravel internal token: migrate both services to HONO_INTERNAL_API_TOKEN in one coordinated deployment. Remove SHOPPER_SERVICE_TOKEN; no legacy fallback is supported. The production internal base URL defaults to http://kubuli-admin-internal:8000 and is deployment-overridable. Keep /api/internal/* off public ingress.

Push token cleanup

WARNING

The is_active column for push tokens is not yet deployed. Only cleanup Strategy C currently works; Strategies A/B are not effective until the migration lands.

Runbook: docs/operations/push-token-cleanup.md

Troubleshooting

Symptom	Likely cause	Action
Webhook 404	Wrong path	Use /api/webhooks/stripe (no /v1)
Duplicate events processed	Idempotency missed	Verify the unique event_id row and queue worker health.
Payout fails	Manual Mobanking only	Bank-account payout is not implemented.

See the Stripe Webhook Reference for the full event contract.