backend-manager 5.0.175 → 5.0.176

package/CHANGELOG.md

@@ -14,6 +14,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.176] - 2026-03-30
+### Fixed
+- Chargeblast `alert.created` events use `alertId` instead of `id` — normalizer now accepts either field
+- Dispute charge matching now uses `charges.search()` instead of invoice search, fixing cases where Stripe invoices had `charge: null` even when paid (via balance/credit). Single reliable strategy: amount + ±2 day date window + card last4
+### Changed
+- Dispute `on-write` trigger is now processor-agnostic — Stripe-specific match/refund logic extracted to `processors/stripe.js`, matching the pattern used by payments-webhooks
+
 # [5.0.174] - 2026-03-27
 ### Fixed
 - Payments-orders `metadata.created` timestamp no longer overwritten on subsequent webhook events (renewals, cancellations, payment failures)

package/_zombie-sub-guard-wip/journey-payments-zombie-sub.js

@@ -0,0 +1,159 @@
+/**
+ * Test: Payment Journey - Zombie/Stale Subscription Guard
+ * Simulates: user has active sub A → webhook arrives for old sub B (cancellation)
+ *
+ * Verifies that on-write.js does NOT overwrite the user doc when a webhook
+ * arrives for a subscription that doesn't match the user's current resourceId.
+ * The order doc should still be updated, but user.subscription must remain unchanged.
+ */
+module.exports = {
+  description: 'Payment journey: zombie subscription webhook does not overwrite current subscription',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'setup-active-subscription',
+      async run({ accounts, firestore, assert, state, config, http, waitFor }) {
+        const uid = accounts['journey-payments-zombie-sub'].uid;
+
+        // Resolve first paid product from config
+        const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        assert.ok(paidProduct, 'Config should have at least one paid product');
+
+        state.uid = uid;
+        state.paidProductId = paidProduct.id;
+        state.paidProductName = paidProduct.name;
+        state.paidStripeProductId = paidProduct.stripe?.productId;
+
+        // Create subscription via test intent
+        const response = await http.as('journey-payments-zombie-sub').post('payments/intent', {
+          processor: 'test',
+          productId: paidProduct.id,
+          frequency: 'monthly',
+        });
+        assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
+
+        // Wait for subscription to activate
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.product?.id === paidProduct.id;
+        }, 15000, 500);
+
+        const userDoc = await firestore.get(`users/${uid}`);
+        assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should be ${paidProduct.id}`);
+        assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+
+        // Save the current (real) subscription resourceId
+        state.currentResourceId = userDoc.subscription.payment.resourceId;
+        assert.ok(state.currentResourceId, 'Should have a resourceId');
+      },
+    },
+
+    {
+      name: 'send-zombie-cancellation-webhook',
+      async run({ http, assert, state, config }) {
+        // Send a cancellation webhook for a DIFFERENT subscription (the "zombie")
+        state.zombieResourceId = 'sub_zombie_old_dead_' + Date.now();
+        state.zombieEventId = `_test-evt-zombie-cancel-${Date.now()}`;
+
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.zombieEventId,
+          type: 'customer.subscription.deleted',
+          data: {
+            object: {
+              id: state.zombieResourceId,
+              object: 'subscription',
+              status: 'canceled',
+              metadata: { uid: state.uid },
+              cancel_at_period_end: false,
+              canceled_at: Math.floor(Date.now() / 1000),
+              current_period_end: Math.floor(Date.now() / 1000),
+              current_period_start: Math.floor(Date.now() / 1000) - 86400 * 30,
+              start_date: Math.floor(Date.now() / 1000) - 86400 * 60,
+              trial_start: null,
+              trial_end: null,
+              plan: { product: state.paidStripeProductId, interval: 'month' },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted');
+      },
+    },
+
+    {
+      name: 'user-doc-unchanged',
+      async run({ firestore, assert, state, waitFor }) {
+        // Wait for the zombie webhook to complete processing
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.zombieEventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        // Verify the webhook completed but did NOT trigger a transition
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.zombieEventId}`);
+        assert.equal(webhookDoc.status, 'completed', 'Webhook should complete successfully');
+        assert.equal(webhookDoc.transition, null, 'Transition should be null (suppressed for zombie sub)');
+
+        // Verify user doc was NOT overwritten — subscription should still be active with original resourceId
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        assert.equal(userDoc.subscription.status, 'active', 'User subscription should still be active');
+        assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should still be ${state.paidProductId}`);
+        assert.equal(userDoc.subscription.payment.resourceId, state.currentResourceId, 'ResourceId should still be the current subscription, not the zombie');
+        assert.notEqual(userDoc.subscription.payment.resourceId, state.zombieResourceId, 'ResourceId should NOT be the zombie subscription');
+      },
+    },
+
+    {
+      name: 'send-zombie-suspension-webhook',
+      async run({ http, assert, state, config }) {
+        // Also test that a payment failure for a zombie sub doesn't suspend the user
+        state.zombieSuspendEventId = `_test-evt-zombie-suspend-${Date.now()}`;
+
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.zombieSuspendEventId,
+          type: 'invoice.payment_failed',
+          data: {
+            object: {
+              id: state.zombieResourceId,
+              object: 'subscription',
+              status: 'active',
+              metadata: { uid: state.uid },
+              cancel_at_period_end: false,
+              canceled_at: null,
+              current_period_end: Math.floor(Date.now() / 1000) + 86400 * 30,
+              current_period_start: Math.floor(Date.now() / 1000),
+              start_date: Math.floor(Date.now() / 1000) - 86400 * 60,
+              trial_start: null,
+              trial_end: null,
+              plan: { product: state.paidStripeProductId, interval: 'month' },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted');
+      },
+    },
+
+    {
+      name: 'user-still-active-after-zombie-suspension',
+      async run({ firestore, assert, state, waitFor }) {
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.zombieSuspendEventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.zombieSuspendEventId}`);
+        assert.equal(webhookDoc.status, 'completed', 'Webhook should complete');
+        assert.equal(webhookDoc.transition, null, 'Transition should be null (suppressed for zombie sub)');
+
+        // User should STILL be active — zombie payment failure must not suspend them
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        assert.equal(userDoc.subscription.status, 'active', 'User should still be active after zombie payment failure');
+        assert.equal(userDoc.subscription.payment.resourceId, state.currentResourceId, 'ResourceId should still be the current subscription');
+      },
+    },
+  ],
+};

package/_zombie-sub-guard-wip/on-write.js

