Download the PHP package srmklive/paypal without Composer

Laravel PayPal

A PayPal REST API package for Laravel, also usable as a standalone PHP client without any framework.

Supports: PHP 8.2–8.5 · Laravel 12 / 13

Disclaimer: This package is an independent community project and is not affiliated with, endorsed by, or supported by PayPal, Inc. "PayPal" is a registered trademark of PayPal, Inc. Use this package at your own risk; no warranty is provided beyond what the MIT license covers.

• Version Compatibility
• Moving to Orders v2 (v1 Payments API sunset Jan 2027)
• Installation
• Standalone Usage (without Laravel)
• Configuration
• Usage
• PayPal Fastlane
• Pay Upon Invoice (Buy Now, Pay Later — DE/AT)
• Subscription Helpers
• Billing Plans
  • BillingPlanBuilder
• Catalog Products
• Orders
• Payments
• Payouts
• Referenced Payouts
• Reference Transactions (Billing Agreements)
• Invoices
• Invoice Search
• Invoice Templates
• Subscriptions
• Disputes
• Dispute Actions
• Trackers
• Webhooks
• Payment Method Tokens
• Reporting
• Identity
• Partner Referrals
• Payment Experience

Version Compatibility

What's new in v3.1

• PHP 8.2+ and Laravel 12 / 13 required
• Standalone usage — no Laravel dependency required, pass credentials directly
• PSR-18 HTTP client — swap Guzzle for any compliant client via setClient()
• Configurable timeouts and retries — timeout, connect_timeout, max_retries in config
• Exception-based error handling — opt in with withExceptions() for PayPalApiException
• Local webhook verification — verifyWebHookLocally() with in-memory cert caching, no API roundtrip
• PayPal Fastlane — generateFastlaneClientToken() for one-click guest checkout
• Payment Method Tokens — full Vault v3 API (setup tokens, permanent tokens, Apple Pay, Google Pay)
• getCaptureIdFromOrder() — extract capture/transaction ID from order responses
• Bug fixes — float precision, URL encoding, null guards, invoice date normalization
• 100% test coverage with Pest v3/v4 and PHPStan level 7

Moving to Orders v2 (v1 Payments API sunset Jan 2027)

PayPal is sunsetting the v1 Payments REST API (/v1/payments/payment) in January 2027. If your integration uses the old create-payment → redirect → execute-payment flow, or the classic Billing Agreements API (/v1/billing-agreements/), you need to migrate before then.

This package already uses Orders v2 and Subscriptions v2 throughout. The migration notes below are for callers who built custom flows against the legacy endpoints or who were previously using the Express Checkout helpers from older versions.

Checkout: redirect-based payment flow

Recurring billing: Billing Agreements → Subscriptions

See the Subscription Helpers section for creating plans programmatically.

Installation

Publish the config file:

Standalone Usage (without Laravel)

The package has no hard dependency on Laravel — you can use it in any PHP project:

Instantiate the client and pass your credentials directly via setApiCredentials(). No service provider or .env file needed:

The facade and php artisan vendor:publish are Laravel-only conveniences; everything else works identically.

Configuration

Add to your .env:

The published config/paypal.php:

Usage

Initialization

Custom HTTP Client (PSR-18)

setClient() accepts any PSR-18 ClientInterface, so you can swap out Guzzle for Symfony HttpClient, Buzz, or any other compliant implementation:

Pass null (or call with no argument) to restore the default Guzzle client with the configured timeout and retry middleware.

Note: The built-in retry middleware runs only on the default Guzzle client. When you inject a custom client, handle retries in that client's own middleware stack.

Retry Behaviour

The default Guzzle client automatically retries failed requests up to max_retries times (default: 2) for:

• 5xx server errors — PayPal-side failures (500, 502, 503, …)
• 429 Too Many Requests — rate-limit responses; the Retry-After header (seconds or HTTP-date) is honoured up to 10 s. If PayPal asks to wait longer, the request is not retried and the 429 is returned to you
• Network/connection errors — DNS failures, connection refused, etc.

Only requests that are safe to resend are retried:

• GET, HEAD, PUT, DELETE and OPTIONS requests are always retried.
• POST and PATCH requests (create order, capture, refund, payouts, …) are retried only when they carry an idempotency key. Without one, a retry after a 5xx or timeout could make PayPal process the same capture or payout twice. Call withIdempotencyKey() before the request to make it retryable:

The delay between attempts uses exponential backoff (500 ms → 1 s → 2 s → 4 s, capped at 8 s) unless a Retry-After header overrides it. Set max_retries to 0 to disable retries entirely.

