mirror of
https://github.com/xtr-dev/payload-billing.git
synced 2025-12-10 10:53:23 +00:00
Compare commits
2 Commits
v0.1.6
...
claude/iss
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
38c8c3677d | ||
|
|
e74a2410e6 |
96
README.md
96
README.md
@@ -1,17 +1,19 @@
|
||||
# @xtr-dev/payload-billing
|
||||
|
||||
A billing and payment provider plugin for PayloadCMS 3.x. Supports Stripe, Mollie, and local testing with comprehensive tracking.
|
||||
A billing and payment provider plugin for PayloadCMS 3.x. Supports Stripe, Mollie, and local testing with comprehensive tracking and flexible customer data management.
|
||||
|
||||
⚠️ **Pre-release Warning**: This package is currently in active development (v0.0.x). Breaking changes may occur before v1.0.0. Not recommended for production use.
|
||||
⚠️ **Pre-release Warning**: This package is currently in active development (v0.1.x). Breaking changes may occur before v1.0.0. Not recommended for production use.
|
||||
|
||||
## Features
|
||||
|
||||
- 💳 Multiple payment providers (Stripe, Mollie, Test)
|
||||
- 🧾 Invoice generation and management
|
||||
- 🧾 Invoice generation and management with embedded customer info
|
||||
- 👥 Flexible customer data management with relationship support
|
||||
- 📊 Complete payment tracking and history
|
||||
- 🪝 Secure webhook processing for all providers
|
||||
- 🧪 Built-in test provider for local development
|
||||
- 📱 Payment management in PayloadCMS admin
|
||||
- 🔄 Callback-based customer data syncing
|
||||
- 🔒 Full TypeScript support
|
||||
|
||||
## Installation
|
||||
@@ -42,6 +44,8 @@ pnpm add @mollie/api-client
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```typescript
|
||||
import { buildConfig } from 'payload'
|
||||
import { billingPlugin, stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
|
||||
@@ -70,6 +74,68 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
### With Customer Management
|
||||
|
||||
```typescript
|
||||
import { billingPlugin, CustomerInfoExtractor } from '@xtr-dev/payload-billing'
|
||||
|
||||
// Define how to extract customer info from your customer collection
|
||||
const customerExtractor: CustomerInfoExtractor = (customer) => ({
|
||||
name: customer.name,
|
||||
email: customer.email,
|
||||
phone: customer.phone,
|
||||
company: customer.company,
|
||||
taxId: customer.taxId,
|
||||
billingAddress: {
|
||||
line1: customer.address.line1,
|
||||
line2: customer.address.line2,
|
||||
city: customer.address.city,
|
||||
state: customer.address.state,
|
||||
postalCode: customer.address.postalCode,
|
||||
country: customer.address.country,
|
||||
}
|
||||
})
|
||||
|
||||
billingPlugin({
|
||||
// ... providers
|
||||
collections: {
|
||||
payments: 'payments',
|
||||
invoices: 'invoices',
|
||||
refunds: 'refunds',
|
||||
},
|
||||
customerRelationSlug: 'customers', // Enable customer relationships
|
||||
customerInfoExtractor: customerExtractor, // Auto-sync customer data
|
||||
})
|
||||
```
|
||||
|
||||
### Custom Customer Data Extraction
|
||||
|
||||
```typescript
|
||||
import { CustomerInfoExtractor } from '@xtr-dev/payload-billing'
|
||||
|
||||
const customExtractor: CustomerInfoExtractor = (customer) => ({
|
||||
name: customer.fullName,
|
||||
email: customer.contactEmail,
|
||||
phone: customer.phoneNumber,
|
||||
company: customer.companyName,
|
||||
taxId: customer.vatNumber,
|
||||
billingAddress: {
|
||||
line1: customer.billing.street,
|
||||
line2: customer.billing.apartment,
|
||||
city: customer.billing.city,
|
||||
state: customer.billing.state,
|
||||
postalCode: customer.billing.zip,
|
||||
country: customer.billing.countryCode,
|
||||
}
|
||||
})
|
||||
|
||||
billingPlugin({
|
||||
// ... other config
|
||||
customerRelationSlug: 'clients',
|
||||
customerInfoExtractor: customExtractor,
|
||||
})
|
||||
```
|
||||
|
||||
## Imports
|
||||
|
||||
```typescript
|
||||
@@ -80,7 +146,17 @@ import { billingPlugin } from '@xtr-dev/payload-billing'
|
||||
import { stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
|
||||
|
||||
// Types
|
||||
import type { PaymentProvider, Payment, Invoice, Refund } from '@xtr-dev/payload-billing'
|
||||
import type {
|
||||
PaymentProvider,
|
||||
Payment,
|
||||
Invoice,
|
||||
Refund,
|
||||
BillingPluginConfig,
|
||||
CustomerInfoExtractor,
|
||||
MollieProviderConfig,
|
||||
StripeProviderConfig,
|
||||
ProviderData
|
||||
} from '@xtr-dev/payload-billing'
|
||||
```
|
||||
|
||||
## Provider Types
|
||||
@@ -99,9 +175,19 @@ Local development testing with configurable scenarios, automatic completion, deb
|
||||
The plugin adds these collections:
|
||||
|
||||
- **payments** - Payment transactions with status and provider data
|
||||
- **invoices** - Invoice generation with line items and PDF support
|
||||
- **invoices** - Invoice generation with line items and embedded customer info
|
||||
- **refunds** - Refund tracking and management
|
||||
|
||||
### Customer Data Management
|
||||
|
||||
The plugin supports flexible customer data handling:
|
||||
|
||||
1. **With Customer Relationship + Extractor**: Customer relationship required, customer info auto-populated and read-only, syncs automatically when customer changes
|
||||
|
||||
2. **With Customer Relationship (no extractor)**: Customer relationship optional, customer info manually editable, either relationship OR customer info required
|
||||
|
||||
3. **No Customer Collection**: Customer info fields always required and editable, no relationship field available
|
||||
|
||||
## Webhook Endpoints
|
||||
|
||||
Automatic webhook endpoints are created for configured providers:
|
||||
|
||||
Reference in New Issue
Block a user