@omega.js/backend 0.1.0

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

@@ -0,0 +1,157 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const powertools = require('node-powertools');
+const safeCompare = require('../../../helpers/safe-compare.js');
+const env = require('../../../libraries/env.js');
+
+/**
+ * POST /payments/webhook?provider=stripe&key=XXX
+ * Receives payment provider webhooks, validates them, and saves to Firestore
+ * The Firestore onWrite trigger handles async processing
+ *
+ * This handler is provider-agnostic. Each provider module defines:
+ *   - parseWebhook(req) — extracts { eventId, eventType, category, resourceType, resourceId, chargeId, refundId, raw, uid }
+ *   - isSupported(eventType) — returns true for events we should process
+ */
+module.exports = async ({ ctx, Manager, libraries }) => {
+  const { admin } = libraries;
+  const data = ctx.request.data;
+  const query = ctx.request.query;
+
+  // Get provider and key from query params
+  const provider = query.provider;
+  const key = query.key;
+
+  // Validate provider
+  if (!provider) {
+    return ctx.respond('Missing provider parameter', { code: 400 });
+  }
+
+  // Validate key
+  if (!safeCompare(key, env.get('OMEGA_WEBHOOK_KEY'))) {
+    return ctx.respond('Invalid key', { code: 401 });
+  }
+
+  // Guard: test provider is not available in production
+  // (mirrors the intent side's guard — the webhook providers receive only the raw
+  // req, so the dispatch layer is where this side has a ctx to ask)
+  if (provider === 'test' && ctx.isProduction()) {
+    return ctx.respond('Test provider is not available in production', { code: 403 });
+  }
+
+  // Validate brand — quit if a brand is specified and doesn't match ours
+  const brand = query.brand;
+  const ourBrand = Manager.config.brand?.id;
+  if (brand && ourBrand && brand !== ourBrand) {
+    ctx.log(`Ignoring webhook: explicit brand mismatch (received=${brand}, expected=${ourBrand})`);
+    return ctx.respond({ received: true, ignored: true });
+  }
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // Parse the webhook using the provider
+  let parsed;
+  try {
+    parsed = providerModule.parseWebhook(ctx.ref.req);
+  } catch (e) {
+    return ctx.respond(`Failed to parse webhook: ${e.message}`, { code: 400 });
+  }
+
+  const { eventId, eventType, category, resourceType, resourceId, chargeId, refundId, raw, uid } = parsed;
+
+  ctx.log(`Parsed webhook: eventId=${eventId}, eventType=${eventType}, category=${category || 'null'}, resourceType=${resourceType || 'null'}, uid=${uid || 'null'}, api_version=${raw?.api_version || 'unknown'}`);
+
+  // Let the provider decide if this event type is relevant
+  if (providerModule.isSupported && !providerModule.isSupported(eventType)) {
+    ctx.log(`Ignoring unsupported event type: ${eventType}`);
+    return ctx.respond({ received: true, ignored: true });
+  }
+
+  // Skip events with no category (e.g., checkout.session.completed for subscription mode)
+  if (!category) {
+    ctx.log(`Ignoring event with no category: ${eventType}`);
+    return ctx.respond({ received: true, ignored: true });
+  }
+
+  // Build timestamps
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  // Claim the event, then save — in ONE transaction. Providers retry, and a
+  // retry can arrive while the first delivery is still in flight: a read
+  // followed by a separate write leaves a window where both deliveries see no
+  // doc and both write, so the pipeline runs the same event twice. The
+  // transaction's read locks the document, so exactly one delivery claims it
+  // and the other is told it is a duplicate ([#212]).
+  const docRef = admin.firestore().doc(`payments-webhooks/${eventId}`);
+  const claimed = await admin.firestore().runTransaction(async (transaction) => {
+    const existingDoc = await transaction.get(docRef);
+
+    if (existingDoc.exists) {
+      const existingStatus = existingDoc.data()?.status;
+
+      // A failed webhook is the one state that may be reclaimed — that IS the retry path
+      if (existingStatus !== 'failed') {
+        return { claimed: false, status: existingStatus };
+      }
+    }
+
+    // Save with status=pending (trigger handles the rest)
+    transaction.set(docRef, {
+      id: eventId,
+      provider: provider,
+      status: 'pending',
+      raw: raw,
+      owner: uid,
+      event: {
+        type: eventType,
+        category: category,
+        resourceType: resourceType,
+        resourceId: resourceId,
+        // THIS charge's own id (Stripe/Chargebee invoice, PayPal sale), where a
+        // subscription event names one. The resourceId is the subscription, which
+        // never changes, so only this can key a single charge — and GA4
+        // deduplicates `purchase` on the id it is sent
+        // ([#656](https://github.com/Omega-JS-Stack/omega/issues/656))
+        chargeId: chargeId || null,
+        // The refund's own id, where the parser separates it from the resource the
+        // refund reversed — the key the trigger looks its amounts up by
+        // ([#510](https://github.com/Omega-JS-Stack/omega/issues/510))
+        refundId: refundId || null,
+      },
+      error: null,
+      metadata: {
+        created: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+        completed: {
+          timestamp: null,
+          timestampUNIX: null,
+        },
+      },
+    });
+
+    return { claimed: true, retried: existingDoc.exists };
+  });
+
+  if (!claimed.claimed) {
+    ctx.log(`Duplicate webhook ${eventId}, existing status=${claimed.status}, skipping`);
+    return ctx.respond({ received: true, duplicate: true });
+  }
+
+  if (claimed.retried) {
+    ctx.log(`Retrying previously failed webhook ${eventId}`);
+  }
+
+  ctx.log(`Saved payments-webhooks/${eventId}: eventType=${eventType}, category=${category}, provider=${provider}, uid=${uid}`);
+
+  // Return 200 immediately
+  return ctx.respond({ received: true });
+};

