Build a web store on StorePay PaaS

This guide covers shopper authentication against your tenant, a practical catalog model, one-time items, and subscriptions. Replace YOUR_DEPLOYMENT with your Vercel hostname.

1. Environment (local and Vercel)

Use the same variable names locally (.env.local) and in the Vercel project (Settings → Environment Variables).

• POSTGRES_URL — pooled Postgres (Prisma/Vercel Postgres).
• DIRECT_URL — direct connection for migrations.
• KV_REST_API_URL / KV_REST_API_TOKEN — Upstash REST (Redis cache for OAuth resolution).
• PAAS_CORS_ORIGINS — comma-separated origins allowed to call /api/v1/* from the browser (use * only for prototyping).

2. Register a storefront app (tenant)

1. Sign in on the platform, open Developer, create an app.
2. Copy the public key — this is your X-PaaS-App-Key.

3. Shopper OAuth (Google, Facebook, Apple)

Use the provider SDKs in your storefront (same OAuth client IDs you configured for the platform). After the shopper signs in, you receive either an access_token (Google, Facebook) or id_token (Apple). Send that token to the PaaS API — the platform verifies it, reads email / subject, upserts a global user, links them to your app as a customer, and caches the result in Redis.

POST https://YOUR_DEPLOYMENT/api/v1/auth/oauth
Headers:
  Content-Type: application/json
  X-PaaS-App-Key: <your public key>
Body:
  { "provider": "google", "accessToken": "..." }
  { "provider": "facebook", "accessToken": "..." }
  { "provider": "apple", "idToken": "..." }

Response:
  { "user": { "id", "email", "name", "image" },
    "customerId": "...",
    "appId": "...",
    "publicKey": "..." }

Subsequent calls from your SPA:

GET https://YOUR_DEPLOYMENT/api/v1/me
Headers:
  Authorization: Bearer <same provider token>
  X-Auth-Provider: google | facebook | apple
  X-PaaS-App-Key: <your public key>

4. Dashboard vs storefront

• POST /api/auth/oauth and GET /api/me — platform operator session (no app key).
• /api/v1/* — your customers’ apps; requires X-PaaS-App-Key and CORS as configured.

5. Catalog: products and subscription plans

Keep catalog tables in your database (or extend this monorepo with Prisma models). A minimal shape:

• Product — id, merchantAppId, title, description, priceCents, currency, type one_time | subscription, active.
• Plan (for subscriptions) — interval (month/year), trial days, Stripe price id or store SKU references.

List products with a Next.js page or static JSON; filter by merchantAppId so each tenant only sees their SKUs.

6. Checkout and payments

• Web — Stripe Checkout or Payment Element; create Checkout Sessions server-side with metadata customerId and appId from step 3.
• Mobile IAP — keep purchase verification on your backend (Play/App Store APIs) and tie receipts to user.id or customerId.

7. Subscriptions

1. Define recurring prices in Stripe Billing (web) or in-app subscription SKUs (mobile).
2. On customer.subscription.updated (Stripe) or platform RTDN/ASN webhooks, update a Subscription row keyed by customer.
3. Gate premium routes in your storefront by fetching subscription status from your API.

8. Security checklist

• Restrict PAAS_CORS_ORIGINS to your real storefront domains.
• Prefer short-lived provider tokens; refresh as needed.
• Never expose Postgres or Upstash admin URLs in client bundles.
• Rotate OAuth client secrets and database credentials on a schedule.

← Back to Developer