mirror of
https://github.com/xtr-dev/payload-billing.git
synced 2025-12-10 02:43:24 +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
|
# @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,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
|
## Imports
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
@@ -80,7 +146,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 +175,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