package/dist/manager/routes/payments/webhook/providers/chargebee.js

@@ -0,0 +1,218 @@
+/**
+ * Chargebee webhook provider
+ * Extracts, validates, and categorizes webhook event data from Chargebee
+ *
+ * Chargebee webhook payload structure:
+ * {
+ *   id: "ev_xxx",
+ *   occurred_at: 1234567890,
+ *   event_type: "subscription_created",
+ *   content: { subscription: {...}, customer: {...}, invoice: {...} }
+ * }
+ */
+
+const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+
+// Events we process — mapped to their category
+const SUPPORTED_EVENTS = new Set([
+  // Subscription lifecycle
+  'subscription_created',
+  'subscription_activated',
+  'subscription_changed',
+  'subscription_cancelled',
+  'subscription_reactivated',
+  'subscription_renewed',
+  'subscription_cancellation_scheduled',
+  'subscription_scheduled_cancellation_removed',
+  'subscription_paused',
+  'subscription_resumed',
+
+  // Payment events
+  'payment_succeeded',
+  'payment_failed',
+  'payment_refunded',
+
+  // One-time (non-recurring invoice)
+  'invoice_generated',
+]);
+
+// Events that are always subscription-related
+const SUBSCRIPTION_EVENTS = new Set([
+  'subscription_created',
+  'subscription_activated',
+  'subscription_changed',
+  'subscription_cancelled',
+  'subscription_reactivated',
+  'subscription_renewed',
+  'subscription_cancellation_scheduled',
+  'subscription_scheduled_cancellation_removed',
+  'subscription_paused',
+  'subscription_resumed',
+]);
+
+module.exports = {
+  /**
+   * Returns true if this event type should be saved and processed
+   */
+  isSupported(eventType) {
+    return SUPPORTED_EVENTS.has(eventType);
+  },
+
+  /**
+   * Parse a Chargebee webhook request
+   *
+   * @param {object} req - The raw HTTP request
+   * @returns {object} { eventId, eventType, category, resourceType, resourceId, chargeId, raw, uid }
+   */
+  parseWebhook(req) {
+    const event = req.body;
+
+    // Validate event structure
+    if (!event || !event.id || !event.event_type) {
+      throw new Error('Invalid Chargebee webhook payload');
+    }
+
+    const eventType = event.event_type;
+    const content = event.content || {};
+    const subscription = content.subscription;
+    const invoice = content.invoice;
+    const customer = content.customer;
+
+    let category = null;
+    let resourceType = null;
+    let resourceId = null;
+    let uid = null;
+    // THIS charge's own id — Chargebee's invoice id, which rides the renewal and
+    // refund payloads. The resourceId is the subscription, constant for its whole
+    // life, so it can never key a single charge
+    // ([#656](https://github.com/Omega-JS-Stack/omega/issues/656)). A one-time
+    // purchase has exactly one charge and the order names it.
+    let chargeId = null;
+
+    if (SUBSCRIPTION_EVENTS.has(eventType)) {
+      // Subscription lifecycle events
+      category = 'subscription';
+      resourceType = 'subscription';
+      resourceId = subscription?.id || null;
+      // The RENEWAL's invoice, and only that one. `subscription_created` carries
+      // an invoice too — the checkout's first one (test/fixtures/chargebee/
+      // webhook-subscription-created.json) — but that charge is reported under
+      // the ORDER id, the one id the confirmation page can compute as well
+      // ([#656](https://github.com/Omega-JS-Stack/omega/issues/656)). Naming it
+      // here would have this hand the pipeline a charge id for an event whose
+      // transaction is keyed on the order.
+      chargeId = eventType === 'subscription_renewed' ? (invoice?.id || null) : null;
+      uid = extractUid(subscription, customer);
+
+    } else if (eventType === 'payment_succeeded') {
+      // The paid signal. Note this routes the OPPOSITE way from payment_failed
+      // below on the subscription branch: there, the state diff (active →
+      // suspended) is what names the failure, so the doc has work to do. Here a
+      // renewal's charge is already carried by `subscription_renewed` — the event
+      // the analytics resolver reads as Chargebee's payment — so storing this one
+      // too would book that revenue TWICE, the same double-count Stripe's provider
+      // header documents for `invoice.paid` beside `invoice.payment_succeeded`.
+      if (subscription) {
+        category = null;
+      } else {
+        // A one-time purchase, and the only event that says it was actually PAID.
+        // `invoice_generated` fires for the same purchase but an invoice is born
+        // unpaid, so reading that as the sale would email a receipt to someone who
+        // never paid ([#729](https://github.com/Omega-JS-Stack/omega/issues/729)).
+        category = 'one-time';
+        resourceType = 'invoice';
+        resourceId = invoice?.id || null;
+        uid = extractUid(null, customer);
+      }
+
+    } else if (eventType === 'payment_failed') {
+      // Payment failure — subscription-related if subscription is present
+      if (subscription) {
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = subscription.id;
+        uid = extractUid(subscription, customer);
+      } else {
+        // One-time payment failure
+        category = 'one-time';
+        resourceType = 'invoice';
+        resourceId = invoice?.id || null;
+        uid = extractUid(null, customer);
+      }
+
+    } else if (eventType === 'payment_refunded') {
+      // Refund — subscription-related if subscription is present
+      if (subscription) {
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = subscription.id;
+        // The invoice the reversed charge was paid against ([#656]).
+        chargeId = invoice?.id || null;
+        uid = extractUid(subscription, customer);
+      } else if (invoice) {
+        // No subscription — the refund of a one-time purchase, resolved through
+        // the invoice it refunded, the same one the one-time payment_failed branch
+        // above names. Skipping it meant that refund never entered the pipeline at
+        // all ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+        category = 'one-time';
+        resourceType = 'invoice';
+        resourceId = invoice.id;
+        uid = extractUid(null, customer);
+      } else {
+        // Neither a subscription nor an invoice — nothing names the purchase
+        category = null;
+      }
+
+    } else if (eventType === 'invoice_generated') {
+      // Check if it's a non-recurring invoice (one-time purchase)
+      if (invoice && !invoice.subscription_id) {
+        category = 'one-time';
+        resourceType = 'invoice';
+        resourceId = invoice.id;
+        uid = extractUid(null, customer);
+      } else {
+        // Recurring invoice — skip (subscription events handle this)
+        category = null;
+      }
+    }
+
+    return {
+      eventId: event.id,
+      eventType: eventType,
+      category: category,
+      resourceType: resourceType,
+      resourceId: resourceId,
+      chargeId: chargeId,
+      raw: event,
+      uid: uid,
+    };
+  },
+};
+
+/**
+ * Extract UID from Chargebee subscription meta_data or customer
+ * Tries subscription meta_data first, then customer meta_data, then cf_ fields
+ *
+ * @param {object|null} subscription - Chargebee subscription object
+ * @param {object|null} customer - Chargebee customer object
+ * @returns {string|null}
+ */
+function extractUid(subscription, customer) {
+  // Try subscription meta_data
+  if (subscription) {
+    const uid = ChargebeeLib.getUid(subscription);
+    if (uid) {
+      return uid;
+    }
+  }
+
+  // Try customer meta_data
+  if (customer) {
+    const uid = ChargebeeLib.getUid(customer);
+    if (uid) {
+      return uid;
+    }
+  }
+
+  return null;
+}

