backend-manager 5.0.88 → 5.0.91

package/src/manager/routes/payments/intent/processors/stripe.js

@@ -1,3 +1,5 @@
+const resolvePriceId = require('../../../../libraries/payment-processors/resolve-price-id.js');
+
 /**
  * Stripe intent processor
  * Creates Stripe Checkout Sessions for subscription and one-time purchases
@@ -12,11 +14,11 @@ module.exports = {
    * @param {string} options.productId - Product ID from config (e.g., 'premium')
    * @param {string} options.frequency - 'monthly' or 'annually' (subscriptions only)
    * @param {boolean} options.trial - Whether to include a trial period (subscriptions only)
-   * @param {object} options.config - BEM config
-   * @param {object} options.Manager - Manager instance
+   * @param {string} options.confirmationUrl - Success redirect URL
+   * @param {string} options.cancelUrl - Cancel redirect URL
    * @returns {object} { id, url, raw }
    */
-  async createIntent({ uid, product, productId, frequency, trial, config, Manager, assistant }) {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, confirmationUrl, cancelUrl, assistant }) {
     // Initialize Stripe SDK
     const StripeLib = require('../../../../libraries/payment-processors/stripe.js');
     const stripe = StripeLib.init();
@@ -24,65 +26,27 @@ module.exports = {
     const productType = product.type || 'subscription';
 
     // Resolve the Stripe price ID based on product type
-    let priceId;
-    if (productType === 'subscription') {
-      priceId = product.prices?.[frequency]?.stripe;
-      if (!priceId) {
-        throw new Error(`No Stripe price found for ${productId}/${frequency}`);
-      }
-    } else {
-      priceId = product.prices?.once?.stripe;
-      if (!priceId) {
-        throw new Error(`No Stripe price found for ${productId}/once`);
-      }
-    }
+    const priceId = resolvePriceId(product, productType, frequency);
 
     // Resolve or create Stripe customer (keyed by uid in metadata)
     const email = assistant?.getUser()?.auth?.email || null;
     const customer = await resolveCustomer(stripe, uid, email, assistant);
 
-    assistant?.log(`Stripe checkout: type=${productType}, priceId=${priceId}, uid=${uid}, customerId=${customer.id}, trial=${trial}, trialDays=${product.trial?.days || 'none'}`);
-
-    // Build confirmation redirect URL
-    const baseUrl = Manager.project.websiteUrl;
-    const amount = productType === 'subscription'
-      ? (product.prices?.[frequency]?.amount || 0)
-      : (product.prices?.once?.amount || 0);
-
-    let confirmationUrl = new URL('/payment/confirmation', baseUrl);
-    confirmationUrl.searchParams.set('productId', productId);
-    confirmationUrl.searchParams.set('productName', product.name || productId);
-    confirmationUrl.searchParams.set('amount', trial && product.trial?.days ? '0' : String(amount));
-    confirmationUrl.searchParams.set('currency', 'USD');
-    confirmationUrl.searchParams.set('frequency', frequency || 'once');
-    confirmationUrl.searchParams.set('paymentMethod', 'stripe');
-    confirmationUrl.searchParams.set('trial', String(!!trial && !!product.trial?.days));
-    confirmationUrl.searchParams.set('track', 'true');
-    // Append orderId as raw string — Stripe replaces {CHECKOUT_SESSION_ID} at redirect
-    // time, but only if the braces are NOT URL-encoded
-    confirmationUrl = `${confirmationUrl.toString()}&orderId={CHECKOUT_SESSION_ID}`;
-
-    let cancelUrl = new URL('/payment/checkout', baseUrl);
-    cancelUrl.searchParams.set('product', productId);
-    if (frequency) {
-      cancelUrl.searchParams.set('frequency', frequency);
-    }
-    cancelUrl.searchParams.set('payment', 'cancelled');
-    cancelUrl = cancelUrl.toString();
+    assistant.log(`Stripe checkout: type=${productType}, priceId=${priceId}, uid=${uid}, customerId=${customer.id}, trial=${trial}, trialDays=${product.trial?.days || 'none'}`);
 
     // Build session params based on product type
     let sessionParams;
 
     if (productType === 'subscription') {
-      sessionParams = buildSubscriptionSession({ priceId, customer, uid, productId, frequency, trial, product, confirmationUrl, cancelUrl });
+      sessionParams = buildSubscriptionSession({ priceId, customer, uid, orderId, productId, frequency, trial, product, confirmationUrl, cancelUrl });
     } else {
-      sessionParams = buildOneTimeSession({ priceId, customer, uid, productId, product, confirmationUrl, cancelUrl });
+      sessionParams = buildOneTimeSession({ priceId, customer, uid, orderId, productId, product, confirmationUrl, cancelUrl });
     }
 
     // Create the checkout session
     const session = await stripe.checkout.sessions.create(sessionParams);
 
-    assistant?.log(`Stripe session created: sessionId=${session.id}, mode=${sessionParams.mode}, url=${session.url}`);
+    assistant.log(`Stripe session created: sessionId=${session.id}, mode=${sessionParams.mode}, url=${session.url}`);
 
     return {
       id: session.id,
@@ -95,7 +59,7 @@ module.exports = {
 /**
  * Build Stripe Checkout Session params for a subscription
  */
-function buildSubscriptionSession({ priceId, customer, uid, productId, frequency, trial, product, confirmationUrl, cancelUrl }) {
+function buildSubscriptionSession({ priceId, customer, uid, orderId, productId, frequency, trial, product, confirmationUrl, cancelUrl }) {
   const sessionParams = {
     mode: 'subscription',
     customer: customer.id,
@@ -106,12 +70,14 @@ function buildSubscriptionSession({ priceId, customer, uid, productId, frequency
     subscription_data: {
       metadata: {
         uid: uid,
+        orderId: orderId,
       },
     },
     success_url: confirmationUrl,
     cancel_url: cancelUrl,
     metadata: {
       uid: uid,
+      orderId: orderId,
       productId: productId,
       frequency: frequency,
     },
@@ -128,7 +94,7 @@ function buildSubscriptionSession({ priceId, customer, uid, productId, frequency
 /**
  * Build Stripe Checkout Session params for a one-time payment
  */
-function buildOneTimeSession({ priceId, customer, uid, productId, product, confirmationUrl, cancelUrl }) {
+function buildOneTimeSession({ priceId, customer, uid, orderId, productId, product, confirmationUrl, cancelUrl }) {
   return {
     mode: 'payment',
     customer: customer.id,
@@ -139,12 +105,14 @@ function buildOneTimeSession({ priceId, customer, uid, productId, product, confi
     payment_intent_data: {
       metadata: {
         uid: uid,
+        orderId: orderId,
       },
     },
     success_url: confirmationUrl,
     cancel_url: cancelUrl,
     metadata: {
       uid: uid,
+      orderId: orderId,
       productId: productId,
     },
   };
@@ -162,7 +130,7 @@ async function resolveCustomer(stripe, uid, email, assistant) {
 
   if (search.data.length > 0) {
     const existing = search.data[0];
-    assistant?.log(`Found existing Stripe customer: ${existing.id}`);
+    assistant.log(`Found existing Stripe customer: ${existing.id}`);
     return existing;
   }
 
@@ -176,6 +144,6 @@ async function resolveCustomer(stripe, uid, email, assistant) {
   }
 
   const customer = await stripe.customers.create(params);
-  assistant?.log(`Created new Stripe customer: ${customer.id}`);
+  assistant.log(`Created new Stripe customer: ${customer.id}`);
   return customer;
 }

package/src/manager/routes/payments/intent/processors/test.js

@@ -1,4 +1,5 @@
 const fetch = require('wonderful-fetch');
+const resolvePriceId = require('../../../../libraries/payment-processors/resolve-price-id.js');
 
 /**
  * Test intent processor
@@ -16,12 +17,13 @@ module.exports = {
    * @param {string} options.productId - Product ID from config
    * @param {string} options.frequency - 'monthly' or 'annually' (subscriptions only)
    * @param {boolean} options.trial - Whether to include a trial period (subscriptions only)
-   * @param {object} options.config - BEM config
+   * @param {string} options.confirmationUrl - Success redirect URL
+   * @param {string} options.cancelUrl - Cancel redirect URL
    * @param {object} options.Manager - Manager instance
    * @param {object} options.assistant - Assistant instance
    * @returns {object} { id, url, raw }
    */
-  async createIntent({ uid, product, productId, frequency, trial, config, Manager, assistant }) {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, confirmationUrl, Manager, assistant }) {
     // Guard: test processor is not available in production
     if (assistant.isProduction()) {
       throw new Error('Test processor is not available in production');
@@ -30,10 +32,10 @@ module.exports = {
     const productType = product.type || 'subscription';
 
     if (productType === 'subscription') {
-      return createSubscriptionIntent({ uid, product, productId, frequency, trial, config, Manager, assistant });
+      return createSubscriptionIntent({ uid, orderId, product, frequency, trial, confirmationUrl, Manager, assistant });
     }
 
-    return createOneTimeIntent({ uid, product, productId, config, Manager, assistant });
+    return createOneTimeIntent({ uid, orderId, product, productId, confirmationUrl, Manager, assistant });
   },
 };
 
@@ -41,12 +43,9 @@ module.exports = {
  * Create a test subscription intent
  * Generates Stripe-shaped subscription + customer.subscription.created event
  */
-async function createSubscriptionIntent({ uid, product, productId, frequency, trial, config, Manager, assistant }) {
+async function createSubscriptionIntent({ uid, orderId, product, frequency, trial, confirmationUrl, Manager, assistant }) {
   // Get the price ID for the requested frequency
-  const priceId = product.prices?.[frequency]?.stripe;
-  if (!priceId) {
-    throw new Error(`No Stripe price found for ${productId}/${frequency}`);
-  }
+  const priceId = resolvePriceId(product, 'subscription', frequency);
 
   // Generate IDs
   const timestamp = Date.now();
@@ -68,7 +67,7 @@ async function createSubscriptionIntent({ uid, product, productId, frequency, tr
     id: subscriptionId,
     object: 'subscription',
     status: trial && product.trial?.days ? 'trialing' : 'active',
-    metadata: { uid },
+    metadata: { uid, orderId },
     plan: { id: priceId, interval },
     current_period_end: periodEnd,
     current_period_start: now,
@@ -94,14 +93,14 @@ async function createSubscriptionIntent({ uid, product, productId, frequency, tr
     data: { object: subscription },
   };
 
-  assistant?.log(`Test subscription intent: sessionId=${sessionId}, subscriptionId=${subscriptionId}, eventId=${eventId}, trial=${!!subscription.trial_start}`);
+  assistant.log(`Test subscription intent: sessionId=${sessionId}, subscriptionId=${subscriptionId}, eventId=${eventId}, trial=${!!subscription.trial_start}`);
 
   // Auto-fire webhook
   fireWebhook({ event, Manager, assistant });
 
   return {
     id: sessionId,
-    url: `${config.brand?.url || 'https://example.com'}/payment/confirmation?session=${sessionId}`,
+    url: confirmationUrl,
     raw: { id: sessionId, object: 'checkout.session', subscription: subscriptionId },
   };
 }
@@ -110,12 +109,9 @@ async function createSubscriptionIntent({ uid, product, productId, frequency, tr
  * Create a test one-time payment intent
  * Generates Stripe-shaped checkout session + checkout.session.completed event
  */
-async function createOneTimeIntent({ uid, product, productId, config, Manager, assistant }) {
-  // Get the price ID for one-time purchase
-  const priceId = product.prices?.once?.stripe;
-  if (!priceId) {
-    throw new Error(`No Stripe price found for ${productId}/once`);
-  }
+async function createOneTimeIntent({ uid, orderId, product, productId, confirmationUrl, Manager, assistant }) {
+  // Validate that a price exists (resolvePriceId throws if not found)
+  resolvePriceId(product, 'one-time', null);
 
   // Generate IDs
   const timestamp = Date.now();
@@ -129,7 +125,7 @@ async function createOneTimeIntent({ uid, product, productId, config, Manager, a
     mode: 'payment',
     status: 'complete',
     payment_status: 'paid',
-    metadata: { uid, productId },
+    metadata: { uid, orderId, productId },
     amount_total: Math.round((product.prices?.once?.amount || 0) * 100),
     currency: 'usd',
   };
@@ -141,14 +137,14 @@ async function createOneTimeIntent({ uid, product, productId, config, Manager, a
     data: { object: session },
   };
 
-  assistant?.log(`Test one-time intent: sessionId=${sessionId}, eventId=${eventId}, productId=${productId}`);
+  assistant.log(`Test one-time intent: sessionId=${sessionId}, eventId=${eventId}, productId=${productId}`);
 
   // Auto-fire webhook
   fireWebhook({ event, Manager, assistant });
 
   return {
     id: sessionId,
-    url: `${config.brand?.url || 'https://example.com'}/payment/confirmation?session=${sessionId}`,
+    url: confirmationUrl,
     raw: { id: sessionId, object: 'checkout.session', mode: 'payment' },
   };
 }
@@ -164,6 +160,6 @@ function fireWebhook({ event, Manager, assistant }) {
     body: event,
     timeout: 15000,
   }).catch((e) => {
-    assistant?.log(`Test processor auto-webhook failed: ${e.message}`);
+    assistant.log(`Test processor auto-webhook failed: ${e.message}`);
   });
 }

package/src/manager/routes/payments/webhook/post.js

@@ -82,7 +82,7 @@ module.exports = async ({ assistant, Manager, libraries }) => {
     processor: processor,
     status: 'pending',
     raw: raw,
-    uid: uid,
+    owner: uid,
     event: {
       type: eventType,
       category: category,

package/src/test/runner.js

@@ -1,3 +1,4 @@
+const os = require('os');
 const path = require('path');
 const jetpack = require('fs-jetpack');
 const chalk = require('chalk');
@@ -52,6 +53,16 @@ class TestRunner {
    * Main run method
    */
   async run() {
+    // Abort if BEM is running from the user's home directory (e.g., accidental ~/node_modules install)
+    const homeDir = os.homedir();
+    if (__dirname.startsWith(path.join(homeDir, 'node_modules'))) {
+      console.error(chalk.red('\n  ERROR: BEM is running from ~/node_modules (home directory install).'));
+      console.error(chalk.red('  This is likely an accidental global install that shadows local project copies.'));
+      console.error(chalk.red(`  Fix: rm -rf ${path.join(homeDir, 'node_modules')} ${path.join(homeDir, 'package.json')} ${path.join(homeDir, 'package-lock.json')}`));
+      console.error(chalk.red(`  Running from: ${__dirname}\n`));
+      process.exit(1);
+    }
+
     // Set testing flag to skip external API calls (emails, SendGrid)
     process.env.BEM_TESTING = 'true';
 

package/src/test/test-accounts.js

@@ -175,6 +175,24 @@ const JOURNEY_ACCOUNTS = {
       subscription: { product: { id: 'basic' }, status: 'active' }, // Test's first step overwrites with correct paid product from config
     },
   },
+  'journey-payments-plan-change': {
+    id: 'journey-payments-plan-change',
+    uid: '_test-journey-payments-plan-change',
+    email: '_test.journey-payments-plan-change@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' }, // Test's first step overwrites with correct paid product from config
+    },
+  },
+  'journey-payments-one-time': {
+    id: 'journey-payments-one-time',
+    uid: '_test-journey-payments-one-time',
+    email: '_test.journey-payments-one-time@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
 };
 
 /**
@@ -363,13 +381,13 @@ async function deleteTestUsers(admin) {
 
   // Clean up payment-related collections for test accounts
   const testUids = Object.values(TEST_ACCOUNTS).map(a => a.uid);
-  const paymentCollections = ['payments-subscriptions', 'payments-webhooks', 'payments-intents', 'payments-one-time'];
+  const paymentCollections = ['payments-orders', 'payments-webhooks', 'payments-intents'];
 
   await Promise.all(
     paymentCollections.map(async (collection) => {
       try {
         const snapshot = await admin.firestore().collection(collection)
-          .where('uid', 'in', testUids)
+          .where('owner', 'in', testUids)
           .get();
 
         await Promise.all(

package/templates/backend-manager-config.json

@@ -72,18 +72,37 @@
           },
         },
       },
-      // Example one-time product:
-      // {
-      //   id: 'credits-100',
-      //   name: '100 Credits',
-      //   type: 'one-time',
-      //   prices: {
-      //     once: {
-      //       amount: 9.99,
-      //       stripe: null,
-      //     },
-      //   },
-      // },
+      {
+        id: 'ultimate',
+        name: 'Ultimate',
+        type: 'subscription',
+        limits: {
+          requests: 10000,
+        },
+        prices: {
+          monthly: {
+            amount: 19.99,
+            stripe: null,
+            paypal: null,
+          },
+          annually: {
+            amount: 199.99,
+            stripe: null,
+            paypal: null,
+          },
+        },
+      },
+      {
+        id: 'credits-100',
+        name: '100 Credits',
+        type: 'one-time',
+        prices: {
+          once: {
+            amount: 9.99,
+            stripe: null,
+          },
+        },
+      },
       // Add more products/tiers here
     ],
   },

package/test/events/payments/journey-payments-cancel.js

@@ -32,6 +32,7 @@ module.exports = {
           frequency: 'monthly',
         });
         assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
 
         // Wait for subscription to activate
         await waitFor(async () => {
@@ -42,6 +43,7 @@ module.exports = {
         const userDoc = await firestore.get(`users/${uid}`);
         assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should start as ${paidProduct.id}`);
         assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+        assert.equal(userDoc.subscription?.payment?.orderId, state.orderId, 'Order ID should match intent');
 
         state.subscriptionId = userDoc.subscription.payment.resourceId;
       },

package/test/events/payments/journey-payments-failure.js

@@ -35,6 +35,7 @@ module.exports = {
           frequency: 'monthly',
         });
         assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
 
         // Wait for subscription to activate
         await waitFor(async () => {
@@ -45,6 +46,7 @@ module.exports = {
         const userDoc = await firestore.get(`users/${uid}`);
         assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should start as ${paidProduct.id}`);
         assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+        assert.equal(userDoc.subscription?.payment?.orderId, state.orderId, 'Order ID should match intent');
 
         state.subscriptionId = userDoc.subscription.payment.resourceId;
       },

package/test/events/payments/journey-payments-one-time-failure.js

@@ -0,0 +1,105 @@
+/**
+ * Test: Payment Journey - One-Time Payment Failure
+ * Simulates: invoice.payment_failed for a non-subscription invoice → purchase-failed transition
+ *
+ * This verifies the webhook routing for one-time invoice failures:
+ * invoice.payment_failed with no subscription billing_reason → category: 'one-time'
+ *
+ * Uses the journey-payments-one-time account (one-time events don't modify subscription state)
+ */
+module.exports = {
+  description: 'Payment journey: one-time invoice.payment_failed → purchase-failed',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'resolve-one-time-product',
+      async run({ accounts, assert, state, config }) {
+        const uid = accounts['journey-payments-one-time'].uid;
+
+        // Resolve first one-time product from config
+        const oneTimeProduct = config.payment.products.find(p => p.type === 'one-time' && p.prices?.once);
+        assert.ok(oneTimeProduct, 'Config should have at least one one-time product');
+
+        state.uid = uid;
+        state.productId = oneTimeProduct.id;
+      },
+    },
+
+    {
+      name: 'send-one-time-payment-failed',
+      async run({ http, assert, state, config }) {
+        state.eventId = `_test-evt-journey-onetime-fail-${Date.now()}`;
+        state.invoiceId = `_test-inv-onetime-fail-${Date.now()}`;
+        state.orderId = `0000-0000-0000`; // Fake orderId for test
+
+        // Send invoice.payment_failed with a non-subscription billing reason
+        // This routes to category: 'one-time' in the webhook parser
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.eventId,
+          type: 'invoice.payment_failed',
+          data: {
+            object: {
+              id: state.invoiceId,
+              object: 'invoice',
+              billing_reason: 'manual',
+              amount_due: 999,
+              amount_paid: 0,
+              status: 'open',
+              metadata: {
+                uid: state.uid,
+                orderId: state.orderId,
+                productId: state.productId,
+              },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted');
+      },
+    },
+
+    {
+      name: 'webhook-categorized-as-one-time',
+      async run({ firestore, assert, state, waitFor }) {
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.eventId}`);
+          return doc?.status === 'completed' || doc?.status === 'failed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
+        assert.ok(webhookDoc, 'Webhook doc should exist');
+        assert.equal(webhookDoc.event?.category, 'one-time', 'Category should be one-time');
+        assert.equal(webhookDoc.event?.resourceType, 'invoice', 'Resource type should be invoice');
+        assert.equal(webhookDoc.transition, 'purchase-failed', 'Transition should be purchase-failed');
+      },
+    },
+
+    {
+      name: 'order-doc-created-with-failure',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.type, 'one-time', 'Type should be one-time');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+        assert.equal(orderDoc.processor, 'test', 'Processor should be test');
+      },
+    },
+
+    {
+      name: 'subscription-unchanged',
+      async run({ firestore, assert, state }) {
+        // One-time payment failures must NOT modify subscription state
+        const userDoc = await firestore.get(`users/${state.uid}`);
+
+        assert.equal(
+          userDoc.subscription?.product?.id,
+          'basic',
+          'Subscription should remain basic after one-time failure',
+        );
+      },
+    },
+  ],
+};

package/test/events/payments/journey-payments-one-time.js

@@ -0,0 +1,128 @@
+/**
+ * Test: Payment Journey - One-Time Purchase
+ * Simulates: user → test intent (one-time product) → auto-webhook → purchase-completed
+ *
+ * Uses the test processor to exercise the full intent→webhook→trigger pipeline
+ * for one-time payments. Unlike subscriptions, one-time payments only write to
+ * payments-orders/{orderId} — they do NOT modify users/{uid}.subscription.
+ *
+ * Requires at least one product with type: 'one-time' in config.payment.products
+ */
+module.exports = {
+  description: 'Payment journey: one-time purchase via test intent → purchase-completed',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'resolve-one-time-product',
+      async run({ accounts, firestore, assert, state, config }) {
+        const uid = accounts['journey-payments-one-time'].uid;
+        const userDoc = await firestore.get(`users/${uid}`);
+
+        assert.ok(userDoc, 'User doc should exist');
+
+        // Resolve first one-time product from config
+        const oneTimeProduct = config.payment.products.find(p => p.type === 'one-time' && p.prices?.once);
+        assert.ok(oneTimeProduct, 'Config should have at least one one-time product');
+
+        state.uid = uid;
+        state.productId = oneTimeProduct.id;
+        state.productName = oneTimeProduct.name;
+        state.price = oneTimeProduct.prices.once.amount;
+
+        // Snapshot subscription before purchase — should remain unchanged after
+        state.subscriptionBefore = userDoc.subscription || null;
+      },
+    },
+
+    {
+      name: 'create-one-time-intent',
+      async run({ http, assert, state }) {
+        const response = await http.as('journey-payments-one-time').post('payments/intent', {
+          processor: 'test',
+          productId: state.productId,
+        });
+
+        assert.isSuccess(response, 'Intent should succeed');
+        assert.ok(response.data.id, 'Should return intent ID');
+        assert.ok(response.data.orderId, 'Should return orderId');
+        assert.match(response.data.orderId, /^\d{4}-\d{4}-\d{4}$/, 'orderId should be XXXX-XXXX-XXXX format');
+        assert.ok(response.data.url, 'Should return URL');
+
+        state.intentId = response.data.id;
+        state.orderId = response.data.orderId;
+
+        // Derive webhook event ID from intent ID (same timestamp)
+        state.eventId = response.data.id.replace('_test-cs-', '_test-evt-');
+      },
+    },
+
+    {
+      name: 'webhook-transition-purchase-completed',
+      async run({ firestore, assert, state, waitFor }) {
+        // Poll until the webhook is processed
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.eventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.eventId}`);
+        assert.ok(webhookDoc, 'Webhook doc should exist');
+        assert.equal(webhookDoc.transition, 'purchase-completed', 'Transition should be purchase-completed');
+        assert.equal(webhookDoc.orderId, state.orderId, 'Webhook doc orderId should match intent');
+        assert.equal(webhookDoc.event?.category, 'one-time', 'Category should be one-time');
+      },
+    },
+
+    {
+      name: 'order-doc-created',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(orderDoc.type, 'one-time', 'Type should be one-time');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+        assert.equal(orderDoc.processor, 'test', 'Processor should be test');
+        assert.equal(orderDoc.unified.product.id, state.productId, `Product should be ${state.productId}`);
+        assert.equal(orderDoc.unified.payment.processor, 'test', 'Unified processor should be test');
+        assert.equal(orderDoc.unified.payment.orderId, state.orderId, 'Unified orderId should match');
+      },
+    },
+
+    {
+      name: 'subscription-unchanged',
+      async run({ firestore, assert, state }) {
+        // One-time payments must NOT modify users/{uid}.subscription
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        const subAfter = userDoc.subscription || null;
+
+        assert.deepEqual(
+          subAfter?.product?.id,
+          state.subscriptionBefore?.product?.id,
+          'Subscription product should be unchanged after one-time purchase',
+        );
+        assert.deepEqual(
+          subAfter?.status,
+          state.subscriptionBefore?.status,
+          'Subscription status should be unchanged after one-time purchase',
+        );
+      },
+    },
+
+    {
+      name: 'intent-doc-created',
+      async run({ firestore, assert, state }) {
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
+
+        assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(intentDoc.intentId, state.intentId, 'Intent ID should match processor session ID');
+        assert.equal(intentDoc.owner, state.uid, 'Owner should match');
+        assert.equal(intentDoc.processor, 'test', 'Processor should be test');
+        assert.equal(intentDoc.productId, state.productId, `Product should be ${state.productId}`);
+      },
+    },
+  ],
+};