mirror of
https://github.com/xtr-dev/payload-billing.git
synced 2025-12-10 10:53:23 +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
|
# @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
|
## Features
|
||||||
|
|
||||||
- 💳 Multiple payment providers (Stripe, Mollie, Test)
|
- 💳 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
|
- 📊 Complete payment tracking and history
|
||||||
- 🪝 Secure webhook processing for all providers
|
- 🪝 Secure webhook processing for all providers
|
||||||
- 🧪 Built-in test provider for local development
|
- 🧪 Built-in test provider for local development
|
||||||
- 📱 Payment management in PayloadCMS admin
|
- 📱 Payment management in PayloadCMS admin
|
||||||
|
- 🔄 Callback-based customer data syncing
|
||||||
- 🔒 Full TypeScript support
|
- 🔒 Full TypeScript support
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
@@ -42,6 +44,8 @@ pnpm add @mollie/api-client
|
|||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
|
### Basic Configuration
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { buildConfig } from 'payload'
|
import { buildConfig } from 'payload'
|
||||||
import { billingPlugin, stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
|
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
|
## Imports
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
@@ -80,7 +129,17 @@ import { billingPlugin } from '@xtr-dev/payload-billing'
|
|||||||
import { stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
|
import { stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
|
||||||
|
|
||||||
// Types
|
// 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
|
## Provider Types
|
||||||
@@ -99,9 +158,19 @@ Local development testing with configurable scenarios, automatic completion, deb
|
|||||||
The plugin adds these collections:
|
The plugin adds these collections:
|
||||||
|
|
||||||
- **payments** - Payment transactions with status and provider data
|
- **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
|
- **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
|
## Webhook Endpoints
|
||||||
|
|
||||||
Automatic webhook endpoints are created for configured providers:
|
Automatic webhook endpoints are created for configured providers:
|
||||||
|
|||||||
Reference in New Issue
Block a user