README

The PayPal gateway for the ArtisanPack UI ecommerce engine: PayPal, Pay Later, and Venmo buttons, advanced card fields with 3-D Secure, Apple Pay, and Google Pay through PayPal's Orders v2 API, with signature-verified webhooks and saved payment methods. Card data is collected by PayPal's SDK only and never reaches your server, which is designed to support a PCI DSS SAQ A assessment. Eligibility also depends on the rest of your payment page, so confirm it with your acquirer (see Security and CSP).

It registers four gateways with the engine (paypal, paypal-card, paypal-apple-pay, paypal-google-pay). With ecommerce-storefront-livewire installed it also ships the Livewire payment UI and a saved payment methods account page; React and Vue storefronts use its framework-agnostic JS module.

Features

Four checkout choices: PayPal (with Pay Later and Venmo), credit or debit card, Apple Pay, and Google Pay, each switched on separately.
Capture or authorize: Idempotent captures, voids, and full or partial refunds. Uncaptured authorizations are reauthorized after PayPal's honor period by a scheduled command.
3-D Secure: Card and wallet payments without a liability shift can be refused.
Verified webhooks: Local signature verification (or PayPal postback), with pending captures, dashboard refunds, reversals, disputes, and vault changes recorded on the order.
Saved payment methods: PayPal and cards, managed on an account page or through REST endpoints. Only PayPal's token ids and display data are stored.
Operations: Setup commands, an admin order panel, and PayPal debug ids in every error log, with credentials and personal data redacted.
Extension points: Filters for the Order payload, client options, and currencies; actions for captures, denials, expiring authorizations, disputes, and every webhook event.
Accessible and translated: Targets WCAG 2.2 AA. Ships English, Spanish, French, and German.

Requirements

PHP 8.3+ with ext-openssl
Laravel 12 or 13
artisanpack-ui/ecommerce 1.3 or later 1.x (^1.3)
Optional: artisanpack-ui/ecommerce-storefront-livewire (payment UI, account page) and artisanpack-ui/ecommerce-admin-livewire (order panel, settings screen)

Quick start

composer require artisanpack-ui/ecommerce-paypal
php artisan ecommerce-paypal:install --migrate

The service provider is auto-discovered and registers the package with the engine's satellite registry. The install command publishes the config and the JS module, runs the migrations, and prints the Tailwind @source line and the Content-Security-Policy sources.

Add your PayPal REST app's credentials to .env:

PAYPAL_MODE=sandbox
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-secret

php artisan ecommerce-paypal:webhooks:register

Set the webhook id it printed, then check the setup:

PAYPAL_WEBHOOK_ID=the-printed-id

php artisan ecommerce-paypal:verify-credentials

Then turn PayPal on with PAYPAL_ENABLED=true. PayPal now appears at checkout. Turn on cards, Apple Pay, Google Pay, Pay Later messages, and saved payment methods in the config or the store settings.

Documentation

Testing

composer test   # Unit and Feature suites
npm test        # the JS module's Vitest suite (run npm ci first)
composer lint

Contributing

As an open source project, this package is open to contributions from anyone. Please read through the contributing guidelines to learn more about how you can contribute to this project.

License

MIT. See LICENSE.

artisanpack-ui / ecommerce-paypal

Package info

Security

Statistics