fix: fetch payment sessions from database for persistence

The test provider was using an in-memory Map to store payment sessions,
which caused "Payment session not found" errors in several scenarios:

1. Next.js hot reload clearing the memory
2. Different execution contexts (API routes vs Payload admin)
3. Server restarts losing all sessions

This fix updates all three test provider endpoints (UI, process, status)
to fetch payment data from the database when not found in memory:

- Tries in-memory session first (fast path)
- Falls back to database query by providerId
- Creates and caches session from database payment
- Handles both string and object collection configurations

This makes the built-in test UI work reliably out of the box, without
requiring users to implement custom session management.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -111,9 +111,9 @@ const payment = await payload.create({
 
 **What you get back:**
 
-- **Stripe**: `providerId` = PaymentIntent ID, `providerData.raw.client_secret` for Stripe.js
-- **Mollie**: `providerId` = Transaction ID, `providerData.raw._links.checkout.href` for redirect URL
-- **Test**: `providerId` = Test payment ID, `providerData.raw.paymentUrl` for interactive test UI
+- **Stripe**: `providerId` = PaymentIntent ID, use `providerData.raw.client_secret` with Stripe.js on frontend
+- **Mollie**: `providerId` = Transaction ID, redirect user to `checkoutUrl` to complete payment
+- **Test**: `providerId` = Test payment ID, navigate to `checkoutUrl` for interactive test UI
 
 ## Payment Providers
 
@@ -407,6 +407,7 @@ Tracks payment transactions with provider integration.
   amount: number                        // Amount in cents
   currency: string                      // ISO 4217 currency code
   description?: string
+  checkoutUrl?: string                  // Checkout URL (if applicable)
   invoice?: Invoice | string            // Linked invoice
   metadata?: Record<string, any>        // Custom metadata
   providerData?: ProviderData           // Raw provider response (read-only)
@@ -639,12 +640,14 @@ const payment = await payload.create({
   }
 })
 
-// Get client secret for Stripe.js
+// Get client secret for Stripe.js (Stripe doesn't use checkoutUrl)
 const clientSecret = payment.providerData.raw.client_secret
 
 // Frontend: Confirm payment with Stripe.js
 // const stripe = Stripe('pk_...')
 // await stripe.confirmCardPayment(clientSecret, { ... })
+
+// For Mollie/Test: redirect to payment.checkoutUrl instead
 ```
 
 ### Creating an Invoice with Line Items

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/payload-billing",
-  "version": "0.1.15",
+  "version": "0.1.21",
   "description": "PayloadCMS plugin for billing and payment provider integrations with tracking and local testing",
   "license": "MIT",
   "type": "module",

src/collections/hooks.ts

@@ -7,7 +7,8 @@ export const initProviderPayment = async (payload: Payload, payment: Partial<Pay
 
   if (!billing) {
     throw new Error(
-      'Billing plugin not initialized. Make sure the billingPlugin is properly configured in your Payload config and that Payload has finished initializing.'
+      'Billing plugin not initialized. Make sure the billingPlugin is properly configured in your Payload config and that Payload has finished initializing. ' +
+      'If you are calling this from a Next.js API route or Server Component, ensure you are using getPayload() with the same config instance used in your Payload configuration.'
     )
   }
 

src/collections/payments.ts

@@ -78,6 +78,14 @@ export function createPaymentsCollection(pluginConfig: BillingPluginConfig): Col
         description: 'Payment description',
       },
     },
+    {
+      name: 'checkoutUrl',
+      type: 'text',
+      admin: {
+        description: 'Checkout URL where user can complete payment (if applicable)',
+        readOnly: true,
+      },
+    },
     {
       name: 'invoice',
       type: 'relationship',
@@ -136,6 +144,18 @@ export function createPaymentsCollection(pluginConfig: BillingPluginConfig): Col
       useAsTitle: 'id',
     },
     fields,
+    defaultPopulate: {
+      id: true,
+      provider: true,
+      status: true,
+      amount: true,
+      currency: true,
+      description: true,
+      checkoutUrl: true,
+      providerId: true,
+      metadata: true,
+      providerData: true,
+    },
     hooks: {
       afterChange: [
         async ({ doc, operation, req, previousDoc }) => {

src/plugin/index.ts

@@ -4,7 +4,7 @@ import type { Config, Payload } from 'payload'
 import { createSingleton } from './singleton'
 import type { PaymentProvider } from '../providers/index'
 
-const singleton = createSingleton(Symbol('billingPlugin'))
+const singleton = createSingleton(Symbol.for('@xtr-dev/payload-billing'))
 
 type BillingPlugin = {
   config: BillingPluginConfig

src/plugin/types/payments.ts

@@ -22,6 +22,10 @@ export interface Payment {
    * Payment description
    */
   description?: string | null;
+  /**
+   * Checkout URL where user can complete payment (if applicable)
+   */
+  checkoutUrl?: string | null;
   invoice?: (Id | null) | Invoice;
   /**
    * Additional metadata for the payment

src/providers/mollie.ts

@@ -14,7 +14,7 @@ import {
 import { formatAmountForProvider, isValidAmount, isValidCurrencyCode } from './currency'
 import { createContextLogger } from '../utils/logger'
 
-const symbol = Symbol('mollie')
+const symbol = Symbol.for('@xtr-dev/payload-billing/mollie')
 export type MollieProviderConfig = Parameters<typeof createMollieClient>[0]
 
 /**
@@ -155,6 +155,7 @@ export const mollieProvider = (mollieConfig: MollieProviderConfig & {
       });
       payment.providerId = molliePayment.id
       payment.providerData = molliePayment.toPlainObject()
+      payment.checkoutUrl = molliePayment._links?.checkout?.href || null
       return payment
     },
   } satisfies PaymentProvider

src/providers/stripe.ts

@@ -14,7 +14,7 @@ import {
 import { isValidAmount, isValidCurrencyCode } from './currency'
 import { createContextLogger } from '../utils/logger'
 
-const symbol = Symbol('stripe')
+const symbol = Symbol.for('@xtr-dev/payload-billing/stripe')
 
 export interface StripeProviderConfig {
   secretKey: string

src/providers/test.ts

@@ -6,7 +6,7 @@ import { handleWebhookError, logWebhookEvent } from './utils'
 import { isValidAmount, isValidCurrencyCode } from './currency'
 import { createContextLogger } from '../utils/logger'
 
-const TestModeWarningSymbol = Symbol('TestModeWarning')
+const TestModeWarningSymbol = Symbol.for('@xtr-dev/payload-billing/test-mode-warning')
 const hasGivenTestModeWarning = () => TestModeWarningSymbol in globalThis
 const setTestModeWarning = () => ((<any>globalThis)[TestModeWarningSymbol] = true)
 
@@ -242,10 +242,15 @@ export const testProvider = (testConfig: TestProviderConfig) => {
         {
           path: '/payload-billing/test/payment/:id',
           method: 'get',
-          handler: (req) => {
+          handler: async (req) => {
             // Extract payment ID from URL path
             const urlParts = req.url?.split('/') || []
-            const paymentId = urlParts[urlParts.length - 1]
+            let paymentId = urlParts[urlParts.length - 1]
+
+            // Remove query parameters if present
+            if (paymentId?.includes('?')) {
+              paymentId = paymentId.split('?')[0]
+            }
 
             if (!paymentId) {
               return new Response(JSON.stringify({ error: 'Payment ID required' }), {
@@ -263,7 +268,41 @@ export const testProvider = (testConfig: TestProviderConfig) => {
               })
             }
 
-            const session = testPaymentSessions.get(paymentId)
+            // Try to get session from memory first (for backward compatibility)
+            let session = testPaymentSessions.get(paymentId)
+
+            // If not in memory, fetch from database
+            if (!session && req.payload) {
+              try {
+                const paymentsConfig = pluginConfig.collections?.payments
+                const paymentSlug = typeof paymentsConfig === 'string' ? paymentsConfig : (paymentsConfig?.slug || 'payments')
+                const result = await req.payload.find({
+                  collection: paymentSlug,
+                  where: {
+                    providerId: {
+                      equals: paymentId
+                    }
+                  },
+                  limit: 1
+                })
+
+                if (result.docs && result.docs.length > 0) {
+                  const payment = result.docs[0] as Payment
+                  // Create session from database payment
+                  session = {
+                    id: paymentId,
+                    payment: payment,
+                    createdAt: new Date(payment.createdAt || Date.now()),
+                    status: 'pending' as PaymentOutcome
+                  }
+                  // Store in memory for future requests
+                  testPaymentSessions.set(paymentId, session)
+                }
+              } catch (error) {
+                console.error('Error fetching payment from database:', error)
+              }
+            }
+
             if (!session) {
               return new Response(JSON.stringify({ error: 'Payment session not found' }), {
                 status: 404,
@@ -322,7 +361,41 @@ export const testProvider = (testConfig: TestProviderConfig) => {
 
               const { paymentId, scenarioId, method } = validation.data!
 
-              const session = testPaymentSessions.get(paymentId)
+              // Try to get session from memory first
+              let session = testPaymentSessions.get(paymentId)
+
+              // If not in memory, fetch from database
+              if (!session && req.payload) {
+                try {
+                  const paymentsConfig = pluginConfig.collections?.payments
+                const paymentSlug = typeof paymentsConfig === 'string' ? paymentsConfig : (paymentsConfig?.slug || 'payments')
+                  const result = await req.payload.find({
+                    collection: paymentSlug,
+                    where: {
+                      providerId: {
+                        equals: paymentId
+                      }
+                    },
+                    limit: 1
+                  })
+
+                  if (result.docs && result.docs.length > 0) {
+                    const payment = result.docs[0] as Payment
+                    // Create session from database payment
+                    session = {
+                      id: paymentId,
+                      payment: payment,
+                      createdAt: new Date(payment.createdAt || Date.now()),
+                      status: 'pending' as PaymentOutcome
+                    }
+                    // Store in memory for future requests
+                    testPaymentSessions.set(paymentId, session)
+                  }
+                } catch (error) {
+                  console.error('Error fetching payment from database:', error)
+                }
+              }
+
               if (!session) {
                 return new Response(JSON.stringify({ error: 'Payment session not found' }), {
                   status: 404,
@@ -398,10 +471,15 @@ export const testProvider = (testConfig: TestProviderConfig) => {
         {
           path: '/payload-billing/test/status/:id',
           method: 'get',
-          handler: (req) => {
+          handler: async (req) => {
             // Extract payment ID from URL path
             const urlParts = req.url?.split('/') || []
-            const paymentId = urlParts[urlParts.length - 1]
+            let paymentId = urlParts[urlParts.length - 1]
+
+            // Remove query parameters if present
+            if (paymentId?.includes('?')) {
+              paymentId = paymentId.split('?')[0]
+            }
 
             if (!paymentId) {
               return new Response(JSON.stringify({ error: 'Payment ID required' }), {
@@ -419,7 +497,41 @@ export const testProvider = (testConfig: TestProviderConfig) => {
               })
             }
 
-            const session = testPaymentSessions.get(paymentId)
+            // Try to get session from memory first
+            let session = testPaymentSessions.get(paymentId)
+
+            // If not in memory, fetch from database
+            if (!session && req.payload) {
+              try {
+                const paymentsConfig = pluginConfig.collections?.payments
+                const paymentSlug = typeof paymentsConfig === 'string' ? paymentsConfig : (paymentsConfig?.slug || 'payments')
+                const result = await req.payload.find({
+                  collection: paymentSlug,
+                  where: {
+                    providerId: {
+                      equals: paymentId
+                    }
+                  },
+                  limit: 1
+                })
+
+                if (result.docs && result.docs.length > 0) {
+                  const payment = result.docs[0] as Payment
+                  // Create session from database payment
+                  session = {
+                    id: paymentId,
+                    payment: payment,
+                    createdAt: new Date(payment.createdAt || Date.now()),
+                    status: 'pending' as PaymentOutcome
+                  }
+                  // Store in memory for future requests
+                  testPaymentSessions.set(paymentId, session)
+                }
+              } catch (error) {
+                console.error('Error fetching payment from database:', error)
+              }
+            }
+
             if (!session) {
               return new Response(JSON.stringify({ error: 'Payment session not found' }), {
                 status: 404,
@@ -492,6 +604,10 @@ export const testProvider = (testConfig: TestProviderConfig) => {
 
       // Set provider ID and data
       payment.providerId = testPaymentId
+      // Use custom UI route if specified, otherwise use built-in UI endpoint
+      const paymentUrl = testConfig.customUiRoute
+        ? `${baseUrl}${testConfig.customUiRoute}/${testPaymentId}`
+        : `${baseUrl}/api/payload-billing/test/payment/${testPaymentId}`
       const providerData: ProviderData = {
         raw: {
           id: testPaymentId,
@@ -500,7 +616,7 @@ export const testProvider = (testConfig: TestProviderConfig) => {
           description: payment.description,
           status: 'pending',
           testMode: true,
-          paymentUrl: `${baseUrl}/api/payload-billing/test/payment/${testPaymentId}`,
+          paymentUrl,
           scenarios: scenarios.map(s => ({ id: s.id, name: s.name, description: s.description })),
           methods: Object.entries(PAYMENT_METHODS).map(([key, value]) => ({
             id: key,
@@ -512,6 +628,7 @@ export const testProvider = (testConfig: TestProviderConfig) => {
         provider: 'test'
       }
       payment.providerData = providerData
+      payment.checkoutUrl = paymentUrl
 
       return payment
     },