payload-billing/dev/DEMO_GUIDE.md

Demo Project Quick Start Guide

This guide will help you quickly get started with the billing plugin demo.

🚀 Quick Start

1. Install dependencies (if not already done):

   pnpm install
   

2. Start the development server:

   pnpm dev
   

3. Access the demo:

   • Open http://localhost:3000
   • Login with dev@payloadcms.com / test if prompted

🎯 What's Included

Custom Test Payment UI

A beautiful, modern payment interface built with React and Tailwind CSS that demonstrates:

• Payment method selection (iDEAL, Credit Card, PayPal, Apple Pay, Bank Transfer)
• Test scenario selection (success, failure, cancellation, etc.)
• Real-time payment status updates
• Test mode indicators and warnings
• Responsive design

Location: /dev/app/test-payment/[id]/page.tsx

Interactive Demo Page

A landing page that showcases the plugin features and allows you to:

• Create test payments with one click
• Navigate to custom payment UI
• Access admin collections
• Learn about the plugin features

Location: /dev/app/page.tsx

Customer Management

Full customer collection with:

• Name, email, phone, company
• Tax ID support
• Complete address fields
• Auto-sync with invoices via customerInfoExtractor

Location: Configured in /dev/payload.config.ts

Sample Data

Comprehensive seed data including:

• 2 sample customers
• 2 invoices (1 paid, 1 open)
• 4 payments (various statuses)
• 1 refund

Location: /dev/seed.ts

Custom API Routes

Demo API endpoint for creating payments:

• POST /api/demo/create-payment

Location: /dev/app/api/demo/create-payment/route.ts

🧪 Testing the Flow

Complete Payment Flow Test

1. Go to the demo page: http://localhost:3000

2. Click "Create Demo Payment" - This creates a test payment

3. Click "Go to Payment Page" - Opens the custom payment UI

4. Select a payment method - Choose any method (e.g., Credit Card)

5. Select a test scenario - Try different scenarios:

   • Instant Success: See immediate payment success
   • Delayed Success: See processing indicator, then success
   • Declined Payment: See failure handling
   • Cancelled Payment: See cancellation flow

6. Click "Process Test Payment" - Watch the payment process

7. View in admin - After success, you'll be redirected to the payments list

Testing with Different Scenarios

Each scenario simulates a different payment outcome:

Scenario	Delay	Outcome	Use Case
Instant Success	0ms	Success	Testing happy path
Delayed Success	3s	Success	Testing async processing
Cancelled Payment	1s	Cancelled	Testing user cancellation
Declined Payment	2s	Failed	Testing payment failures
Expired Payment	5s	Cancelled	Testing timeout handling
Pending Payment	1.5s	Pending	Testing long-running payments

📊 Viewing Data

Admin Collections

After running the demo, explore the seeded data:

1. Payments (http://localhost:3000/admin/collections/payments)

   • View all payment transactions
   • See payment statuses and provider data
   • Check linked invoices

2. Invoices (http://localhost:3000/admin/collections/invoices)

   • View generated invoices
   • See line items and totals
   • Check customer relationships

3. Refunds (http://localhost:3000/admin/collections/refunds)

   • View processed refunds
   • See refund amounts and reasons

4. Customers (http://localhost:3000/admin/collections/customers)

   • View customer information
   • Edit customer details (invoices will auto-update!)

🔧 Configuration Highlights

Plugin Configuration

billingPlugin({
  providers: [
    testProvider({
      enabled: true,
      customUiRoute: '/test-payment', // Custom UI route
      testModeIndicators: {
        showWarningBanners: true,
        showTestBadges: true,
        consoleWarnings: true
      }
    })
  ],
  collections: {
    payments: 'payments',
    invoices: 'invoices',
    refunds: 'refunds',
  },
  customerRelationSlug: 'customers',
  customerInfoExtractor: (customer) => ({
    // Auto-extract customer info for invoices
    name: customer.name,
    email: customer.email,
    // ... more fields
  }),
})

🎨 Customization Ideas

1. Modify the Payment UI

Edit /dev/app/test-payment/[id]/page.tsx to:

• Change colors and styling
• Add your brand logo
• Modify the layout
• Add additional fields

2. Add More Test Scenarios

Edit testProvider config to add custom scenarios:

testProvider({
  scenarios: [
    {
      id: 'custom-scenario',
      name: 'Custom Scenario',
      description: 'Your custom test scenario',
      outcome: 'paid',
      delay: 2000
    }
  ]
})

3. Create Invoice Templates

Add invoice generation endpoints that use specific templates

4. Add Webhooks

Create webhook handlers to process real payment events

💡 Tips

• Reset Data: Delete dev/payload.sqlite and restart to re-seed
• Check Console: Test provider logs all events to the console
• Test Mode Warnings: Notice the warning banners and badges in test mode
• Auto-sync: Edit a customer's info and see invoices update automatically

🐛 Troubleshooting

Payment not processing?

• Check browser console for errors
• Check server console for logs
• Verify the test provider is enabled in config

Custom UI not loading?

• Check that customUiRoute matches your page route
• Verify the payment ID is valid (starts with test_pay_)

Types not matching?

Run pnpm dev:generate-types to regenerate Payload types

📚 Next Steps

1. Explore the Admin - Login and browse the collections
2. Create Custom Invoices - Try creating invoices with line items
3. Process Refunds - Create refunds for successful payments
4. Add Real Providers - Configure Stripe or Mollie (see README.md)
5. Build Your Integration - Use this as a template for your app

🎓 Learning Resources

• Review /dev/seed.ts for data structure examples
• Check /dev/payload.config.ts for plugin configuration
• See /dev/app/test-payment/[id]/page.tsx for UI integration
• Read the main README.md for API documentation

Happy testing! 🚀