Override Configuration at Runtime

Get Access Token

Call this before any API method:

Set Currency

Partner Attribution ID (BN code)

PayPal uses the PayPal-Partner-Attribution-Id header to attribute transactions to a partner or platform. Set it once after initialisation — it persists for the lifetime of the provider instance:

All subsequent API calls will include the header automatically.

Error Handling

By default, API errors are returned as an array with an error key:

Opt in to exceptions with withExceptions(). All API errors will then throw PayPalApiException instead:

Call withoutExceptions() to revert to silent mode. Both methods are fluent.

PayPal Fastlane

PayPal Fastlane is a one-click guest checkout experience that pre-fills shipping and payment details for returning PayPal customers, typically delivering ~50% higher conversion on guest checkout flows.

Server role: generate a client token and handle Orders v2 create/capture. The Fastlane UI is rendered entirely by the PayPal JS SDK on the client.

1. Generate a client token (server-side)

2. Initialise Fastlane (client-side)

See PayPal's SDK setup and Fastlane documentation for the client-side integration.

3. Create & capture the order (server-side)

Pay Upon Invoice (Buy Now, Pay Later — DE/AT)

Pay Upon Invoice (Rechnungskauf) lets buyers in Germany and Austria pay after receiving goods. PayPal collects the payment and the merchant is paid upfront.

Requirements: DE/AT merchant account, buyer name, email, date of birth, phone number, and billing address.

Subscription Helpers

A fluent helper API for creating subscriptions without manually building plan/product payloads.

addPlanTrialPricing() and setReturnAndCancelUrl() are optional. Return/cancel URLs require real domains (not localhost).

Daily Subscription

Weekly / Monthly / Annual Subscription

Custom Interval

Use Existing Product & Billing Plan

Additional Options

Update Pricing Schemes for a Billing Plan

Billing Plans

BillingPlanBuilder

Building a billing plan payload by hand is error-prone — cycles need correct sequences, prices must be strings, and the nesting is deep. BillingPlanBuilder handles all of that:

With a trial period and setup fee:

Cycles are sequenced automatically in the order they are added. Use build() instead of create() to get the raw array without making an API call:

Available cycle methods:

totalCycles: 0 means the cycle repeats indefinitely.

Raw API

Catalog Products

Orders

Payments

Authorizations

Captures & Refunds

Eligible Payment Methods

Payouts

Referenced Payouts

Reference Transactions (Billing Agreements)

Note: This is a limited-release PayPal API. You must request access from PayPal before using it.

Invoices

Invoice Search

Available filters (chainable, call searchInvoices() at the end):

Invoice Templates

Subscriptions

Full CRUD for PayPal Subscriptions (distinct from the subscription helper methods above):

Disputes

Dispute Actions

Trackers

The transaction-id used here is the capture ID — get it via getCaptureIdFromOrder() after calling capturePaymentOrder() (see Orders).

For Orders v2 payments, prefer addTrackingForOrder($orderId, $data) (see Orders); PayPal has deprecated the batch endpoint behind addBatchTracking().

Webhooks

Local verification skips the PayPal verify API entirely. The signing certificate is fetched over HTTPS from the PAYPAL-CERT-URL on the first call, then cached in memory for the lifetime of the process — subsequent calls are pure in-memory RSA-SHA256 with no network I/O. Short-lived processes (serverless, etc.) will still fetch the cert on each cold start. The cert URL is validated against PayPal's known API domains before any request is made (SSRF guard).

Handling webhook events

After verification, parse the raw body into a typed WebhookEvent and route by event type:

You can also build from an already-decoded array:

Payment Method Tokens

Using the fluent helpers to create a token:

Reporting

Identity

Partner Referrals

Payment Experience

Testing

Use MockPayPalClient to write unit tests against your PayPal integration without hitting the sandbox API:

Queue multiple responses in order — one is consumed per API call:

Pass false as the body for empty-response operations (e.g. updateOrder, which returns 204):

Inspect what was sent to assert on headers, method, or payload:

If you need to inject the mock into a provider you've already constructed, pass it to setClient() directly — MockPayPalClient implements Psr\Http\Client\ClientInterface:

Maintained by Blendbyte

Blendbyte builds cloud infrastructure, web apps, and developer tools.
We've been shipping software to production for 20+ years.

This package runs in our own stack, which is why we keep it maintained.
Issues and PRs get read. Good ones get merged.

blendbyte.com · [email protected]