package/dist/manager/routes/payments/webhook/providers/coinbase.js

@@ -0,0 +1,91 @@
+/**
+ * Coinbase Commerce webhook provider
+ * Extracts and categorizes webhook event data from Coinbase Commerce
+ *
+ * Coinbase Commerce events: https://docs.cdp.coinbase.com/commerce-onchain/docs/webhooks
+ *
+ * The delivery is authenticated by the ONE `?key=` check every payment webhook
+ * rides (Ian 2026-08-27, with [#634](https://github.com/Omega-JS-Stack/omega/issues/634)).
+ * Coinbase signs its deliveries with an `X-CC-Webhook-Signature` header and this
+ * framework does NOT verify it — there is no per-provider signature layer left
+ * anywhere in the payment system, and the body is trusted for identifiers only:
+ * every value that drives state comes from the charge the pipeline looks up.
+ */
+
+// Events we process, mapped to their category. Every Coinbase Commerce event is
+// about a CHARGE, and a charge is a single payment — there is no subscription,
+// plan or billing agreement in this API at all, so nothing here can ever reach
+// the pipeline's subscription half ([#642](https://github.com/Omega-JS-Stack/omega/issues/642)).
+//
+// The siblings stay OUT, and each for its own reason: `charge:created` is our
+// OWN intent call answering, not a payment, and processing it would write an
+// order for a checkout nobody has paid for; `charge:delayed` and
+// `charge:resolved` are the two halves of the underpaid/overpaid lane, where
+// what the customer gets is a MERCHANT decision — they need that decision
+// specified before an event can act on one, the same rule that keeps PayPal's
+// CAPTURE.REVERSED out of its list.
+const SUPPORTED_EVENTS = new Set([
+  'charge:confirmed',
+  'charge:pending',
+  'charge:failed',
+]);
+
+module.exports = {
+  /**
+   * Returns true if this event type should be saved and processed
+   */
+  isSupported(eventType) {
+    return SUPPORTED_EVENTS.has(eventType);
+  },
+
+  /**
+   * Parse a Coinbase Commerce webhook request
+   * Extracts event data and determines category, resource type, resource ID, and UID
+   *
+   * @param {object} req - The raw HTTP request
+   * @returns {object} { eventId, eventType, category, resourceType, resourceId, chargeId, refundId, raw, uid }
+   */
+  parseWebhook(req) {
+    const body = req.body;
+    const event = body?.event;
+
+    // Validate event structure
+    if (!event || !event.id || !event.type) {
+      throw new Error('Invalid Coinbase Commerce webhook payload');
+    }
+
+    const charge = event.data || {};
+    const eventType = event.type;
+
+    let category = null;
+    let resourceType = null;
+    let resourceId = null;
+    let chargeId = null;
+
+    if (SUPPORTED_EVENTS.has(eventType)) {
+      // Every supported event is a charge event, and a charge is one purchase
+      category = 'one-time';
+      resourceType = 'charge';
+      // The endpoint reads either identifier, and the id is the stable one — a
+      // code is the short human-facing handle on the hosted page
+      resourceId = charge.id || charge.code || null;
+      // A one-time purchase has exactly ONE charge, and this is it: the same id
+      // the money event is deduplicated on ([#656](https://github.com/Omega-JS-Stack/omega/issues/656))
+      chargeId = resourceId;
+    }
+
+    return {
+      eventId: event.id,
+      eventType: eventType,
+      category: category,
+      resourceType: resourceType,
+      resourceId: resourceId,
+      chargeId: chargeId,
+      // Coinbase Commerce has no refund API and publishes no refund event, so no
+      // coinbase delivery is ever about money going back
+      refundId: null,
+      raw: body,
+      uid: charge.metadata?.uid || null,
+    };
+  },
+};

