PHPackages sudiptpa/paypal-notifications - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. sudiptpa/paypal-notifications ActiveLibrary[Payment Processing](/categories/payments) sudiptpa/paypal-notifications ============================= Framework-agnostic PayPal Notifications SDK for webhook signature verification and legacy Instant Payment Notification verification. v1.1.0(4mo ago)0346MITPHPPHP >=8.2 <8.6CI passing Since Feb 21Pushed 3mo agoCompare [ Source](https://github.com/sudiptpa/paypal-notifications)[ Packagist](https://packagist.org/packages/sudiptpa/paypal-notifications)[ RSS](/packages/sudiptpa-paypal-notifications/feed)WikiDiscussions main Synced today READMEChangelog (2)Dependencies (2)Versions (4)Used By (0) PayPal Notifications PHP SDK ============================ [](#paypal-notifications-php-sdk) Framework-agnostic PHP SDK for PayPal **Webhooks** and legacy **Instant Payment Notification (IPN)** verification. [![CI](https://github.com/sudiptpa/paypal-notifications/actions/workflows/ci.yml/badge.svg)](https://github.com/sudiptpa/paypal-notifications/actions/workflows/ci.yml)[![Latest Release](https://camo.githubusercontent.com/c203e8d916f17fe3b0d0dd25ea969ea7959e00aabf0c5feab9e071669acf928a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f73756469707470612f70617970616c2d6e6f74696669636174696f6e733f736f72743d73656d766572)](https://github.com/sudiptpa/paypal-notifications/releases)[![Packagist](https://camo.githubusercontent.com/e80477c3e60b2aaf5235ea0f8dd254154ae4c15dd32962c215d29fe7c79d7aec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73756469707470612f70617970616c2d6e6f74696669636174696f6e73)](https://packagist.org/packages/sudiptpa/paypal-notifications)[![Downloads](https://camo.githubusercontent.com/e3b38b7e13d65b6d02f1f29f1b872719f2a39b4bc8ff45f55434782bfe07190c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73756469707470612f70617970616c2d6e6f74696669636174696f6e73)](https://packagist.org/packages/sudiptpa/paypal-notifications)[![PHP](https://camo.githubusercontent.com/1aa7939e7a27a6dfba78b11869a5918ecc8c2da1876f0122727733776e3fff4c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e322d2d382e352d3737376262342e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/a536dc4fbd444825cc4a801b898a4296c26e98c6eb9043f2e496f4208d835a20/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f73756469707470612f70617970616c2d6e6f74696669636174696f6e73)](LICENSE) --- [![Sponsor](https://camo.githubusercontent.com/d57b8ff0c3e08877e313deccbfe103a9cbcc5121e4d381986c7f56fb19a08b71/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53706f6e736f722d47697448756225323053706f6e736f72732d6561346161613f6c6f676f3d67697468756273706f6e736f7273266c6f676f436f6c6f723d7768697465)](https://github.com/sponsors/sudiptpa) If this package has been useful to you, GitHub Sponsors is a simple way to support ongoing maintenance, improvements, and future releases. Table of Contents ----------------- [](#table-of-contents) - [At a Glance](#at-a-glance) - [Why This Package](#why-this-package) - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Quick Start](#quick-start) - [Release Highlights (v1.0.0)](#release-highlights-v100) - [Webhook Verification (Simple)](#webhook-verification-simple) - [Webhook Verification (Advanced)](#webhook-verification-advanced) - [Typed Event Parsing](#typed-event-parsing) - [Event Catalog](#event-catalog) - [Event Routing](#event-routing) - [Framework Adapters](#framework-adapters) - [Webhook Processor](#webhook-processor) - [Token Caching](#token-caching) - [Idempotency Guard](#idempotency-guard) - [Persistent Idempotency Stores](#persistent-idempotency-stores) - [Retry Strategy](#retry-strategy) - [Instant Payment Notification (Legacy)](#instant-payment-notification-legacy) - [Transport Extension](#transport-extension) - [Extending Event Mappings](#extending-event-mappings) - [Dead-Letter Guidance](#dead-letter-guidance) - [Examples](#examples) - [Error Handling](#error-handling) - [Production Checklist](#production-checklist) - [Testing](#testing) - [Manual Sandbox Smoke Test](#manual-sandbox-smoke-test) - [Contributing](#contributing) At a Glance ----------- [](#at-a-glance) Usage: - Verify PayPal webhook signatures before processing events. - Parse webhook payloads into typed event models. - Route events using clear type-based handlers. - Process webhooks with idempotency protection and structured outcomes. - Verify legacy Instant Payment Notification (IPN) during migration windows. Benefits: - Security-first verification aligned with PayPal’s flow. - Typed models and typed exceptions for safer handling. - Retry controls for transient verification failures. - Minimal dependencies with framework-agnostic design. - Backward-compatible event API paths for smoother upgrades. Why This Package ---------------- [](#why-this-package) This SDK is for PHP projects that need reliable PayPal notification verification without framework lock-in. Design goals: - resource-based API aligned with PayPal docs - minimal hard dependencies - explicit models and enums - transport extensibility - safe production defaults Features -------- [](#features) - Webhook signature verification using PayPal `verify-webhook-signature` API - Case-insensitive extraction of required PayPal headers: - `PAYPAL-TRANSMISSION-ID` - `PAYPAL-TRANSMISSION-TIME` - `PAYPAL-TRANSMISSION-SIG` - `PAYPAL-CERT-URL` - `PAYPAL-AUTH-ALGO` - OAuth client credentials flow with in-memory token caching - Typed event parsing with mapped models for: - `PAYMENT.CAPTURE.COMPLETED` - `PAYMENT.CAPTURE.DENIED` - `PAYMENT.CAPTURE.REFUNDED` - `PAYMENT.CAPTURE.PENDING` - `PAYMENT.CAPTURE.REVERSED` - `CHECKOUT.ORDER.APPROVED` - `CHECKOUT.ORDER.COMPLETED` - `CUSTOMER.DISPUTE.CREATED` - `CUSTOMER.DISPUTE.RESOLVED` - `BILLING.SUBSCRIPTION.CREATED` - `BILLING.SUBSCRIPTION.CANCELLED` - `BILLING.SUBSCRIPTION.ACTIVATED` - `BILLING.SUBSCRIPTION.SUSPENDED` - `BILLING.SUBSCRIPTION.EXPIRED` - `BILLING.SUBSCRIPTION.PAYMENT.FAILED` - `PAYMENT.PAYOUTSBATCH.SUCCESS` - `PAYMENT.PAYOUTS-ITEM.SUCCEEDED` - `PAYMENT.PAYOUTS-ITEM.DENIED` - Unknown event fallback (`UnknownWebhookEvent`) for forward compatibility - Event router helper for clean application handlers - Framework adapter contract for framework-specific request bridges - High-level `WebhookProcessor` with structured processing result (easy to log and monitor) - Idempotency guard support for duplicate event prevention - Optional persisted OAuth token caches (file or Redis-style key-value adapter) - Optional persistent idempotency stores (Redis-style key-value adapter and app-managed database stores) - Configurable retry strategy for transient verification failures - Legacy Instant Payment Notification verification (`cmd=_notify-validate`) - Native cURL transport included (`CurlTransport`) - Custom transport support via `TransportInterface` - Strict exception model and safe error handling Requirements ------------ [](#requirements) - PHP `^8.2` (supports up to `