srmklive/paypal

Eight new features landed since 3.1.0, all fully backward-compatible. No removed methods, no signature changes, nothing to migrate.

429 handling with Retry-After (#674)

The retry middleware now handles 429 Too Many Requests. When PayPal sends a Retry-After header the delay respects it exactly; without it, the existing exponential backoff kicks in (500ms, 1s, 2s, up to 8s). Nothing to configure.

WebhookEvent value object (#676)

Typed readonly wrapper around PayPal webhook payloads:

use Srmklive\PayPal\Events\WebhookEvent;

$event = WebhookEvent::fromRawBody($request->getContent());

if ($event->is('PAYMENT.CAPTURE.COMPLETED')) {
    $captureId = $event->resource['id'];
}

Fields: id, eventType, resourceType, summary, createTime, resource, rawPayload.

Transaction reporting helpers (#678)

Four wrappers on top of listTransactions() for the common cases:

// Single transaction by ID, looks back up to 31 days
$tx = $provider->getTransactionDetails('5TY05013RG002845M');

// Date range shorthand, no manual ISO 8601 formatting needed
$txns = $provider->listTransactionsForDateRange('2025-01-01', '2025-01-31');

// Filter by PayPal transaction type code
$txns = $provider->listTransactionsByType('T0006', '2025-01-01', '2025-01-31');

// Filter by status (S = success, P = pending, etc.)
$txns = $provider->listTransactionsByStatus('S', '2025-01-01', '2025-01-31');

Subscription lifecycle helpers (#675)

// Alias for activateSubscription() with a sensible default reason
$provider->reactivateSubscription($subscriptionId);

// True only when status === 'ACTIVE'
if ($provider->isSubscriptionActive($subscriptionId)) { ... }

MockPayPalClient (#672)

A public MockPayPalClient lives at Srmklive\PayPal\Testing\MockPayPalClient. Queue responses in tests without touching the sandbox:

use Srmklive\PayPal\Testing\MockPayPalClient;

$client = new MockPayPalClient($credentials);
$client->addResponse(201, ['id' => 'ORDER-123', 'status' => 'CREATED']);

$order = $client->createOrder([...]);
// $client->requests() to inspect what was sent

BillingPlanBuilder (#673)

Fluent builder for billing plan payloads. Covers all cycle types, trial pricing, and payment preferences:

use Srmklive\PayPal\Services\BillingPlanBuilder;

$plan = BillingPlanBuilder::make('Pro Plan', 'PROD-ABC123')
    ->trialCycle(days: 14, price: 0)
    ->monthlyPrice(29.99)
    ->build();

$response = $provider->createBillingPlan($plan);

setPartnerAttributionId() (#677)

Set the PayPal-Partner-Attribution-Id BN code once after initialisation and it sticks for all subsequent requests from that instance:

$provider->setPartnerAttributionId('YourBNCode_Cart');

Pay Upon Invoice / BNPL for DE/AT (#679)

setPaymentSourcePayUponInvoice() joins the existing payment source setters. Available for merchants in Germany and Austria:

$provider->setPaymentSourcePayUponInvoice([
    'name'            => ['given_name' => 'John', 'surname' => 'Doe'],
    'email'           => '[email protected]',
    'birth_date'      => '1990-01-01',
    'phone'           => ['country_code' => '49', 'national_number' => '1234567890'],
    'billing_address' => [
        'address_line_1' => 'Hauptstraße 1',
        'admin_area_2'   => 'Berlin',
        'postal_code'    => '10115',
        'country_code'   => 'DE',
    ],
    'experience_context' => [
        'locale'     => 'de-DE',
        'return_url' => 'https://example.com/paypal-success',
        'cancel_url' => 'https://example.com/paypal-cancel',
    ],
]);

$order = $provider->createOrderWithPaymentSource([
    'intent'         => 'CAPTURE',
    'purchase_units' => [['amount' => ['currency_code' => 'EUR', 'value' => '99.00']]],
]);

Upgrading

composer update srmklive/paypal

No code changes required.

New maintainership

Starting with v3.1, Blendbyte is taking over active maintenance of srmklive/paypal. We're a cloud infrastructure and software development company that builds and operates Laravel applications for our own products and for clients. This package has been a dependency in our stack for years across dozens of projects, so when the opportunity came up to take over maintainership we didn't think twice. We're stoked to give it the attention it deserves.

A huge thank you to @srmklive for building and maintaining this package across 110+ releases and nearly 4 million Packagist installs. His work gave the Laravel ecosystem a reliable PayPal integration for years, and we're grateful for the trust he's placed in us to carry it forward. He'll stay on as a contributor.

Highlights

This release is fully backward-compatible with v3.0. No API changes, no removed methods, no migration needed. If your project runs on PHP 8.2+ and Laravel 12, composer update picks this up automatically.

Platform support

• PHP 8.2 through 8.5 (aligned with Laravel 12's own floor; PHP 8.2 is in security support until Dec 2026)
• Laravel 12 and 13
• Standalone usage without Laravel: pass credentials directly to setApiCredentials(), no service provider needed

New features

• PSR-18 HTTP client support. Swap Guzzle for any compliant client via setClient().
• Configurable timeouts and retry. New timeout, connect_timeout, max_retries config keys with exponential backoff on 5xx and network errors.
• Exception-based error handling. Call withExceptions() to get PayPalApiException with getHttpStatus() and getPayPalError() instead of error arrays. Fully opt-in, existing code keeps working.
• Local webhook verification. verifyWebHookLocally() does in-memory RSA-SHA256 with cert caching. No PayPal API roundtrip, SSRF-guarded cert URL validation.
• PayPal Fastlane. generateClientToken() for one-click guest checkout flows.
• Vault v3 complete. deletePaymentSetupToken(), setCustomerId(), full setup and permanent token lifecycle.
• Apple Pay, Google Pay, and ACDC card helpers. setPaymentSourceApplePay(), setPaymentSourceGooglePay(), setCardBillingAddress(), setCardVaulting(), setCardVerification().
• getCaptureIdFromOrder(). Extract the capture/transaction ID from order responses in one call.
• createOrderWithPaymentSource(). Create orders with an attached payment source directly.
• sendDisputeMessage(). Send messages in dispute conversations.
• withIdempotencyKey(). Set idempotency keys for safe request retries.
• setShippingAddressChangeCallback(). Server-side shipping callbacks for Orders v2.

Bug fixes

• Monetary amounts now serialize as 2-decimal strings, preventing float noise like 49.990000000000002
• generateInvoiceNumber() sends an empty JSON body to prevent 415 Unsupported Media Type from PayPal
• Moved experience_context from deprecated application_context to payment_source.paypal.experience_context
• Aligned setStoredPaymentSource() with PayPal's Feb 2025 API change (usage renamed to usage_pattern)
• Removed sanctioned currency (RUB) from currency list, sorted alphabetically, improved error messages
• validate_ssl=false was silently ignored because empty() treated false as empty
• listTrackingDetails(), listUsers() SCIM filter, and query params now properly URL-encoded
• addInvoiceFilterByDateRange() normalizes dates to Y-m-d
• verifyIPN() and json_decode results properly guarded against null
• previous_network_transaction_reference strips null values instead of sending them to PayPal
• Fixed stray leading slash in provideDisputeEvidence() endpoint; acceptDisputeClaim() no longer overwrites caller's accept_claim_type
• listPaymentSourceTokens() throws RuntimeException when called without a customer ID
• Local webhook verification retries on certificate fetch failure
• makeHttpRequest() no longer drops auth and form_params on the PSR-18 code path

Code quality

• 100% test coverage with Pest v4 and PHPUnit 12
• PHPStan level 8
• Laravel Pint formatting across the entire codebase
• PHP 8.2 through 8.5 CI matrix via GitHub Actions
• Removed dead code, unused Docker files, and legacy CI configs
• Replaced collect() and Illuminate\Support\Str calls with native PHP where possible
• Deprecated PaymentExperienceWebProfiles (PayPal deprecated /v1/payment-experience/web-profiles)
• Dropped ext-curl hard requirement

Upgrading from v3.0

composer require srmklive/paypal:^3.1

No code changes needed. All existing method signatures and return types are preserved. The three new config keys (timeout, connect_timeout, max_retries) have sensible defaults and are fully optional. Your existing config/paypal.php works as-is.

What's Changed

• Add order tracking endpoint by @DMollov in #648
• fix: zulu timestamp for listBalances by @btwlouis in #652
• Laravel v12 Support by @sajjadhossainshohag in #657

New Contributors

• @DMollov made their first contribution in #648
• @btwlouis made their first contribution in #652
• @sajjadhossainshohag made their first contribution in #657

Full Changelog: 3.0.32...3.0.40

What's Changed

• Fix price format for @addSetupFee by @otnansirk in #639
• Only set subscription start_time if passed by @willcurry in #640

New Contributors

• @willcurry made their first contribution in #640

Full Changelog: 3.0.30...3.0.31

What's Changed

• Add lang it by @matheo-2001 in #609
• Add lang de by @matheo-2001 in #610
• Add lang ar by @matheo-2001 in #611
• Add lang es by @matheo-2001 in #612
• Add lang ja by @matheo-2001 in #613
• Add lang hu by @matheo-2001 in #614
• Add lang cn by @matheo-2001 in #615
• Add custom id for invoice id by @buzzclue in #603
• Add billing_plan_id and product_id after creating recurring subscriptions by @otnansirk in #619
• fix : add error handler for addProduct and addBillingPlan from subscription helper by @otnansirk in #623
• Laravel 11.x Compatibility by @laravel-shift in #625

New Contributors

• @matheo-2001 made their first contribution in #609
• @buzzclue made their first contribution in #603
• @otnansirk made their first contribution in #619

Full Changelog: 3.0.28...3.0.30

What's Changed

• Removed extra slash from api url (live mode) by @korkoshko in #397
• V2.0 by @BGaeteAlvear in #454
• Merge v3 into v2 by @srmklive in #481
• Apply fixes from StyleCI by @srmklive in #587
• Add lang it by @matheo-2001 in #609
• Add lang de by @matheo-2001 in #610
• Add lang ar by @matheo-2001 in #611
• Add lang es by @matheo-2001 in #612
• Add lang ja by @matheo-2001 in #613
• Add lang hu by @matheo-2001 in #614
• Add lang cn by @matheo-2001 in #615
• Add custom id for invoice id by @buzzclue in #603
• Apply fixes from StyleCI by @srmklive in #621
• Add billing_plan_id and product_id after creating recurring subscriptions by @otnansirk in #619
• fix : add error handler for addProduct and addBillingPlan from subscription helper by @otnansirk in #623
• Laravel 11.x Compatibility by @laravel-shift in #625
• fix : add bcdiv for Helpers.php@addSetupFee by @otnansirk in #639
• Only set subscription start_time if passed by @willcurry in #640
• V3 v2 by @srmklive in #644

New Contributors

• @korkoshko made their first contribution in #397
• @BGaeteAlvear made their first contribution in #454
• @matheo-2001 made their first contribution in #609
• @buzzclue made their first contribution in #603
• @otnansirk made their first contribution in #619
• @willcurry made their first contribution in #640

Full Changelog: 2.0.20...2.0.30

What's Changed

• Support nesbot/carbon:~3.0 in v1.0 by @toyi in #642

Full Changelog: 1.11.10...1.11.11