Download the PHP package leonardganyire/paypal without Composer

PayPal for Laravel

A frontend-agnostic Laravel package for PayPal Checkout Orders v2. It handles OAuth authentication, access-token caching, order creation, order capture, authorization, refunds, order lookup, approval URL extraction, and webhook signature verification.

Your application still owns the payment model, routes, controllers, validation, fulfillment, and frontend. That keeps this package usable from Blade, Livewire, Inertia, a standalone React app, a mobile app, or any other client that can talk to your Laravel backend.

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13
• A PayPal REST app from the PayPal Developer Dashboard

Installation

Install the package with Composer:

Laravel auto-discovers the service provider and facade. You may publish the config if you want to customize the defaults:

Configuration

Add your PayPal REST app credentials to .env:

Configuration notes:

• PAYPAL_MODE should be sandbox while testing and live in production.
• PAYPAL_CLIENT_ID is safe to expose to a browser only when you need to load PayPal's JavaScript SDK. The backend still needs the same value for OAuth.
• PAYPAL_CLIENT_SECRET must stay server-side. Never send it to React, Inertia props, mobile apps, logs, or public config.
• PAYPAL_WEBHOOK_ID is required only when you call verifyWebhookSignature().
• PAYPAL_BASE_URL is usually not needed. If it is empty, the package resolves https://api-m.sandbox.paypal.com for sandbox and https://api-m.paypal.com for live.

Access tokens are cached automatically. The cache lifetime follows PayPal's expires_in value minus PAYPAL_ACCESS_TOKEN_LEEWAY, so tokens are refreshed shortly before they expire. PAYPAL_ACCESS_TOKEN_TTL is only used as a fallback when PayPal does not return a usable expiry value. When PayPal returns 401, the package clears the cached token so the next request can authenticate again.

What The Package Provides

Resolve LeonardGanyire\Paypal\PayPalClient from the container or use the PayPal facade:

Dependency injection is preferred for application code:

Available methods:

• createOrder(array $payload, ?string $idempotencyKey = null): array
• captureOrder(string $orderId): array
• authorizeOrder(string $orderId): array
• getOrder(string $orderId): array
• refundCapture(string $captureId, ?array $payload = null): array
• verifyWebhookSignature(array $headers, array $payload): bool
• approvalUrl(array $orderResponse): ?string

Checkout Architecture

For one-time payments, your application should usually follow this flow:

1. The customer starts checkout in your app.
2. Your Laravel backend creates a local pending payment record.
3. Your Laravel backend calls createOrder() with server-trusted amount and currency values.
4. Your app either redirects the customer to PayPal or returns the PayPal order ID to React Smart Buttons.
5. After buyer approval, your Laravel backend calls captureOrder().
6. Your app marks the local payment as paid only after PayPal confirms COMPLETED.
7. Webhooks act as a recovery path for missed redirects, closed browser tabs, and asynchronous payment events.

Do not trust the amount, currency, user ID, order owner, or product price sent by the browser. Use browser input only to identify the cart/order the authenticated user is trying to pay for, then calculate payable totals on the server.

Example App Structure

The package does not create database tables. A host app normally has a payment or transaction model with columns like these:

Your model might look like this:

Replace this with your own domain model. For example, a course app might call this an EnrollmentPayment, while an ecommerce app might link it to an Order.

Laravel Routes

For a web or Inertia checkout flow:

For a separate frontend, put equivalent endpoints in routes/api.php and protect them with your chosen authentication strategy, commonly Sanctum or bearer tokens:

Create A PayPal Order

This example creates a local pending payment, creates a PayPal order, stores PayPal's order ID, and returns either JSON or a redirect depending on how the endpoint was called.

Important details:

• Pass a local payment ID as the idempotency key so retries do not create duplicate PayPal orders.
• Store PayPal's order ID in provider_reference.
• Return paypal_order_id to React Smart Buttons.
• Return or redirect to approval_url for redirect checkout.
• Keep the final amount calculation on the backend.

Redirect Checkout

Redirect checkout is the simplest integration. Your UI submits to payments.paypal.orders.store with mode=redirect; the controller sends the customer to PayPal's approval URL.

When the buyer approves, PayPal redirects to your return_url with a token query parameter. The token is the PayPal order ID. Always compare it with the value stored on your local payment before capture:

Handle cancellation separately:

Capture Endpoint For React

When you use PayPal Smart Buttons, the browser opens the PayPal approval popup. After approval, your frontend must ask Laravel to capture the order.

Inertia + React Smart Buttons

Install PayPal's React package in your Laravel frontend:

Expose only the public PayPal client ID to the page. For example:

Then render PayPal buttons from your Inertia page. In an application that uses Laravel Wayfinder, prefer generated route functions from @/actions or @/routes instead of hard-coded strings.

Notes for Inertia apps:

• Keep the frontend amount display informational; the backend should calculate and send the PayPal amount.
• If you use Wayfinder, replace the string URLs with generated imports from @/actions/... or @/routes/....
• If your PayPal buttons do not render, confirm the script provider includes components: 'buttons'.
• You can use Inertia navigation after capture, but the PayPal callbacks themselves are plain JavaScript callbacks, so fetch() is often the clearest option.

Standalone React Frontend

A standalone React, Next.js, Vite, or mobile frontend uses the same backend endpoints, but it must handle authentication, CORS, and CSRF according to your Laravel API setup.

Install PayPal's React package:

Use a public environment variable for the PayPal client ID:

Example React component:

Standalone frontend checklist:

• Configure Laravel CORS to allow the frontend origin.
• If using Sanctum cookie auth, call /sanctum/csrf-cookie before the first state-changing request and send credentials: 'include'.
• If using token auth, send an Authorization: Bearer ... header.
• Keep PAYPAL_CLIENT_SECRET only in Laravel.
• Do not let the frontend choose the final amount. Send an order/cart ID and let Laravel calculate the PayPal purchase unit.

Refunds

After a successful capture, store the capture ID from PayPalOrderStatus::captureReference($capture). Use it for refunds.

Your application should also store refund state locally and prevent refunding more than the captured amount.

Authorize Now, Capture Later

If your business flow needs authorization first and capture later, create the order with intent set to AUTHORIZE and call authorizeOrder() after approval:

This package does not currently provide a separate "capture authorization" helper. If you need that flow, add the missing endpoint in your app or extend the package.

Get An Order

Use getOrder() when you need to reconcile state with PayPal:

This is useful for admin troubleshooting, webhook reconciliation, or checking an order before attempting capture.

Webhooks

Webhooks are important, but they should not be your only completion path. Use them to recover from missed redirects, closed tabs, delayed events, and asynchronous updates.

In the PayPal Developer Dashboard, create a webhook pointing to your Laravel route, for example:

Select the events your app needs. Common one-time checkout events include:

• CHECKOUT.ORDER.APPROVED
• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.REFUNDED
• PAYMENT.CAPTURE.REVERSED

Webhook controller example:

Exclude the webhook route from CSRF verification in bootstrap/app.php:

Webhook handling tips:

• Verify the webhook signature before trusting any payload fields.
• Make webhook processing idempotent. PayPal may retry events.
• Store enough local state to ignore duplicate events safely.
• Return a 2xx response after successful processing so PayPal does not keep retrying.

Status Mapping

Use PayPalOrderStatus to interpret PayPal responses without coupling your app to raw PayPal status strings:

Supported statuses are CREATED, SAVED, APPROVED, PAYER_ACTION_REQUIRED, VOIDED, and COMPLETED.

Error Handling

All PayPal API failures throw LeonardGanyire\Paypal\Exceptions\PayPalException:

The exception exposes:

• $exception->getMessage() for a human-readable message.
• $exception->status() for the HTTP status your app can return, defaulting to 502.
• $exception->errorCode() for a stable application-level error code.
• $exception->details() for safe PayPal error metadata such as status, name, message, and debug_id.

Configuration errors, such as missing credentials or an invalid base URL, also throw PayPalException before a PayPal request is made.

Security Checklist

• Keep PAYPAL_CLIENT_SECRET server-side only.
• Calculate payment amounts on the backend from trusted order/cart records.
• Authorize access to local orders and payments before creating or capturing PayPal orders.
• Verify the returned PayPal order ID matches your stored provider_reference.
• Use idempotency keys when creating PayPal orders.
• Treat webhooks as untrusted until verifyWebhookSignature() returns true.
• Make capture and webhook handlers idempotent so duplicate requests do not double-fulfill orders.
• Store PayPal debug_id values from exceptions when you need support or reconciliation.

What This Package Does Not Include

The following are intentionally left to your host app:

• Payment, order, transaction, refund, or subscription models and migrations.
• Checkout, return, cancel, capture, refund, or webhook controllers and routes.
• Authorization policies for your orders and payments.
• Order fulfillment logic such as enrollment, shipping, invoicing, or receipt emails.
• React, Inertia, Blade, Livewire, Vue, mobile, or other frontend components.
• PayPal Billing Subscriptions and recurring billing APIs.

Testing

Run the package test suite:

In your host app, fake PayPal HTTP calls with Laravel's HTTP fake:

Example Pest assertion for your host app:

License

MIT