ArtisanPack UI Ecommerce PayPal Documentation Home

Welcome to the documentation for ArtisanPack UI Ecommerce PayPal. The package is the PayPal gateway for the artisanpack-ui/ecommerce engine. It adds PayPal (with Pay Later and Venmo), advanced card fields with 3-D Secure, Apple Pay, and Google Pay to checkout through PayPal's Orders v2 API.

It registers four gateways with the engine, verifies PayPal's webhooks, and stores saved payment methods as PayPal vault references. With artisanpack-ui/ecommerce-storefront-livewire installed, it also ships the Livewire payment UI and a saved payment methods account page. Card data is entered in PayPal-hosted fields and never reaches your server, which is designed to support a PCI DSS SAQ A assessment; see Security and CSP for what else eligibility needs.

Table of Contents

• Getting Started

  • Quick Start Guide

• Installation

  • Installation Overview
  • Requirements
  • PayPal App and Credentials
  • Configuration
  • Front-End Setup

• Payment Methods

  • Payment Methods Overview
  • PayPal Buttons
  • Card Fields
  • Apple Pay
  • Google Pay
  • Pay Later Messaging

• Payments and Events

  • Saved Payment Methods
  • Webhooks

• Extending

  • Extending Overview
  • Hooks Reference
  • Availability
  • JavaScript Module (React and Vue)

• Quality

  • Accessibility
  • Localization

• Advanced

  • Advanced Overview
  • Artisan Commands
  • Security and CSP
  • Troubleshooting
  • Admin Order Panel
  • Testing Your Application
  • Upgrade Guide
  • Sandbox Integration Tests
  • Browser Tests

Features

• Four checkout choices: PayPal (with Pay Later and Venmo where the buyer is eligible), credit or debit card, Apple Pay, and Google Pay. Each is its own gateway and can be switched on separately.
• Two-phase payments: The PayPal Order is created on the server and captured at finalize. Captures, voids, and refunds are idempotent, and declines come back as results, not exceptions.
• Capture or authorize: Take the money when the order is placed, or authorize first. Uncaptured authorizations are reauthorized after PayPal's honor period by a scheduled command.
• 3-D Secure: Card fields, Apple Pay, and Google Pay run 3-D Secure in PayPal's flow, and payments without a liability shift can be refused.
• Verified webhooks: Signatures are checked locally against PayPal's certificate (or by PayPal, in postback mode). Pending captures, dashboard refunds, reversals, disputes, and vault changes are recorded on the order.
• Saved payment methods: Signed-in shoppers can save PayPal and cards. Only PayPal's token ids and display data are stored. Shoppers manage them on an account page or through REST endpoints.
• Storefront UI: Livewire drivers for storefront-livewire, a Pay Later message component, and a framework-agnostic JS module (paypal-checkout.js) for React and Vue storefronts.
• Operations: Setup commands that register the webhook and check the credentials, webhook, and Apple Pay domain file; a daily cleanup of saved payment methods; an admin order panel; PayPal debug ids in every error log, with credentials and personal data redacted.
• Extension points: Filters for the Order payload, client options, and currencies, and 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, and loads PayPal's SDK in the matching locale.

Quick Example

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

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

php artisan ecommerce-paypal:webhooks:register   # prints the webhook id

Add the printed id to .env as PAYPAL_WEBHOOK_ID, then check the setup:

php artisan ecommerce-paypal:verify-credentials

Then set PAYPAL_ENABLED=true (or enable PayPal in the store settings). PayPal now appears at checkout.

Support

For support, please open an issue on the GitHub repository.

License

This package is open-source software licensed under the MIT license.