mirror of
https://github.com/xtr-dev/payload-billing.git
synced 2025-12-10 02:43:24 +00:00
feat: add comprehensive demo application with custom payment UI
- Custom test payment UI with modern Tailwind CSS design - Payment method selection (iDEAL, Credit Card, PayPal, Apple Pay, Bank Transfer) - Test scenario selection (6 scenarios: success, delayed, cancelled, declined, expired, pending) - Real-time payment status polling - Success and failure result pages with payment details - Interactive demo homepage at root path - Sample data seeding (customers, invoices) - Customers collection with auto-sync to invoices - Comprehensive documentation (README.md, DEMO_GUIDE.md) - Proper cursor styles for all interactive elements 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
350
dev/README.md
Normal file
350
dev/README.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# Billing Plugin Demo Application
|
||||
|
||||
This is a demo application showcasing the `@xtr-dev/payload-billing` plugin for PayloadCMS 3.x.
|
||||
|
||||
## Features
|
||||
|
||||
- 🧪 **Test Payment Provider** with customizable scenarios
|
||||
- 💳 **Payment Management** with full CRUD operations
|
||||
- 🧾 **Invoice Generation** with line items and tax calculation
|
||||
- 👥 **Customer Management** with relationship support
|
||||
- 🔄 **Refund Processing** and tracking
|
||||
- 🎨 **Custom Payment UI** with modern design
|
||||
- 📊 **Sample Data** for quick testing
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### Running the Demo
|
||||
|
||||
```bash
|
||||
# Start the development server
|
||||
pnpm dev
|
||||
|
||||
# The application will be available at http://localhost:3000
|
||||
```
|
||||
|
||||
### Default Credentials
|
||||
|
||||
- **Email**: `dev@payloadcms.com`
|
||||
- **Password**: `test`
|
||||
|
||||
## Demo Routes
|
||||
|
||||
### Interactive Demo Page
|
||||
Visit [http://localhost:3000](http://localhost:3000) to access the interactive demo page where you can:
|
||||
- Create test payments
|
||||
- View the custom payment UI
|
||||
- Test different payment scenarios
|
||||
- Navigate to admin collections
|
||||
|
||||
### Custom Payment UI
|
||||
The custom test payment UI is available at:
|
||||
```
|
||||
http://localhost:3000/test-payment/{payment-id}
|
||||
```
|
||||
|
||||
This page demonstrates:
|
||||
- Modern, responsive payment interface
|
||||
- Payment method selection
|
||||
- Test scenario selection (success, failure, cancellation, etc.)
|
||||
- Real-time payment status updates
|
||||
- Test mode indicators and warnings
|
||||
|
||||
### Admin Routes
|
||||
|
||||
- **Payments**: [http://localhost:3000/admin/collections/payments](http://localhost:3000/admin/collections/payments)
|
||||
- **Invoices**: [http://localhost:3000/admin/collections/invoices](http://localhost:3000/admin/collections/invoices)
|
||||
- **Refunds**: [http://localhost:3000/admin/collections/refunds](http://localhost:3000/admin/collections/refunds)
|
||||
- **Customers**: [http://localhost:3000/admin/collections/customers](http://localhost:3000/admin/collections/customers)
|
||||
|
||||
## Sample Data
|
||||
|
||||
The application includes seed data with:
|
||||
|
||||
- **2 Customers**
|
||||
- John Doe (Acme Corporation)
|
||||
- Jane Smith (Tech Innovations Inc.)
|
||||
|
||||
- **2 Invoices**
|
||||
- Paid invoice with web development services
|
||||
- Open invoice with subscription and additional users
|
||||
|
||||
- **4 Payments**
|
||||
- Successful payment linked to invoice
|
||||
- Pending payment linked to invoice
|
||||
- Standalone successful payment
|
||||
- Failed payment example
|
||||
|
||||
- **1 Refund**
|
||||
- Partial refund on a successful payment
|
||||
|
||||
To reset the sample data:
|
||||
```bash
|
||||
# Delete the database file
|
||||
rm dev/payload.sqlite
|
||||
|
||||
# Restart the server (will re-seed automatically)
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The plugin is configured in `dev/payload.config.ts` with:
|
||||
|
||||
### Test Provider Setup
|
||||
```typescript
|
||||
testProvider({
|
||||
enabled: true,
|
||||
testModeIndicators: {
|
||||
showWarningBanners: true,
|
||||
showTestBadges: true,
|
||||
consoleWarnings: true
|
||||
},
|
||||
customUiRoute: '/test-payment',
|
||||
})
|
||||
```
|
||||
|
||||
### Customer Relationship
|
||||
```typescript
|
||||
customerRelationSlug: 'customers',
|
||||
customerInfoExtractor: (customer) => ({
|
||||
name: customer.name,
|
||||
email: customer.email,
|
||||
phone: customer.phone,
|
||||
company: customer.company,
|
||||
taxId: customer.taxId,
|
||||
billingAddress: customer.address ? {
|
||||
line1: customer.address.line1,
|
||||
line2: customer.address.line2,
|
||||
city: customer.address.city,
|
||||
state: customer.address.state,
|
||||
postalCode: customer.address.postalCode,
|
||||
country: customer.address.country,
|
||||
} : undefined,
|
||||
})
|
||||
```
|
||||
|
||||
## Test Payment Scenarios
|
||||
|
||||
The test provider includes the following scenarios:
|
||||
|
||||
1. **Instant Success** - Payment succeeds immediately
|
||||
2. **Delayed Success** - Payment succeeds after a delay (3s)
|
||||
3. **Cancelled Payment** - User cancels the payment (1s)
|
||||
4. **Declined Payment** - Payment is declined by the provider (2s)
|
||||
5. **Expired Payment** - Payment expires before completion (5s)
|
||||
6. **Pending Payment** - Payment remains in pending state (1.5s)
|
||||
|
||||
## Payment Methods
|
||||
|
||||
The test provider supports these payment methods:
|
||||
|
||||
- 🏦 iDEAL
|
||||
- 💳 Credit Card
|
||||
- 🅿️ PayPal
|
||||
- 🍎 Apple Pay
|
||||
- 🏛️ Bank Transfer
|
||||
|
||||
## API Examples
|
||||
|
||||
### Creating a Payment (Local API)
|
||||
|
||||
```typescript
|
||||
import { getPayload } from 'payload'
|
||||
import configPromise from '@payload-config'
|
||||
|
||||
const payload = await getPayload({ config: configPromise })
|
||||
|
||||
const payment = await payload.create({
|
||||
collection: 'payments',
|
||||
data: {
|
||||
provider: 'test',
|
||||
amount: 2500, // $25.00 in cents
|
||||
currency: 'USD',
|
||||
description: 'Demo payment',
|
||||
status: 'pending',
|
||||
}
|
||||
})
|
||||
|
||||
// The payment will have a providerId that can be used in the custom UI
|
||||
console.log(`Payment URL: /test-payment/${payment.providerId}`)
|
||||
```
|
||||
|
||||
### Creating an Invoice with Customer
|
||||
|
||||
```typescript
|
||||
const invoice = await payload.create({
|
||||
collection: 'invoices',
|
||||
data: {
|
||||
customer: 'customer-id-here',
|
||||
currency: 'USD',
|
||||
items: [
|
||||
{
|
||||
description: 'Service',
|
||||
quantity: 1,
|
||||
unitAmount: 5000 // $50.00
|
||||
}
|
||||
],
|
||||
taxAmount: 500, // $5.00
|
||||
status: 'open'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### REST API Example
|
||||
|
||||
```bash
|
||||
# Create a payment
|
||||
curl -X POST http://localhost:3000/api/payments \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{
|
||||
"provider": "test",
|
||||
"amount": 2500,
|
||||
"currency": "USD",
|
||||
"description": "Demo payment",
|
||||
"status": "pending"
|
||||
}'
|
||||
```
|
||||
|
||||
## Custom Routes
|
||||
|
||||
The demo includes custom API routes:
|
||||
|
||||
### Create Payment
|
||||
```
|
||||
POST /api/demo/create-payment
|
||||
```
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"amount": 2500,
|
||||
"currency": "USD",
|
||||
"description": "Demo payment"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"payment": {
|
||||
"id": "test_pay_1234567890_abc123",
|
||||
"paymentId": "67890",
|
||||
"amount": 2500,
|
||||
"currency": "USD",
|
||||
"description": "Demo payment"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
dev/
|
||||
├── app/
|
||||
│ ├── page.tsx # Interactive demo page (root)
|
||||
│ ├── test-payment/
|
||||
│ │ └── [id]/
|
||||
│ │ └── page.tsx # Custom payment UI
|
||||
│ ├── api/
|
||||
│ │ └── demo/
|
||||
│ │ └── create-payment/
|
||||
│ │ └── route.ts # Payment creation endpoint
|
||||
│ └── (payload)/ # PayloadCMS admin routes
|
||||
├── helpers/
|
||||
│ └── credentials.ts # Default user credentials
|
||||
├── payload.config.ts # PayloadCMS configuration
|
||||
├── seed.ts # Sample data seeding
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Modifying the Demo
|
||||
|
||||
To customize the demo:
|
||||
|
||||
1. **Add more test scenarios**: Edit the `testProvider` config in `payload.config.ts`
|
||||
2. **Customize the payment UI**: Edit `app/test-payment/[id]/page.tsx`
|
||||
3. **Add more sample data**: Edit `seed.ts`
|
||||
4. **Add custom collections**: Add to `collections` array in `payload.config.ts`
|
||||
|
||||
### Testing Different Providers
|
||||
|
||||
To test with real payment providers:
|
||||
|
||||
```typescript
|
||||
// Install the provider
|
||||
pnpm add stripe
|
||||
// or
|
||||
pnpm add @mollie/api-client
|
||||
|
||||
// Update payload.config.ts
|
||||
import { stripeProvider, mollieProvider } from '../src/providers'
|
||||
|
||||
billingPlugin({
|
||||
providers: [
|
||||
stripeProvider({
|
||||
secretKey: process.env.STRIPE_SECRET_KEY!,
|
||||
webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
|
||||
}),
|
||||
mollieProvider({
|
||||
apiKey: process.env.MOLLIE_API_KEY!,
|
||||
webhookUrl: process.env.MOLLIE_WEBHOOK_URL,
|
||||
}),
|
||||
// Keep test provider for development
|
||||
testProvider({ enabled: true }),
|
||||
],
|
||||
// ... rest of config
|
||||
})
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database Issues
|
||||
|
||||
If you encounter database errors:
|
||||
```bash
|
||||
# Delete the database
|
||||
rm dev/payload.sqlite
|
||||
|
||||
# Regenerate types
|
||||
pnpm dev:generate-types
|
||||
|
||||
# Restart the server
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
If port 3000 is already in use:
|
||||
```bash
|
||||
# Use a different port
|
||||
PORT=3001 pnpm dev
|
||||
```
|
||||
|
||||
### TypeScript Errors
|
||||
|
||||
Regenerate Payload types:
|
||||
```bash
|
||||
pnpm dev:generate-types
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Plugin Documentation](../README.md)
|
||||
- [PayloadCMS Documentation](https://payloadcms.com/docs)
|
||||
- [GitHub Repository](https://github.com/xtr-dev/payload-billing)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user