Paddle Billing
First-class Paddle billing integration for Vortos — customers, subscriptions, transactions, catalog, and webhooks with a full transactional outbox.
Paddle Billing
vortos/vortos-paddle integrates Paddle billing into Vortos. It covers the full Paddle surface area: customers, addresses, businesses, subscriptions, transactions, adjustments, catalog products, prices, discounts, checkout sessions, portal sessions, and reports.
Every mutating service call goes through a three-tier delivery model: write inside a database transaction (Transactional), write in a standalone transaction (Standalone), or call the Paddle API directly (Immediate). The transactional and standalone tiers route writes through a database outbox so Paddle API calls are decoupled from the business transaction.
Paddle Billing API v1
The package targets the Paddle Billing API (the current API). Classic Paddle is not supported.
What The Package Covers
- Full Paddle service hierarchy for all domains: Customer, Address, Business, Transaction, Adjustment, Product, Price, Discount, Subscription, Checkout, and Report.
- Three-tier delivery contract per domain (Immediate / Transactional / Standalone).
- Transactional outbox with exponential backoff, configurable retry limits, and a long-running worker command.
- Dead-letter retry command to reset permanently failed outbox entries.
- Webhook controller with IP allowlist, replay-attack protection, and idempotency deduplication.
- Attribute-based webhook handler discovery.
- Circuit breaker and SDK exception mapping.
- Audit log for all received webhook events.
- API idempotency key store.
Package Registration
use Vortos\Paddle\DependencyInjection\PaddlePackage;
$packages = [
// ... other packages
new PaddlePackage(),
];Documentation Map
Quickstart
Install, configure, and make your first Paddle API call.
Configuration
Full config reference for API client, webhooks, security, circuit breaker, outbox, and observability.
Services
The three-tier service hierarchy and when to use each.
Webhooks
Receive and handle Paddle webhook events with idempotency and IP verification.
Outbox
Transactional outbox relay, backoff strategy, and dead-letter retry.
Testing & Operations
Commands, sandbox setup, and operational runbooks.
Service Guarantees
The injected interface determines the delivery guarantee.
use Vortos\Paddle\Customer\Contract\CustomerServiceInterface;
use Vortos\Paddle\Customer\Contract\StandaloneCustomerServiceInterface;
use Vortos\Paddle\Customer\Contract\ImmediateCustomerServiceInterface;CustomerServiceInterface (Transactional) — writes to the outbox inside the active database transaction. Use inside command handlers.
StandaloneCustomerServiceInterface (Standalone) — wraps the write in its own short transaction. Use in console commands or event listeners that run outside the main unit of work.
ImmediateCustomerServiceInterface (Immediate) — calls the Paddle API directly. Use for reads and diagnostics only.
The same three interfaces exist for every domain: Address, Business, Transaction, Adjustment, Product, Price, Discount, and Subscription.