reachweb / resrv-payment-paypal
PayPal payment gateway for Statamic Resrv
Package info
github.com/reachweb/resrv-paypal
Type:statamic-addon
pkg:composer/reachweb/resrv-payment-paypal
Requires
- php: ^8.4
- paypal/paypal-server-sdk: ^2.1
- reachweb/statamic-resrv: ^6.5 || dev-main
- statamic/cms: ^6.0
Requires (Dev)
- laravel/pint: ^1.17
- orchestra/testbench: ^10.0 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 19:11:27 UTC
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.4+
- Laravel 12.x or 13.x
- Statamic 6.x
- Statamic Resrv 6.5 or later
- PayPal Business Account with Advanced Credit and Debit Card Payments enabled (for card fields)
Upgrading from Resrv 5? This release targets Resrv's v6 multiple-payment-gateway system (
PaymentInterfacenow requiresname(),label(),paymentView(),supportsManualConfirmation(),cancelPaymentIntent()andsupportsAutomaticRefunds()). Tagged releases start at v1.0.0 and need Resrv 6.5 or later; there is no release for Resrv 5, so a Resrv 5 site has to stay on the last compatible commit:composer require reachweb/resrv-payment-paypal:dev-main#049bfa9.
Upgrading from 1.1.0
Resrv 6.6 checks with the gateway that a payment is cancelled before checkout starts another one.
1.1.0 reported an order the customer had left behind as still payable, so with Resrv 6.6, once a
customer picked PayPal at checkout, Change payment method and a coupon change showed "We could
not start the payment process". Upgrade with composer update reachweb/resrv-payment-paypal in the
same deploy as Resrv 6.6. 1.1.1 still works with Resrv 6.5, and nothing else changes.
Upgrading from 1.0.1
1.0.1 never requested 3-D Secure for card-field payments: it passed a Hosted Fields option that
Card Fields ignore, so a card payment got at most PayPal's default (authentication only where a
mandate such as PSD2 requires it), and it was captured without checking the authentication
result. Card payments now request 3-D Secure (see 3-D Secure). 1.0.1
also dropped trailing zeros from the amount on the card pay button: €316.80 read "Pay € 316.8".
Upgrade with composer update reachweb/resrv-payment-paypal. What changes for a site:
- Published payment view: if you ran
vendor:publish --tag=resrv-paypal-views, re-publish it (php artisan vendor:publish --tag=resrv-paypal-views --force) and re-apply your edits. The old copy pays cards on an order that never requested 3-D Secure, so its card payments are now refused (payments with the PayPal button keep working), and it keeps showing "€ 316.8". - Failed authentications are refused: a card whose cardholder fails or cannot complete the bank's check is not charged; the customer sees an error and can retry or pay with PayPal.
- New optional setting:
PAYPAL_SCA_METHOD(defaultSCA_WHEN_REQUIRED).
Upgrading from 1.0.0
v1.0.0 could not take payments: the payment view failed to render, and a refund PayPal rejected
was still recorded as refunded. Upgrade with composer update reachweb/resrv-payment-paypal.
What changes for a site:
- Published payment view: if you ran
vendor:publish --tag=resrv-paypal-views, re-publish it (php artisan vendor:publish --tag=resrv-paypal-views --force) and re-apply your edits. The old copy fails to render, and it returns customers to the checkout-complete page with a parameter 1.0.1 no longer accepts (see Customizing the Payment View). - Refunds PayPal rejects now fail: the Control Panel and customer self-cancellation show Resrv's refund-failed message and the reservation stays confirmed, instead of being marked refunded with no money returned.
config/services.phpis honoured: values under itspaypalkey now take precedence over thePAYPAL_*environment variables (see API Configuration).- Cancelled or paid-in-person pay-by-link bookings no longer keep a "payment unresolved" PayPal order or send admins an "open payment intent could not be cancelled" alert.
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.
You can configure the same four values under a paypal key in config/services.php instead
(client_id, client_secret, mode, webhook_id). A value set there takes precedence; the
PAYPAL_* environment variables fill in any it leaves out.
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
3-D Secure (card payments)
Card-field payments request 3-D Secure (Strong Customer Authentication) from PayPal. Choose when the cardholder's bank is asked to authenticate them:
PAYPAL_SCA_METHOD=SCA_WHEN_REQUIRED
SCA_WHEN_REQUIRED(default): only when a regional mandate such as PSD2 requires it, for example an EU merchant charging an EU-issued card. Other card payments go through without a challenge, and the chargeback liability stays with you.SCA_ALWAYS: every card payment the card and its bank support. More payments shift liability to the card issuer, at the cost of a challenge step for more customers. A card payment that PayPal reports with no authentication result at all is refused under this setting.
The setting lives in config/resrv-paypal.php (sca_method). PayPal wallet payments are not
affected: PayPal authenticates those itself.
When PayPal reports the authentication result, the gateway follows
PayPal's recommended actions:
the card is charged when liability shifted (POSSIBLE), when the card or its bank does not take
part in 3-D Secure, or when no authentication was needed. It is not charged when the
cardholder failed or could not complete authentication (liability_shift NO on an enrolled
card), when the authentication system was unavailable (UNKNOWN), or when the card was paid on an
order that never requested 3-D Secure (for example from an outdated published payment view); the
customer sees an error and can try again or pay with PayPal.
A blank or unrecognised PAYPAL_SCA_METHOD falls back to SCA_WHEN_REQUIRED and logs a warning.
To test in sandbox, use PayPal's
3-D Secure test cards.
The US cards may not be challenged under SCA_WHEN_REQUIRED (no mandate applies to them), so set
PAYPAL_SCA_METHOD=SCA_ALWAYS while testing, or use the cards for your own region.
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:
- If you registered PayPal under
payment_gateways(multiple gateways), use the per-gateway route whose segment matches your config key:https://yoursite.com/resrv/api/webhook/paypal - If PayPal is your single gateway (legacy
payment_gatewaykey), the barehttps://yoursite.com/resrv/api/webhookroute also works
- If you registered PayPal under
- Subscribe to these events:
PAYMENT.CAPTURE.COMPLETEDPAYMENT.CAPTURE.DENIEDPAYMENT.CAPTURE.REFUNDED
- Save the webhook and copy the Webhook ID
- Add the Webhook ID to your
.envfile:
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
Register the gateway in your config/resrv-config.php. Resrv 6 supports multiple gateways, so the
recommended approach is to add PayPal to the payment_gateways array (the array key — paypal here —
is stored on each reservation and used in the per-gateway webhook URL, so keep it lowercase, stable,
and never change it once reservations exist):
'payment_gateways' => [ 'paypal' => [ 'class' => Reach\ResrvPaymentPaypal\Http\Payment\PaypalPaymentGateway::class, 'label' => 'PayPal', // Optional, handled entirely by Resrv core (no gateway code changes needed): // 'surcharge' => ['type' => 'percent', 'amount' => 3], // 'amount_limits' => ['min' => 5, 'max' => 2000], ], // 'stripe' => [ // 'class' => Reach\StatamicResrv\Http\Payment\StripePaymentGateway::class, // ], ],
If PayPal is your only gateway you can instead use the legacy singular key:
'payment_gateway' => Reach\ResrvPaymentPaypal\Http\Payment\PaypalPaymentGateway::class,
Refunds & Customer Cancellations
Refunds (from the Control Panel or via Resrv's customer self-cancellation feature) always return
the full captured amount — the reservation payment plus any gateway surcharge, exactly what the
customer was charged. The refund call is idempotent (a stable PayPal-Request-Id per reservation
and capture), so a retry after a network failure never double-refunds; and if the capture turns out
to be already fully refunded (e.g. refunded manually in the PayPal dashboard), the reservation is
still marked refunded instead of getting stuck.
If PayPal refuses the refund (for example an insufficient PayPal balance, wrong credentials, or a PayPal outage), the refund fails: the Control Panel or the customer sees Resrv's refund-failed message, the reservation stays confirmed, and the PayPal error is logged. Nothing is marked refunded until PayPal accepts the refund.
Because the gateway reports supportsAutomaticRefunds() === true, customers may cancel eligible
reservations themselves from the reservation status page when you enable Resrv's customer
cancellation feature.
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/resrv-paypal/livewire/checkout-payment.blade.php.
When you customize it, keep the script's contract with the server:
- The card fields'
createOrdermust get its order fromPOST /resrv-paypal/order/{orderId}/card(with the current order id), which creates the card order that carries the 3-D Secure request. A card paid on the order the page was mounted with is refused at capture. The PayPal button pays the mounted order on checkout; after a card attempt, and on the pay-by-link page (which can resume a card order), it gets a wallet order fromPOST /resrv-paypal/order/{orderId}/paypal. - Either order route can answer with a capture result (
status,captureId) instead of a new orderid: the current order had already been captured by an attempt whose response was lost. Finish exactly as after a capture, and do not hand the SDK an order. - A 403 from an order route means the page's order id is no longer the reservation's (for example
a replacement that went through but whose response was lost). Do not retry with that id, or hand
it to the PayPal button, until you know the current one: on the pay-by-link page call
$wire.pay()and use the new$wire.clientSecret; on checkout ask the customer to reload. - After a successful capture, return the customer to
checkoutCompletedUrlwith thecapture_idfrom the capture response (plusresrv_gatewayandredirect_status). The checkout-complete page looks the reservation up by that capture id; it does not accept a reservation id. - Blade compiles every
{{ ... }}in the file, including ones inside JavaScript comments, so each must be a valid PHP expression; anything else (such as an Antlers tag name) makes the whole view fail to render. Write@{{ ... }}when you need literal braces.
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
.envfile 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_MODEmatches 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_IDis correctly set in your.envfile- 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_IDis correct - Ensure your domain is not blocked by PayPal
- Check for Content Security Policy issues
License
MIT License. See LICENSE for details.