package/dist/manager/routes/payments/webhook/providers/paypal.js

@@ -0,0 +1,214 @@
+/**
+ * PayPal webhook provider
+ * Extracts, validates, and categorizes webhook event data from PayPal
+ *
+ * PayPal webhook events: https://developer.paypal.com/api/rest/webhooks/event-names/
+ */
+
+// Events we process, mapped to their category
+const SUPPORTED_EVENTS = new Set([
+  // Subscription lifecycle
+  'BILLING.SUBSCRIPTION.ACTIVATED',
+  'BILLING.SUBSCRIPTION.UPDATED',
+  'BILLING.SUBSCRIPTION.CANCELLED',
+  'BILLING.SUBSCRIPTION.SUSPENDED',
+  'BILLING.SUBSCRIPTION.EXPIRED',
+  'BILLING.SUBSCRIPTION.RE-ACTIVATED',
+
+  // Payment events (subscription billing)
+  'PAYMENT.SALE.COMPLETED',
+  'PAYMENT.SALE.DENIED',
+  'PAYMENT.SALE.REFUNDED',
+
+  // One-time order events
+  'CHECKOUT.ORDER.APPROVED',
+
+  // v2 capture refunds. One-time purchases this framework creates go through
+  // v2 Orders, and a v2 capture refunds as PAYMENT.CAPTURE.REFUNDED — never the
+  // v1 PAYMENT.SALE.REFUNDED above, so this list used to drop every refund of a
+  // modern PayPal purchase ([#240](https://github.com/Omega-JS-Stack/omega/issues/240)).
+  //
+  // The siblings stay OUT, reviewed with the same issue: CAPTURE.COMPLETED /
+  // PENDING / DENIED describe the capture this framework performs itself inside
+  // fetchResource('order'), so accepting them would process one purchase twice.
+  // CAPTURE.REVERSED is a money-out event like a refund, but nothing here has
+  // ever exercised it — it needs its own payload before it is accepted.
+  'PAYMENT.CAPTURE.REFUNDED',
+]);
+
+module.exports = {
+  /**
+   * Returns true if this event type should be saved and processed
+   */
+  isSupported(eventType) {
+    return SUPPORTED_EVENTS.has(eventType);
+  },
+
+  /**
+   * Parse a PayPal webhook request
+   * Extracts event data and determines category, resource type, resource ID, and UID
+   *
+   * @param {object} req - The raw HTTP request
+   * @returns {object} { eventId, eventType, category, resourceType, resourceId, chargeId, refundId, raw, uid }
+   */
+  parseWebhook(req) {
+    const event = req.body;
+
+    // Validate event structure
+    if (!event || !event.id || !event.event_type) {
+      throw new Error('Invalid PayPal webhook payload');
+    }
+
+    const resource = event.resource || {};
+    const eventType = event.event_type;
+
+    let category = null;
+    let resourceType = null;
+    let resourceId = null;
+    let uid = null;
+    // A refund event's resourceId is reassigned to the sale/capture the refund
+    // reversed, which used to be the last anything saw of the REFUND's own id —
+    // the key its amounts are looked up by
+    // ([#510](https://github.com/Omega-JS-Stack/omega/issues/510)).
+    let refundId = null;
+    // THIS charge's own id — PayPal's sale id, where a subscription event names
+    // one. The resourceId is the billing agreement, constant for the whole
+    // subscription, so it can never key a single charge
+    // ([#656](https://github.com/Omega-JS-Stack/omega/issues/656)). A one-time
+    // purchase has exactly one charge and the order names it.
+    let chargeId = null;
+
+    if (eventType.startsWith('BILLING.SUBSCRIPTION.')) {
+      // Subscription lifecycle events
+      category = 'subscription';
+      resourceType = 'subscription';
+      resourceId = resource.id; // PayPal subscription ID (I-xxx)
+
+      // Parse uid from custom_id
+      uid = parseUidFromCustomId(resource.custom_id);
+
+    } else if (eventType === 'PAYMENT.SALE.COMPLETED' || eventType === 'PAYMENT.SALE.DENIED') {
+      // Payment sale — determine if it's for a subscription
+      const billingAgreementId = resource.billing_agreement_id;
+
+      if (billingAgreementId) {
+        // Subscription payment
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = billingAgreementId; // This is the subscription ID
+        chargeId = resource.id || null; // The sale — one per recurring charge
+
+        uid = parseUidFromCustomId(resource.custom_id);
+      } else {
+        // One-time payment — skip for now (not yet supported)
+        category = null;
+      }
+
+    } else if (eventType === 'CHECKOUT.ORDER.APPROVED') {
+      // One-time order approved by buyer — will be captured in fetchResource
+      category = 'one-time';
+      resourceType = 'order';
+      resourceId = resource.id; // PayPal order ID
+
+      // Parse uid from purchase_units custom_id
+      uid = parseUidFromCustomId(resource.purchase_units?.[0]?.custom_id);
+
+    } else if (eventType === 'PAYMENT.SALE.REFUNDED') {
+      // Refund — linked to a subscription via billing_agreement_id
+      const billingAgreementId = resource.billing_agreement_id;
+
+      if (billingAgreementId) {
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = billingAgreementId;
+        // The sale this refund reversed, so the refund names the same id that
+        // charge was recorded under ([#656]).
+        chargeId = resource.sale_id || null;
+      } else {
+        // No billing agreement behind it — this is the refund of a one-time
+        // purchase, and the sale it reversed is the resource the event carries.
+        // Dropping it (category = null) meant that refund never entered the
+        // pipeline at all — the Stripe twin of this gap
+        // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+        category = 'one-time';
+        resourceType = 'sale';
+        resourceId = resource.sale_id || resource.id;
+      }
+
+      // The v1 refund resource IS the event's own resource — its id is the refund's
+      refundId = resource.id || null;
+
+      uid = parseUidFromCustomId(resource.custom_id);
+
+    } else if (eventType === 'PAYMENT.CAPTURE.REFUNDED') {
+      // The v2 twin of the branch above: a one-time purchase made through v2
+      // Orders refunds as a capture refund. The resource is a v2 Refund, which
+      // names the CAPTURE it reversed through its HATEOAS `up` link — there is
+      // no parent_payment to walk, and the capture reads back at
+      // /v2/payments/captures/{id} carrying our custom_id directly
+      // ([#240](https://github.com/Omega-JS-Stack/omega/issues/240)).
+      category = 'one-time';
+      resourceType = 'capture';
+      resourceId = resource.capture_id || parseCaptureIdFromLinks(resource.links) || resource.id;
+
+      // The v2 Refund resource IS the event's own resource — its id is the refund's
+      refundId = resource.id || null;
+
+      uid = parseUidFromCustomId(resource.custom_id);
+    }
+
+    return {
+      eventId: event.id,
+      eventType: eventType,
+      category: category,
+      resourceType: resourceType,
+      resourceId: resourceId,
+      chargeId: chargeId,
+      refundId: refundId,
+      raw: event,
+      uid: uid,
+    };
+  },
+};
+
+/**
+ * The capture id a v2 Refund's HATEOAS links name.
+ *
+ * PayPal v2 resources point UP at what they came from: a refund's `up` link is
+ * the capture it reversed. Only a link that is actually a captures endpoint
+ * counts — the same `up` rel names the ORDER on other resources.
+ * @param {Array} links - The resource's `links` array
+ * @returns {string|null} The capture id, or null when no link names one
+ */
+function parseCaptureIdFromLinks(links) {
+  for (const link of links || []) {
+    const match = String(link?.href || '').match(/\/v2\/payments\/captures\/([^/?#]+)/);
+
+    if (match) {
+      return match[1];
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse uid from PayPal custom_id format: uid:{uid},orderId:{orderId}
+ * @param {string} customId
+ * @returns {string|null}
+ */
+function parseUidFromCustomId(customId) {
+  if (!customId) {
+    return null;
+  }
+
+  for (const part of customId.split(',')) {
+    const [key, ...valueParts] = part.split(':');
+
+    if (key === 'uid') {
+      return valueParts.join(':') || null;
+    }
+  }
+
+  return null;
+}