mirror of
https://github.com/xtr-dev/payload-billing.git
synced 2025-12-10 02:43:24 +00:00
docs: update README to reflect current codebase features
- Update version info from v0.0.x to v0.1.x - Add comprehensive customer management documentation - Include customer info extractor examples and configuration - Document flexible customer data handling modes - Add missing TypeScript exports to imports section - Update features list with callback-based syncing and embedded customer info Co-authored-by: Bas <bvdaakster@users.noreply.github.com>
This commit is contained in:
79
README.md
79
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,51 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
### With Customer Management
|
||||
|
||||
```typescript
|
||||
import { billingPlugin, defaultCustomerInfoExtractor } from '@xtr-dev/payload-billing'
|
||||
|
||||
billingPlugin({
|
||||
// ... providers
|
||||
collections: {
|
||||
payments: 'payments',
|
||||
invoices: 'invoices',
|
||||
refunds: 'refunds',
|
||||
},
|
||||
customerRelationSlug: 'customers', // Enable customer relationships
|
||||
customerInfoExtractor: defaultCustomerInfoExtractor, // 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 +129,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 +158,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