1) Set Up Stripe Dashboard

1. Activate account & get keys

   • Sign up/activate Stripe and copy the Secret / Publishable Key from the Developer Console.
   • For development, use the test environment: https://dashboard.stripe.com/test/apikeys.
   • 

2. Configure Webhook (required)
   

   • Select events: price.created/updated/deleted, checkout.session.completed, customer.subscription.updated, invoice.paid.
     
   • Endpoint: https://[YOUR_DOMAIN]/api/payment/stripe/webhooks.
   • Copy the Signing Secret for later (write it to ShipNowKit Dashboard or env vars).

3. Create Product & Price

   • Create products and prices in Stripe Dashboard, copy the Price ID.
     
   • The webhook automatically writes prices to the DB and syncs currency/amount/interval; no manual import needed.

2) Configure ShipNowKit Dashboard

1. Save credentials & price mappings

   • Path: Dashboard > Settings > Payment, choose Stripe.
   • Fill: stripe.publicKey, stripe.secretKey, stripe.webhookSecret (optional stripe.billingPortalConfigId).
     
   • In Price Mappings, map your business keys to Price IDs (e.g., PRO_MONTHLY -> price_xxx); if missing, it falls back to env NEXT_PUBLIC_[KEY].
   If admin config is disabled (DISABLE_ADMIN_CONFIG=true), put secrets in env vars:

   STRIPE_SECRET_KEY=sk_test_51Qdxxxxx
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51Qxxxx
   STRIPE_WEBHOOK_SECRET=whsec_ytScyxxxx
   STRIPE_BILLING_PORTAL_CONFIGURATION_ID=bp_...

   • Restart the service after updating envs.

2. Price/success pages

   • paymentConfig.successPage and paymentConfig.pricePage (see config/index.ts) control the Checkout success page and “view plans” default link.

3) Code Usage

1. Get priceId and amounts

   import { PriceBtn } from "@/components/price/PriceBtn";
   import { usePriceAmounts } from "@/components/price/hooks/usePriceAmounts";
   import { getPriceId } from "@/lib/client-config";
   
   const priceId = getPriceId("PRO_MONTHLY");
   const { priceAmounts, isLoadingPriceAmounts } = usePriceAmounts([priceId!]);
   
   <PriceBtn
     btnText="Subscribe now"
     targetPlan={{ isSubscription: true, priceId }}
     activePlans={[]}
     className="w-full"
   />;

   • getPriceId first reads Dashboard “Price Mappings”, falling back to NEXT_PUBLIC_[KEY].
   • usePriceAmounts fetches amount/currency in batch; PriceBtn handles auth check and Stripe Checkout redirect (see Payment Overview for details).

2. Customer Portal & subscription changes

   • Page /payment/billing generates a Stripe Customer Portal link for the current user; supports viewing invoices, changing or canceling subscriptions.

3. Event handling

   • Webhook includes signature validation and updates price/subscription/payment records:
     • price.created/updated/deleted syncs the price table
     • checkout.session.completed writes subscription or one-time orders
     • customer.subscription.updated handles upgrades/downgrades/cancellations
     • invoice.paid records renewal payments
   • Subscribe to business events via eventEmitter instead of parsing Stripe payloads directly:

   eventEmitter.on('subscription.plan_updated', async (eventId: string, data) => {
     console.log(`Subscription ${data.subscriptionId} updated: ${data.oldPriceId} -> ${data.newPriceId}`);
   });
   // Others: subscription.succeeded / renewed / canceled, payment.succeeded