README

PayPal payment gateway add-on for Statamic Resrv.

Features

PayPal Wallet Payments - Users can pay with their PayPal account
Direct Card Payments - Credit/debit card fields rendered directly on your checkout page (Advanced Credit and Debit Card Payments)
No Redirects - Payment handled inline via PayPal JavaScript SDK
Secure - PCI-compliant hosted card fields, webhook signature verification

Requirements

PHP 8.2+
Laravel 11.x
Statamic 5.x
Statamic Resrv 5.x
PayPal Business Account with Advanced Credit and Debit Card Payments enabled (for card fields)

Installation

composer require reachweb/resrv-payment-paypal

Optionally publish the configuration:

php artisan vendor:publish --tag=resrv-paypal-config

PayPal Account Setup

Go to the PayPal Developer Dashboard
Create a new application (or use an existing one)
Note your Client ID and Client Secret for both sandbox and live environments
Enable Advanced Credit and Debit Card Payments in your app settings to allow direct card input

Tip: Advanced Credit and Debit Card Payments (ACDC) is automatically enabled for sandbox accounts. For live accounts, you may need to request access through your PayPal account manager.

API Configuration

Add your PayPal credentials to your .env file:

PAYPAL_CLIENT_ID=your_client_id
PAYPAL_CLIENT_SECRET=your_client_secret
PAYPAL_MODE=sandbox
PAYPAL_WEBHOOK_ID=your_webhook_id

Set PAYPAL_MODE to sandbox for testing or live for production.

Important: For security purposes, never commit your API credentials to version control. Always use environment variables.

If you have configuration caching enabled, clear it after updating your .env file:

php artisan config:clear

Webhook Configuration (Required)

Webhooks are mandatory for the PayPal payment gateway. They ensure payment confirmations are received even if a customer closes their browser before returning to your site.

Setting up Webhooks

In your PayPal Developer Dashboard, go to your application settings
Navigate to Webhooks and click Add Webhook
Enter your webhook URL: https://yoursite.com/resrv/api/webhook
Subscribe to these events:
- PAYMENT.CAPTURE.COMPLETED
- PAYMENT.CAPTURE.DENIED
- PAYMENT.CAPTURE.REFUNDED
Save the webhook and copy the Webhook ID
Add the Webhook ID to your .env file:

PAYPAL_WEBHOOK_ID=your_webhook_id

Warning: Without a valid PAYPAL_WEBHOOK_ID, webhook signature verification will fail and payment confirmations will be rejected with a 403 error.

Webhook Signature Verification

The gateway uses PayPal's verify-webhook-signature API to validate all incoming webhook notifications. This ensures:

Webhooks actually come from PayPal
The payload hasn't been tampered with
Your application is protected from spoofing attacks

Payment Gateway Configuration

Update your config/resrv-config.php file to use the PayPal payment gateway:

'payment_gateway' => Reach\ResrvPaymentPaypal\Http\Payment\PaypalPaymentGateway::class,

Payment Flow

This gateway uses the PayPal JavaScript SDK for an inline payment experience. When a customer completes a reservation:

The checkout page displays PayPal buttons and card fields inline
Customer can either:
- Click the PayPal button to pay via PayPal wallet (opens popup)
- Enter card details directly in the card fields on your page
Payment is captured via your server
Customer is redirected to the checkout completion page
PayPal sends a webhook notification
The webhook signature is verified
The reservation is confirmed

Payment Options Displayed

PayPal Button - Opens PayPal popup for wallet payments, Pay Later, Venmo (US)
Card Fields - Direct card number, expiry, CVV, and cardholder name input (requires ACDC enabled)

If Advanced Credit and Debit Card Payments is not enabled for your account, only the PayPal button will be displayed.

Customizing the Payment View

The package provides a default checkout payment view. To customize the styling or layout:

php artisan vendor:publish --tag=resrv-paypal-views

This publishes the view to resources/views/vendor/statamic-resrv/livewire/checkout-payment.blade.php.

You can customize:

Button colors and styles
Card field container styling
Labels and translations
Layout and spacing

Going Live

Before accepting live payments:

Test thoroughly in sandbox mode with PayPal sandbox accounts
Create a live webhook in your PayPal application with the same events
Ensure Advanced Credit and Debit Card Payments is enabled for your live app
Update your .env file with live credentials:

PAYPAL_CLIENT_ID=your_live_client_id
PAYPAL_CLIENT_SECRET=your_live_client_secret
PAYPAL_MODE=live
PAYPAL_WEBHOOK_ID=your_live_webhook_id

Clear the configuration cache:

php artisan config:clear

Supported Currencies

Ensure your Resrv currency configuration (resrv-config.currency_isoCode) uses a PayPal-supported currency.

Troubleshooting

Card fields not appearing

If only the PayPal button appears without card fields:

Verify Advanced Credit and Debit Card Payments (ACDC) is enabled in your PayPal app settings
Check browser console for JavaScript errors
Ensure your PayPal Client ID is correct

Payments not being captured

Ensure that:

Your PayPal API credentials are correct
The PAYPAL_MODE matches your credential type (sandbox/live)
Your server can make outbound HTTPS requests to PayPal's API

Webhook returns 403 error

This indicates webhook signature verification failed. Check that:

PAYPAL_WEBHOOK_ID is correctly set in your .env file
The webhook ID matches the webhook configured in your PayPal application
Your server time is synchronized (significant time drift can cause verification failures)

Webhook notifications not received

Verify that:

Your webhook URL is publicly accessible
Your server is not blocking PayPal's IP addresses
The webhook is enabled in your PayPal Developer Dashboard
You've subscribed to the correct events

"PayPal webhook ID is not configured" error

You must set the PAYPAL_WEBHOOK_ID environment variable. Webhooks are mandatory for this payment gateway to function properly.

JavaScript SDK fails to load

If you see "Failed to load PayPal SDK" error:

Check browser console for specific error messages
Verify your PAYPAL_CLIENT_ID is correct
Ensure your domain is not blocked by PayPal
Check for Content Security Policy issues

License

MIT License. See LICENSE for details.

reachweb / resrv-payment-paypal

Maintainers

Details