Event System - OwnPay

OwnPay dispatches internal events through the EventManager that plugins can listen to. Events are distinct from hooks and serve a different architectural purpose.

Events vs hooks

Aspect	Events	Hooks
Direction	Core fires → plugins listen	Core fires or transforms → plugins participate
Return value	Ignored	Filters must return a value
Queuing	Can be queued for async handling	Always synchronous
Typical use	Domain events, side effects	Data mutation, template overrides
API	`$events->addListener()`	`$events->addAction()` / `$events->addFilter()`

Use events when you need async processing (for example sending an email after a payment). Use hooks when you need to modify data in-flight.

Listening to events in plugins

public function register(EventManager $events, Container $container): void
{
    $events->addListener(
        \OwnPay\Events\PaymentCompleted::class,
        function (PaymentCompleted $event) use ($container): void {
            $container->get(AnalyticsService::class)->track($event->transaction);
        }
    );
}

Built-in events

Event class	Dispatched when	Key properties
`PaymentCompleted`	Transaction settled	`transaction: array`
`PaymentFailed`	Transaction declined	`transaction: array`, `reason: string`
`PaymentExpired`	Intent timed out	`intent: array`
`RefundIssued`	Refund initiated	`refund: array`, `transaction: array`
`RefundCompleted`	Refund settled at gateway	`refund: array`
`RefundFailed`	Refund rejected by gateway	`refund: array`, `reason: string`
`CustomerCreated`	New customer record	`customer: array`
`DisputeOpened`	Chargeback received	`dispute: array`
`DisputeResolved`	Dispute outcome finalized	`dispute: array`, `outcome: string`
`PluginInstalled`	Plugin ZIP extracted	`slug: string`, `manifest: array`
`PluginActivated`	Plugin activated for a brand	`slug: string`, `brandId: int`
`PluginDeactivated`	Plugin deactivated	`slug: string`, `brandId: int`
`DomainMapped`	Custom domain linked	`domain: string`, `merchantId: int`
`DomainVerified`	DNS verification passed	`domain: string`, `merchantId: int`
`UpdateAvailable`	Newer release detected	`latestVersion: string`

Event listener registration

// Synchronous listener (default)
$events->addListener(PaymentCompleted::class, function (PaymentCompleted $event): void {
    // Runs immediately, blocks until done
});

// Queued listener (async via Redis)
$events->addListener(PaymentCompleted::class, SendReceiptListener::class, queued: true);

Queued listeners require Redis to be configured. The listener class must implement __invoke(PaymentCompleted $event).

Error handling

Event listeners run inside the same error-isolation wrapper as hooks. If a listener throws, the error is logged and the event continues to the next listener.

Last modified on August 25, 2026

Related topics

How OwnPay Works Features and Capabilities Plugin System Plugin System - Extensible Architecture Hooks Reference