@@ -0,0 +1,442 @@
+const powertools = require('node-powertools');
+const transitions = require('./transitions/index.js');
+const { trackPayment } = require('./analytics.js');
+
+/**
+ * Firestore trigger: payments-webhooks/{eventId} onWrite
+ *
+ * Processes pending webhook events:
+ * 1. Loads the processor library
+ * 2. Fetches the latest resource from the processor API (not the stale webhook payload)
+ * 3. Branches on event.category to transform + write:
+ *    - subscription → toUnifiedSubscription → users/{uid}.subscription + payments-orders/{orderId}
+ *    - one-time    → toUnifiedOneTime → payments-orders/{orderId}
+ * 4. Detects state transitions and dispatches handler files (non-blocking)
+ * 5. Marks the webhook as completed
+ */
+module.exports = async ({ assistant, change, context }) => {
+  const Manager = assistant.Manager;
+  const admin = Manager.libraries.admin;
+
+  const dataAfter = change.after.data();
+
+  // Short-circuit: deleted doc or non-pending status
+  if (!dataAfter || dataAfter.status !== 'pending') {
+    return;
+  }
+
+  const eventId = context.params.eventId;
+  const webhookRef = admin.firestore().doc(`payments-webhooks/${eventId}`);
+
+  // Set status to processing
+  await webhookRef.set({ status: 'processing' }, { merge: true });
+
+  // Hoisted so orderId is available in catch block for audit trail
+  let orderId = null;
+
+  try {
+    const processor = dataAfter.processor;
+    let uid = dataAfter.owner;
+    const raw = dataAfter.raw;
+    const eventType = dataAfter.event?.type;
+    const category = dataAfter.event?.category;
+    const resourceType = dataAfter.event?.resourceType;
+    const resourceId = dataAfter.event?.resourceId;
+
+    assistant.log(`Processing webhook ${eventId}: processor=${processor}, eventType=${eventType}, category=${category}, resourceType=${resourceType}, resourceId=${resourceId}, uid=${uid || 'null'}`);
+
+    // Validate category
+    if (!category) {
+      throw new Error(`Webhook event has no category — cannot process`);
+    }
+
+    // Load the shared library for this processor
+    let library;
+    try {
+      library = require(`../../../libraries/payment/processors/${processor}.js`);
+    } catch (e) {
+      throw new Error(`Unknown processor library: ${processor}`);
+    }
+
+    // Fetch the latest resource from the processor API
+    // This ensures we always work with the most current state, not stale webhook data
+    const rawFallback = raw.data?.object || {};
+    const resource = await library.fetchResource(resourceType, resourceId, rawFallback, { admin, eventType, config: Manager.config });
+
+    assistant.log(`Fetched resource: type=${resourceType}, id=${resourceId}, status=${resource.status || 'unknown'}`);
+
+    // Resolve UID from the fetched resource if not available from webhook parse
+    // This handles events like PAYMENT.SALE where the Sale object doesn't carry custom_id
+    // but the parent subscription (fetched via fetchResource) does
+    if (!uid && library.getUid) {
+      uid = library.getUid(resource);
+      assistant.log(`UID resolved from fetched resource: uid=${uid || 'null'}, processor=${processor}, resourceType=${resourceType}`);
+
+      // Update the webhook doc with the resolved UID so it's persisted for debugging
+      if (uid) {
+        await webhookRef.set({ owner: uid }, { merge: true });
+      }
+    }
+
+    // Fallback: resolve UID from the hosted page's pass_thru_content
+    // Chargebee hosted page checkouts don't forward subscription[meta_data] to the subscription,
+    // but pass_thru_content is stored on the hosted page and contains our UID + orderId
+    let resolvedFromPassThru = false;
+    let passThruOrderId = null;
+    if (!uid && library.resolveUidFromHostedPage) {
+      const passThruResult = await library.resolveUidFromHostedPage(resourceId, assistant);
+      if (passThruResult) {
+        uid = passThruResult.uid;
+        passThruOrderId = passThruResult.orderId || null;
+        resolvedFromPassThru = true;
+        assistant.log(`UID resolved from hosted page pass_thru_content: uid=${uid}, orderId=${passThruOrderId}, resourceId=${resourceId}`);
+
+        await webhookRef.set({ owner: uid }, { merge: true });
+      }
+    }
+
+    // Validate UID — must have one by now
+    if (!uid) {
+      throw new Error(`Webhook event has no UID — could not extract from webhook parse, fetched ${resourceType} resource, or hosted page pass_thru_content`);
+    }
+
+    // Backfill: if UID was resolved from pass_thru_content, set meta_data on the subscription
+    // so future webhooks (renewals, cancellations) can resolve the UID directly
+    if (resolvedFromPassThru && resourceType === 'subscription' && library.setMetaData) {
+      library.setMetaData(resource, { uid, orderId: passThruOrderId })
+        .then(() => assistant.log(`Backfilled meta_data on subscription ${resourceId} + customer: uid=${uid}, orderId=${passThruOrderId}`))
+        .catch((e) => assistant.error(`Failed to backfill meta_data on ${resourceType} ${resourceId}: ${e.message}`));
+    }
+
+    // Build timestamps
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+    const webhookReceivedUNIX = dataAfter.metadata?.created?.timestampUNIX || nowUNIX;
+
+    // Extract orderId from resource (processor-agnostic)
+    // Falls back to pass_thru_content orderId when meta_data wasn't available on the resource
+    orderId = library.getOrderId(resource) || passThruOrderId;
+
+    // Process the payment event (subscription or one-time)
+    if (category !== 'subscription' && category !== 'one-time') {
+      throw new Error(`Unknown event category: ${category}`);
+    }
+
+    const transitionName = await processPaymentEvent({ category, library, resource, resourceType, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, assistant, raw });
+
+    // Mark webhook as completed (include transition name for auditing/testing)
+    await webhookRef.set({
+      status: 'completed',
+      owner: uid,
+      orderId: orderId,
+      transition: transitionName,
+      metadata: {
+        completed: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    }, { merge: true });
+
+    assistant.log(`Webhook ${eventId} completed`);
+  } catch (e) {
+    assistant.error(`Webhook ${eventId} failed: ${e.message}`, e);
+
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    // Mark as failed with error message
+    await webhookRef.set({
+      status: 'failed',
+      error: e.message || String(e),
+    }, { merge: true });
+
+    // Mark intent as failed if we resolved the orderId before the error
+    if (orderId) {
+      await admin.firestore().doc(`payments-intents/${orderId}`).set({
+        status: 'failed',
+        error: e.message || String(e),
+        metadata: {
+          completed: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+        },
+      }, { merge: true });
+    }
+  }
+};
+
+/**
+ * Process a payment event (subscription or one-time)
+ * 1. Staleness check
+ * 2. Read user doc (for transition detection)
+ * 3. Transform raw resource → unified object
+ * 4. Build order object
+ * 5. Detect and dispatch transition handlers (non-blocking)
+ * 6. Track analytics (non-blocking)
+ * 7. Write to Firestore (user doc for subscriptions + payments-orders)
+ */
+async function processPaymentEvent({ category, library, resource, resourceType, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, assistant, raw }) {
+  const Manager = assistant.Manager;
+  const admin = Manager.libraries.admin;
+  const isSubscription = category === 'subscription';
+
+  // Staleness check: skip if a newer webhook already wrote to this order
+  if (orderId) {
+    const existingDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+    if (existingDoc.exists) {
+      const existingUpdatedUNIX = existingDoc.data()?.metadata?.updated?.timestampUNIX || 0;
+      if (webhookReceivedUNIX < existingUpdatedUNIX) {
+        assistant.log(`Stale webhook ${eventId}: received=${webhookReceivedUNIX}, existing updated=${existingUpdatedUNIX}, skipping`);
+        return null;
+      }
+    }
+  }
+
+  // Read current user doc (needed for transition detection + handler context)
+  const userDoc = await admin.firestore().doc(`users/${uid}`).get();
+  const userData = userDoc.exists ? userDoc.data() : {};
+  const before = isSubscription ? (userData.subscription || null) : null;
+
+  assistant.log(`User doc for ${uid}: exists=${userDoc.exists}, email=${userData?.auth?.email || 'null'}, name=${userData?.personal?.name?.first || 'null'}, subscription=${userData?.subscription?.product?.id || 'null'}`);
+
+  // Auto-fill user name from payment processor if not already set
+  if (!userData?.personal?.name?.first) {
+    const customerName = extractCustomerName(resource, resourceType);
+    if (customerName?.first) {
+      await admin.firestore().doc(`users/${uid}`).set({
+        personal: { name: customerName },
+      }, { merge: true });
+      assistant.log(`Auto-filled user name from ${resourceType}: ${customerName.first} ${customerName.last || ''}`);
+    }
+  }
+
+  // Transform raw resource → unified object
+  const transformOptions = { config: Manager.config, eventName: eventType, eventId: eventId };
+  const unified = isSubscription
+    ? library.toUnifiedSubscription(resource, transformOptions)
+    : library.toUnifiedOneTime(resource, transformOptions);
+
+  // Override: immediately suspend on payment denial
+  // Processors keep the sub active while retrying, but we revoke access right away.
+  // If the retry succeeds (e.g. PAYMENT.SALE.COMPLETED), it will restore active status.
+  // PayPal: PAYMENT.SALE.DENIED, Stripe: invoice.payment_failed, Chargebee: payment_failed
+  const PAYMENT_DENIED_EVENTS = ['PAYMENT.SALE.DENIED', 'invoice.payment_failed', 'payment_failed'];
+  if (isSubscription && PAYMENT_DENIED_EVENTS.includes(eventType) && unified.status === 'active') {
+    assistant.log(`Overriding status to suspended: ${eventType} received but provider still says active`);
+    unified.status = 'suspended';
+  }
+
+  assistant.log(`Unified ${category}: product=${unified.product.id}, status=${unified.status}`, unified);
+
+  // Read checkout context from payments-intents (attribution, discount, supplemental)
+  let intentData = {};
+  if (orderId) {
+    const intentDoc = await admin.firestore().doc(`payments-intents/${orderId}`).get();
+    intentData = intentDoc.exists ? intentDoc.data() : {};
+  }
+
+  // Build the order object (single source of truth for handlers + Firestore)
+  const order = {
+    id: orderId,
+    type: category,
+    owner: uid,
+    productId: unified.product.id,
+    processor: processor,
+    resourceId: resourceId,
+    unified: unified,
+    attribution: intentData.attribution || {},
+    discount: intentData.discount || null,
+    supplemental: intentData.supplemental || {},
+    metadata: {
+      created: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+      updated: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+      updatedBy: {
+        event: {
+          name: eventType,
+          id: eventId,
+        },
+      },
+    },
+  };
+
+  // Guard: check if this webhook is for the user's current subscription
+  const currentResourceId = userData?.subscription?.payment?.resourceId;
+  const isCurrentSub = !currentResourceId || currentResourceId === resourceId;
+
+  // Detect and dispatch transition (non-blocking)
+  // Only run transitions for the user's current subscription — zombie webhooks should not trigger emails
+  const shouldRunHandlers = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
+  const transitionName = isCurrentSub
+    ? transitions.detectTransition(category, before, unified, eventType)
+    : null;
+
+  if (!isCurrentSub && isSubscription) {
+    const wouldBeTransition = transitions.detectTransition(category, before, unified, eventType);
+    if (wouldBeTransition) {
+      assistant.log(`Transition suppressed for stale sub: ${category}/${wouldBeTransition} (webhook resourceId=${resourceId} != current resourceId=${currentResourceId})`);
+    }
+  }
+
+  if (transitionName) {
+    assistant.log(`Transition detected: ${category}/${transitionName} (before.status=${before?.status || 'null'}, after.status=${unified.status})`);
+
+    if (shouldRunHandlers) {
+      // Extract unified refund details from the processor library (keeps handlers processor-agnostic)
+      const refundDetails = (transitionName === 'payment-refunded' && library.getRefundDetails)
+        ? library.getRefundDetails(raw)
+        : null;
+
+      transitions.dispatch(transitionName, category, {
+        before, after: unified, order, uid, userDoc: userData, assistant, refundDetails,
+      });
+    } else {
+      assistant.log(`Transition handler skipped (testing mode): ${category}/${transitionName}`);
+    }
+  }
+
+  // Track payment analytics (non-blocking)
+  // Fires independently of transitions — renewals have no transition but still need tracking
+  if (shouldRunHandlers) {
+    trackPayment({ category, transitionName, eventType, unified, order, uid, processor, assistant });
+  }
+
+  // Write unified subscription to user doc (subscriptions only)
+  if (isSubscription) {
+    if (isCurrentSub) {
+      await admin.firestore().doc(`users/${uid}`).set({ subscription: unified }, { merge: true });
+      assistant.log(`Updated users/${uid}.subscription: status=${unified.status}, product=${unified.product.id}`);
+
+      // Sync marketing contact with updated subscription data (non-blocking)
+      if (shouldRunHandlers) {
+        const email = Manager.Email(assistant);
+        const updatedUserDoc = { ...userData, subscription: unified };
+        email.sync(updatedUserDoc)
+          .then((r) => assistant.log('Marketing sync after payment:', r))
+          .catch((e) => assistant.error('Marketing sync after payment failed:', e));
+      }
+    } else {
+      assistant.log(`Skipping user doc update: webhook resourceId=${resourceId} does not match current subscription resourceId=${currentResourceId}. This is a stale/zombie subscription webhook — only the order doc will be updated.`);
+    }
+  }
+
+  // Write to payments-orders/{orderId}
+  if (orderId) {
+    const orderRef = admin.firestore().doc(`payments-orders/${orderId}`);
+    const orderSnap = await orderRef.get();
+
+    if (!orderSnap.exists) {
+      // Initialize requests on first creation only (avoid overwriting cancel/refund data set by endpoints)
+      order.requests = {
+        cancellation: null,
+        refund: null,
+      };
+    } else {
+      // Preserve original created timestamp on subsequent webhook events
+      order.metadata.created = orderSnap.data().metadata?.created || order.metadata.created;
+    }
+
+    await orderRef.set(order, { merge: true });
+    assistant.log(`Updated payments-orders/${orderId}: type=${category}, uid=${uid}, eventType=${eventType}`);
+  }
+
+  // Update payments-intents/{orderId} status to match webhook outcome
+  if (orderId) {
+    await admin.firestore().doc(`payments-intents/${orderId}`).set({
+      status: 'completed',
+      metadata: {
+        completed: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    }, { merge: true });
+    assistant.log(`Updated payments-intents/${orderId}: status=completed`);
+  }
+
+  // Mark abandoned cart as completed (non-blocking, fire-and-forget)
+  const { COLLECTION } = require('../../../libraries/abandoned-cart-config.js');
+  admin.firestore().doc(`${COLLECTION}/${uid}`).set({
+    status: 'completed',
+    metadata: {
+      updated: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+    },
+  }, { merge: true })
+    .then(() => assistant.log(`Updated ${COLLECTION}/${uid}: status=completed`))
+    .catch((e) => {
+      // Ignore not-found — cart may not exist for this user
+      if (e.code !== 5) {
+        assistant.error(`Failed to update ${COLLECTION}/${uid}: ${e.message}`);
+      }
+    });
+
+  return transitionName;
+}
+
+/**
+ * Extract customer name from a raw payment processor resource
+ *
+ * @param {object} resource - Raw processor resource (Stripe subscription, session, invoice)
+ * @param {string} resourceType - 'subscription' | 'session' | 'invoice'
+ * @returns {{ first: string, last: string }|null}
+ */
+function extractCustomerName(resource, resourceType) {
+  let fullName = null;
+
+  // Checkout sessions have customer_details.name
+  if (resourceType === 'session') {
+    fullName = resource.customer_details?.name;
+  }
+
+  // Invoices have customer_name
+  if (resourceType === 'invoice') {
+    fullName = resource.customer_name;
+  }
+
+  // PayPal orders have payer.name
+  if (resourceType === 'order') {
+    const givenName = resource.payer?.name?.given_name;
+    const surname = resource.payer?.name?.surname;
+
+    if (givenName) {
+      const { capitalize } = require('../../../libraries/infer-contact.js');
+      return {
+        first: capitalize(givenName) || null,
+        last: capitalize(surname) || null,
+      };
+    }
+  }
+
+  // Chargebee subscriptions carry shipping_address / billing_address with first_name + last_name
+  if (resourceType === 'subscription') {
+    const addr = resource.shipping_address || resource.billing_address;
+    if (addr?.first_name) {
+      const { capitalize } = require('../../../libraries/infer-contact.js');
+      return {
+        first: capitalize(addr.first_name) || null,
+        last: capitalize(addr.last_name) || null,
+      };
+    }
+  }
+
+  if (!fullName) {
+    return null;
+  }
+
+  const { capitalize } = require('../../../libraries/infer-contact.js');
+  const parts = fullName.trim().split(/\s+/);
+  return {
+    first: capitalize(parts[0]) || null,
+    last: capitalize(parts.slice(1).join(' ')) || null,
+  };
+}

package/_zombie-sub-guard-wip/test-accounts.diff

@@ -0,0 +1,21 @@
+diff --git a/src/test/test-accounts.js b/src/test/test-accounts.js
+index 796f4c3..5b5efc4 100644
+--- a/src/test/test-accounts.js
++++ b/src/test/test-accounts.js
+@@ -417,6 +417,16 @@ const JOURNEY_ACCOUNTS = {
+       subscription: { product: { id: 'basic' }, status: 'active' },
+     },
+   },
++  // Journey: zombie/stale subscription guard (webhook for old sub should not overwrite current sub)
++  'journey-payments-zombie-sub': {
++    id: 'journey-payments-zombie-sub',
++    uid: '_test-journey-payments-zombie-sub',
++    email: '_test.journey-payments-zombie-sub@{domain}',
++    properties: {
++      roles: {},
++      subscription: { product: { id: 'basic' }, status: 'active' },
++    },
++  },
+   // Journey: legacy product ID resolution (webhook with legacy product ID maps to correct product)
+   'journey-payments-legacy-product': {
+     id: 'journey-payments-legacy-product',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.175",
+  "version": "5.0.176",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/manager/events/firestore/payments-disputes/on-write.js

@@ -1,16 +1,15 @@
-const moment = require('moment');
+const path = require('path');
 const powertools = require('node-powertools');
 
 /**
  * Firestore trigger: payments-disputes/{alertId} onWrite
  *
  * Processes pending dispute alerts:
- * 1. Tries direct match via charge ID or payment intent (from Chargeblast alert.updated)
- * 2. Falls back to searching Stripe invoices by date range + amount + card last4
- * 3. Issues full refund on matched charge
- * 4. Cancels subscription immediately (Stripe fires webhook → existing pipeline handles user doc)
- * 5. Sends email alert to brand contact
- * 6. Updates dispute document with results
+ * 1. Loads the processor module for the alert's payment processor
+ * 2. Searches for the matching charge via processor.searchAndMatch()
+ * 3. Issues refund + cancels subscription via processor.processDispute()
+ * 4. Sends email alert to brand contact
+ * 5. Updates dispute document with results
  */
 module.exports = async ({ assistant, change, context }) => {
   const Manager = assistant.Manager;
@@ -35,13 +34,16 @@ module.exports = async ({ assistant, change, context }) => {
 
     assistant.log(`Processing dispute ${alertId}: processor=${processor}, amount=${alert.amount}, card=****${alert.card.last4}, date=${alert.transactionDate}, chargeId=${alert.chargeId || 'none'}, paymentIntentId=${alert.paymentIntentId || 'none'}`);
 
-    // Only Stripe is supported for now
-    if (processor !== 'stripe') {
-      throw new Error(`Unsupported processor: ${processor}. Only 'stripe' is currently supported.`);
+    // Load the processor module
+    let processorModule;
+    try {
+      processorModule = require(path.resolve(__dirname, `processors/${processor}.js`));
+    } catch (e) {
+      throw new Error(`Unsupported dispute processor: ${processor}`);
     }
 
     // Search for the matching charge
-    const match = await searchAndMatch({ alert, assistant });
+    const match = await processorModule.searchAndMatch(alert, assistant);
 
     // Build timestamps
     const now = powertools.timestamp(new Date(), { output: 'string' });
@@ -80,13 +82,12 @@ module.exports = async ({ assistant, change, context }) => {
     }
 
     // Process refund and cancel
-    const result = await processDispute({ match, alert, assistant });
+    const result = await processorModule.processDispute(match, alert, assistant);
 
     // Update dispute document with results
     await disputeRef.set({
       status: 'resolved',
       match: {
-        method: match.method,
         invoiceId: match.invoiceId || null,
         subscriptionId: match.subscriptionId || null,
         customerId: match.customerId,
@@ -131,253 +132,6 @@ module.exports = async ({ assistant, change, context }) => {
   }
 };
 
-/**
- * Try to match the dispute alert to a Stripe charge.
- *
- * Strategy (in order):
- * 1. Direct lookup via charge ID (externalOrder from Chargeblast)
- * 2. Direct lookup via payment intent ID (metadata from Chargeblast)
- * 3. Fallback: search invoices by date range + amount + card last4
- *
- * @param {object} options
- * @param {object} options.alert - Normalized alert data
- * @param {object} options.assistant - Assistant instance
- * @returns {object|null} Match details or null
- */
-async function searchAndMatch({ alert, assistant }) {
-  const StripeLib = require('../../../libraries/payment/processors/stripe.js');
-  const stripe = StripeLib.init();
-
-  // Strategy 1: Direct charge lookup
-  if (alert.chargeId && alert.chargeId.startsWith('ch_')) {
-    assistant.log(`Trying direct charge lookup: ${alert.chargeId}`);
-
-    try {
-      const charge = await stripe.charges.retrieve(alert.chargeId, {
-        expand: ['invoice', 'customer'],
-      });
-
-      const match = await resolveMatchFromCharge({ charge, stripe, assistant, method: 'charge-id' });
-
-      if (match) {
-        return match;
-      }
-    } catch (e) {
-      assistant.log(`Direct charge lookup failed for ${alert.chargeId}: ${e.message}`);
-    }
-  }
-
-  // Strategy 2: Direct payment intent lookup
-  if (alert.paymentIntentId && alert.paymentIntentId.startsWith('pi_')) {
-    assistant.log(`Trying direct payment intent lookup: ${alert.paymentIntentId}`);
-
-    try {
-      const pi = await stripe.paymentIntents.retrieve(alert.paymentIntentId, {
-        expand: ['latest_charge', 'latest_charge.invoice', 'latest_charge.customer'],
-      });
-
-      const charge = pi.latest_charge;
-      if (charge) {
-        const match = await resolveMatchFromCharge({ charge, stripe, assistant, method: 'payment-intent' });
-
-        if (match) {
-          return match;
-        }
-      }
-    } catch (e) {
-      assistant.log(`Direct payment intent lookup failed for ${alert.paymentIntentId}: ${e.message}`);
-    }
-  }
-
-  // Strategy 3: Fallback — search invoices by date range + amount + card last4
-  return searchInvoicesFallback({ alert, stripe, assistant });
-}
-
-/**
- * Build a match object from a Stripe charge
- */
-async function resolveMatchFromCharge({ charge, stripe, assistant, method }) {
-  if (!charge || charge.status !== 'succeeded') {
-    assistant.log(`Charge ${charge?.id} status=${charge?.status}, skipping`);
-    return null;
-  }
-
-  // Resolve UID from customer metadata
-  let uid = null;
-  let email = null;
-  const customerId = typeof charge.customer === 'string' ? charge.customer : charge.customer?.id;
-
-  if (charge.customer && typeof charge.customer === 'object') {
-    uid = charge.customer.metadata?.uid || null;
-    email = charge.customer.email || null;
-  } else if (customerId) {
-    try {
-      const customer = await stripe.customers.retrieve(customerId);
-      uid = customer.metadata?.uid || null;
-      email = customer.email || null;
-    } catch (e) {
-      assistant.error(`Failed to retrieve customer ${customerId}: ${e.message}`);
-    }
-  }
-
-  // Resolve invoice/subscription
-  const invoiceId = typeof charge.invoice === 'string'
-    ? charge.invoice
-    : charge.invoice?.id || null;
-  const subscriptionId = typeof charge.invoice === 'object'
-    ? charge.invoice?.subscription || null
-    : null;
-
-  assistant.log(`Matched via ${method}: charge=${charge.id}, customer=${customerId}, uid=${uid}, invoice=${invoiceId}`);
-
-  return {
-    method: method,
-    invoiceId: invoiceId,
-    subscriptionId: subscriptionId,
-    customerId: customerId,
-    uid: uid,
-    email: email,
-    chargeId: charge.id,
-  };
-}
-
-/**
- * Fallback: search Stripe invoices by date range + amount and match card last4
- */
-async function searchInvoicesFallback({ alert, stripe, assistant }) {
-  const amountCents = Math.round(alert.amount * 100);
-  const alertDate = moment(alert.transactionDate);
-
-  if (!alertDate.isValid()) {
-    throw new Error(`Invalid transactionDate: ${alert.transactionDate}`);
-  }
-
-  const start = alertDate.clone().subtract(2, 'days').unix();
-  const end = alertDate.clone().add(2, 'days').unix();
-
-  assistant.log(`Fallback: searching Stripe invoices: amount=${amountCents} cents, range=${moment.unix(start).format('YYYY-MM-DD')} to ${moment.unix(end).format('YYYY-MM-DD')}`);
-
-  // Search invoices by date range and amount
-  const invoices = await stripe.invoices.search({
-    limit: 100,
-    query: `created>${start} AND created<${end} AND total:${amountCents}`,
-    expand: ['data.payment_intent.payment_method'],
-  });
-
-  if (!invoices.data.length) {
-    assistant.log(`No invoices found for amount=${amountCents} in date range`);
-    return null;
-  }
-
-  if (invoices.data.length >= 100) {
-    assistant.log(`Warning: 100+ invoices found, results may be truncated`);
-  }
-
-  assistant.log(`Found ${invoices.data.length} invoice(s), matching card last4=${alert.card.last4}`);
-
-  // Loop through invoices and match card last4
-  for (const invoice of invoices.data) {
-    const invoiceLast4 = invoice?.payment_intent?.payment_method?.card?.last4;
-
-    assistant.log(`Checking invoice ${invoice.id}: card last4=${invoiceLast4 || 'unknown'}`);
-
-    if (!invoiceLast4 || invoiceLast4 !== alert.card.last4) {
-      continue;
-    }
-
-    assistant.log(`Matched invoice ${invoice.id}: card last4=${invoiceLast4}`);
-
-    // Resolve UID from customer metadata
-    let uid = null;
-    let email = null;
-    const customerId = invoice.customer;
-    if (customerId) {
-      try {
-        const customer = await stripe.customers.retrieve(customerId);
-        uid = customer.metadata?.uid || null;
-        email = customer.email || null;
-      } catch (e) {
-        assistant.error(`Failed to retrieve customer ${customerId}: ${e.message}`);
-      }
-    }
-
-    return {
-      method: 'invoice-search',
-      invoiceId: invoice.id,
-      subscriptionId: invoice.subscription || null,
-      customerId: customerId,
-      uid: uid,
-      email: email,
-      chargeId: invoice.charge || null,
-    };
-  }
-
-  assistant.log(`No invoice matched card last4=${alert.card.last4}`);
-  return null;
-}
-
-/**
- * Process refund + cancellation for a matched dispute
- *
- * @param {object} options
- * @param {object} options.match - Match details from searchAndMatch
- * @param {object} options.alert - Normalized alert data
- * @param {object} options.assistant - Assistant instance
- * @returns {object} Result with statuses
- */
-async function processDispute({ match, alert, assistant }) {
-  const StripeLib = require('../../../libraries/payment/processors/stripe.js');
-  const stripe = StripeLib.init();
-
-  const amountCents = Math.round(alert.amount * 100);
-  const result = {
-    refundId: null,
-    amountRefunded: null,
-    currency: null,
-    refundStatus: 'skipped',
-    cancelStatus: 'skipped',
-    errors: [],
-  };
-
-  // Issue full refund
-  if (match.chargeId) {
-    try {
-      const refund = await stripe.refunds.create({
-        charge: match.chargeId,
-        amount: amountCents,
-      });
-
-      result.refundId = refund.id;
-      result.amountRefunded = amountCents;
-      result.currency = refund.currency;
-      result.refundStatus = 'success';
-
-      assistant.log(`Refund success: refundId=${refund.id}, amount=${amountCents}, charge=${match.chargeId}`);
-    } catch (e) {
-      result.refundStatus = 'failed';
-      result.errors.push(`Refund failed: ${e.message}`);
-      assistant.error(`Refund failed for charge ${match.chargeId}: ${e.message}`);
-    }
-  }
-
-  // Cancel subscription immediately
-  // Stripe fires customer.subscription.deleted webhook → existing pipeline handles user doc update
-  if (match.subscriptionId) {
-    try {
-      await stripe.subscriptions.cancel(match.subscriptionId);
-      result.cancelStatus = 'success';
-
-      assistant.log(`Subscription cancelled: sub=${match.subscriptionId}`);
-    } catch (e) {
-      result.cancelStatus = 'failed';
-      result.errors.push(`Cancel failed: ${e.message}`);
-      assistant.error(`Cancel failed for sub ${match.subscriptionId}: ${e.message}`);
-    }
-  }
-
-  return result;
-}
-
 /**
  * Send dispute alert email to brand contact (fire-and-forget)
  *

package/src/manager/events/firestore/payments-disputes/processors/stripe.js

@@ -0,0 +1,213 @@
+const moment = require('moment');
+
+const StripeLib = require('../../../../libraries/payment/processors/stripe.js');
+
+/**
+ * Stripe dispute processor
+ *
+ * Implements the dispute processor interface for Stripe:
+ *   - searchAndMatch(alert, assistant) → match | null
+ *   - processDispute(match, alert, assistant) → result
+ *
+ * Match strategy: search charges by amount + date range, then confirm card last4.
+ * If alert.chargeId is provided (alert.updated events), verify it directly — otherwise
+ * fall back to the charge search. Both paths go through the same resolveMatchFromCharge()
+ * so the returned match shape is always identical.
+ *
+ * We use charges.search() rather than invoices.search() because Stripe invoices can have
+ * a null charge field even when paid (payment applied via credit/balance), making invoice
+ * search unreliable. Charges always have payment_method_details.card.last4.
+ */
+
+/**
+ * Find the Stripe charge matching this dispute alert.
+ *
+ * If alert.chargeId is present (Chargeblast alert.updated), verify it directly.
+ * Otherwise search charges by amount + ±2 day window and match card last4.
+ *
+ * @param {object} alert - Normalized alert data
+ * @param {object} assistant - Assistant instance
+ * @returns {object|null} Match details or null
+ */
+async function searchAndMatch(alert, assistant) {
+  const stripe = StripeLib.init();
+
+  // If Chargeblast already gave us the charge ID, verify it directly
+  if (alert.chargeId && alert.chargeId.startsWith('ch_')) {
+    assistant.log(`Direct charge lookup: ${alert.chargeId}`);
+
+    try {
+      const charge = await stripe.charges.retrieve(alert.chargeId, {
+        expand: ['invoice', 'invoice.subscription', 'customer'],
+      });
+      return resolveMatchFromCharge({ charge, stripe, assistant });
+    } catch (e) {
+      assistant.log(`Direct charge lookup failed for ${alert.chargeId}: ${e.message}`);
+    }
+  }
+
+  // Search charges by amount + date range, match card last4
+  const amountCents = Math.round(alert.amount * 100);
+  const alertDate = moment(alert.transactionDate);
+
+  if (!alertDate.isValid()) {
+    throw new Error(`Invalid transactionDate: ${alert.transactionDate}`);
+  }
+
+  const start = alertDate.clone().subtract(2, 'days').unix();
+  const end = alertDate.clone().add(2, 'days').unix();
+
+  assistant.log(`Searching charges: amount=${amountCents} cents, range=${moment.unix(start).format('YYYY-MM-DD')} to ${moment.unix(end).format('YYYY-MM-DD')}, last4=${alert.card.last4}`);
+
+  const charges = await stripe.charges.search({
+    limit: 100,
+    query: `amount:${amountCents} AND created>${start} AND created<${end}`,
+  });
+
+  if (!charges.data.length) {
+    assistant.log(`No charges found for amount=${amountCents} in date range`);
+    return null;
+  }
+
+  if (charges.data.length >= 100) {
+    assistant.log(`Warning: 100+ charges found, results may be truncated`);
+  }
+
+  assistant.log(`Found ${charges.data.length} charge(s), matching last4=${alert.card.last4}`);
+
+  for (const charge of charges.data) {
+    const chargeLast4 = charge.payment_method_details?.card?.last4;
+
+    if (!chargeLast4 || chargeLast4 !== alert.card.last4) {
+      continue;
+    }
+
+    // Fetch full charge with invoice + subscription expanded
+    try {
+      const fullCharge = await stripe.charges.retrieve(charge.id, {
+        expand: ['invoice', 'invoice.subscription', 'customer'],
+      });
+      return resolveMatchFromCharge({ charge: fullCharge, stripe, assistant });
+    } catch (e) {
+      assistant.log(`Failed to expand charge ${charge.id}: ${e.message}`);
+    }
+  }
+
+  assistant.log(`No charge matched last4=${alert.card.last4}`);
+  return null;
+}
+
+/**
+ * Issue a refund and cancel the subscription for a matched dispute.
+ *
+ * @param {object} match - Match details from searchAndMatch
+ * @param {object} alert - Normalized alert data
+ * @param {object} assistant - Assistant instance
+ * @returns {object} Result with statuses
+ */
+async function processDispute(match, alert, assistant) {
+  const stripe = StripeLib.init();
+
+  const amountCents = Math.round(alert.amount * 100);
+  const result = {
+    refundId: null,
+    amountRefunded: null,
+    currency: null,
+    refundStatus: 'skipped',
+    cancelStatus: 'skipped',
+    errors: [],
+  };
+
+  // Issue full refund
+  if (match.chargeId) {
+    try {
+      const refund = await stripe.refunds.create({
+        charge: match.chargeId,
+        amount: amountCents,
+      });
+
+      result.refundId = refund.id;
+      result.amountRefunded = amountCents;
+      result.currency = refund.currency;
+      result.refundStatus = 'success';
+
+      assistant.log(`Refund success: refundId=${refund.id}, amount=${amountCents}, charge=${match.chargeId}`);
+    } catch (e) {
+      result.refundStatus = 'failed';
+      result.errors.push(`Refund failed: ${e.message}`);
+      assistant.error(`Refund failed for charge ${match.chargeId}: ${e.message}`);
+    }
+  }
+
+  // Cancel subscription immediately
+  // Stripe fires customer.subscription.deleted webhook → existing pipeline handles user doc update
+  if (match.subscriptionId) {
+    try {
+      await stripe.subscriptions.cancel(match.subscriptionId);
+      result.cancelStatus = 'success';
+
+      assistant.log(`Subscription cancelled: sub=${match.subscriptionId}`);
+    } catch (e) {
+      result.cancelStatus = 'failed';
+      result.errors.push(`Cancel failed: ${e.message}`);
+      assistant.error(`Cancel failed for sub ${match.subscriptionId}: ${e.message}`);
+    }
+  }
+
+  return result;
+}
+
+module.exports = { searchAndMatch, processDispute };
+
+// ---
+
+/**
+ * Build a match object from a Stripe charge (with invoice + subscription already expanded).
+ *
+ * @param {object} options.charge - Stripe charge with invoice + customer expanded
+ * @param {object} options.stripe - Stripe SDK instance
+ * @param {object} options.assistant - Assistant instance
+ * @returns {object|null}
+ */
+async function resolveMatchFromCharge({ charge, stripe, assistant }) {
+  if (!charge || charge.status !== 'succeeded') {
+    assistant.log(`Charge ${charge?.id} status=${charge?.status}, skipping`);
+    return null;
+  }
+
+  // Resolve UID + email from customer
+  let uid = null;
+  let email = null;
+  const customerId = typeof charge.customer === 'string' ? charge.customer : charge.customer?.id;
+
+  if (charge.customer && typeof charge.customer === 'object') {
+    uid = charge.customer.metadata?.uid || null;
+    email = charge.customer.email || null;
+  } else if (customerId) {
+    try {
+      const customer = await stripe.customers.retrieve(customerId);
+      uid = customer.metadata?.uid || null;
+      email = customer.email || null;
+    } catch (e) {
+      assistant.error(`Failed to retrieve customer ${customerId}: ${e.message}`);
+    }
+  }
+
+  // Resolve invoice + subscription from expanded invoice
+  const invoice = typeof charge.invoice === 'object' ? charge.invoice : null;
+  const invoiceId = invoice?.id || (typeof charge.invoice === 'string' ? charge.invoice : null);
+  const subscriptionId = invoice?.subscription
+    ? (typeof invoice.subscription === 'object' ? invoice.subscription.id : invoice.subscription)
+    : null;
+
+  assistant.log(`Matched charge=${charge.id}, customer=${customerId}, uid=${uid}, invoice=${invoiceId}, subscription=${subscriptionId}`);
+
+  return {
+    chargeId: charge.id,
+    invoiceId: invoiceId,
+    subscriptionId: subscriptionId,
+    customerId: customerId,
+    uid: uid,
+    email: email,
+  };
+}

package/src/manager/routes/payments/dispute-alert/processors/chargeblast.js

@@ -14,7 +14,7 @@ module.exports = {
    * @returns {object} Normalized dispute alert
    */
   normalize(body) {
-    if (!body.id) {
+    if (!body.id && !body.alertId) {
       throw new Error('Missing required field: id');
     }
     if (!body.card) {
@@ -30,7 +30,7 @@ module.exports = {
     const cardStr = String(body.card);
 
     return {
-      id: String(body.id),
+      id: String(body.id || body.alertId),
       card: {
         last4: cardStr.slice(-4),
         brand: body.cardBrand ? String(body.cardBrand).toLowerCase() : null,

package/test/routes/payments/dispute-alert.js

@@ -115,6 +115,14 @@ module.exports = {
           amount: 29.99,
           transactionDate: '2026-03-07 14:30:00',
           processor: 'stripe',
+          alertType: 'FRAUD',
+          customerEmail: 'test@example.com',
+          externalOrder: 'ch_test123',
+          metadata: 'pi_test456',
+          externalUrl: 'https://dashboard.stripe.com/charges/ch_test123',
+          reasonCode: 'WIP',
+          subprovider: 'Ethoca',
+          isRefunded: false,
         });
 
         assert.isSuccess(response, 'Should accept valid Chargeblast alert');
@@ -129,13 +137,23 @@ module.exports = {
           'Status should be pending or processing',
         );
 
-        // Verify normalized alert data
+        // Verify core normalized alert data
         assert.equal(doc.alert.card.last4, '4242', 'Should extract last4 from full card number');
         assert.equal(doc.alert.card.brand, 'visa', 'Should lowercase card brand');
         assert.equal(doc.alert.amount, 29.99, 'Amount should be preserved');
         assert.equal(doc.alert.transactionDate, '2026-03-07', 'Should extract date without time');
         assert.equal(doc.alert.processor, 'stripe', 'Processor should be stripe');
 
+        // Verify new normalized fields
+        assert.equal(doc.alert.alertType, 'FRAUD', 'Alert type should be preserved');
+        assert.equal(doc.alert.customerEmail, 'test@example.com', 'Customer email should be preserved');
+        assert.equal(doc.alert.chargeId, 'ch_test123', 'Charge ID should be extracted from externalOrder');
+        assert.equal(doc.alert.paymentIntentId, 'pi_test456', 'Payment intent ID should be extracted from metadata');
+        assert.equal(doc.alert.stripeUrl, 'https://dashboard.stripe.com/charges/ch_test123', 'Stripe URL should be preserved');
+        assert.equal(doc.alert.reasonCode, 'WIP', 'Reason code should be preserved');
+        assert.equal(doc.alert.subprovider, 'Ethoca', 'Subprovider should be preserved');
+        assert.equal(doc.alert.isRefunded, false, 'isRefunded should be preserved');
+
         // Verify raw payload is preserved
         assert.ok(doc.raw, 'Raw payload should be preserved');
         assert.equal(doc.raw.id, alertId, 'Raw id should match');
@@ -145,6 +163,73 @@ module.exports = {
       },
     },
 
+    {
+      name: 'accepts-alert-with-alertId-field',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-alertid-field';
+
+        // Clean up any existing doc
+        await firestore.delete(`payments-disputes/${alertId}`);
+
+        // Chargeblast alert.created events use alertId instead of id
+        const response = await http.as('none').post(`payments/dispute-alert?key=${process.env.BACKEND_MANAGER_KEY}`, {
+          alertId: alertId,
+          card: '546616******5805',
+          cardBrand: 'Mastercard',
+          amount: 8,
+          transactionDate: '2026-03-19 00:00:00.000000Z',
+        });
+
+        assert.isSuccess(response, 'Should accept alert using alertId field');
+
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.ok(doc, 'Dispute doc should exist in Firestore');
+        assert.equal(doc.id, alertId, 'Doc ID should match alertId');
+        assert.equal(doc.alert.id, alertId, 'Alert id should be set from alertId');
+        assert.equal(doc.alert.card.last4, '5805', 'Should extract last4 from masked card');
+
+        // Clean up
+        await firestore.delete(`payments-disputes/${alertId}`);
+      },
+    },
+
+    {
+      name: 'accepts-alert-without-optional-fields',
+      auth: 'none',
+      async run({ http, assert, firestore }) {
+        const alertId = '_test-dispute-minimal';
+
+        // Clean up any existing doc
+        await firestore.delete(`payments-disputes/${alertId}`);
+
+        // Send minimal alert (alert.created shape — no externalOrder, metadata, etc.)
+        const response = await http.as('none').post(`payments/dispute-alert?key=${process.env.BACKEND_MANAGER_KEY}`, {
+          id: alertId,
+          card: '9124',
+          amount: 10,
+          transactionDate: '2026-03-21 00:01:02',
+        });
+
+        assert.isSuccess(response, 'Should accept minimal alert');
+
+        const doc = await firestore.get(`payments-disputes/${alertId}`);
+        assert.equal(doc.alert.card.last4, '9124', 'Should use card as last4');
+        assert.equal(doc.alert.processor, 'stripe', 'Processor should default to stripe');
+        assert.equal(doc.alert.chargeId, null, 'Charge ID should be null when not provided');
+        assert.equal(doc.alert.paymentIntentId, null, 'Payment intent should be null when not provided');
+        assert.equal(doc.alert.customerEmail, null, 'Customer email should be null when not provided');
+        assert.equal(doc.alert.alertType, null, 'Alert type should be null when not provided');
+        assert.equal(doc.alert.stripeUrl, null, 'Stripe URL should be null when not provided');
+        assert.equal(doc.alert.reasonCode, null, 'Reason code should be null when not provided');
+        assert.equal(doc.alert.subprovider, null, 'Subprovider should be null when not provided');
+        assert.equal(doc.alert.isRefunded, false, 'isRefunded should default to false');
+
+        // Clean up
+        await firestore.delete(`payments-disputes/${alertId}`);
+      },
+    },
+
     {
       name: 'accepts-alert-with-last4-only',
       auth: 'none',
@@ -242,7 +327,7 @@ module.exports = {
     },
 
     {
-      name: 'defaults-alerts-to-chargeblast',
+      name: 'defaults-provider-to-chargeblast',
       auth: 'none',
       async run({ http, assert, firestore }) {
         const alertId = '_test-dispute-default-provider';
@@ -250,7 +335,7 @@ module.exports = {
         // Clean up any existing doc
         await firestore.delete(`payments-disputes/${alertId}`);
 
-        // Send without alerts query param
+        // Send without provider query param
         const response = await http.as('none').post(`payments/dispute-alert?key=${process.env.BACKEND_MANAGER_KEY}`, {
           id: alertId,
           card: '4242',
@@ -258,7 +343,7 @@ module.exports = {
           transactionDate: '2026-01-15',
         });
 
-        assert.isSuccess(response, 'Should accept without explicit alerts param');
+        assert.isSuccess(response, 'Should accept without explicit provider param');
 
         const doc = await firestore.get(`payments-disputes/${alertId}`);
         assert.equal(doc.provider, 'chargeblast', 'Provider should default to chargeblast');