README

A fake PayPal API server for testing Laravel applications. It replaces the real PayPal client with a mock implementation that simulates the full checkout flow without hitting the PayPal API.

Installation

composer require --dev puntodev/paypal-fake

Activation

Set the environment variable in your .env or phpunit.xml:

PAYPAL_USE_FAKE=true

The service provider auto-registers and swaps the PayPal binding in the container with PayPalFake.

How It Works

The library has four main components:

PayPalFake

Extends PayPal and manages global test state. Stores orders in a file-based cache, records method calls for assertions, and provides a reset() method to clean up between tests.

PayPalFakeApi

Extends PayPalApi with mock implementations:

• createOrder(array $order) — Generates a fake order ID, stores it in cache, and returns the expected response structure.
• findOrderById(string $id) — Retrieves a stored order from cache.
• captureOrder(string $orderId) — Simulates payment capture. Throws a RequestException if the order was marked as declined.
• verifyIpn(string $querystring) — Always returns 'VERIFIED'.

FakeCheckoutController

Exposes HTTP routes that simulate PayPal's checkout UI:

PayPalFakeServiceProvider

When PAYPAL_USE_FAKE is true, it binds PayPalFake as a singleton in place of PayPal, registers the checkout routes, and loads the Blade views.

Checkout Flow

Your test creates an order via PayPalFakeApi::createOrder()
        ↓
Order is stored in file cache (300s TTL)
        ↓
Test or browser approves the order
        ↓
Webhook POSTed to /paypal/webhook/{providerId}
        ↓
Test captures payment via PayPalFakeApi::captureOrder()
        ↓
Assertions via PayPalFake::getCalls()

Usage

Automated Tests

use Puntodev\PaymentsFake\PayPalFake;
use Puntodev\Payments\PayPal;
use Puntodev\Payments\OrderBuilder;

// Get the fake client
$client = app(PayPal::class)->defaultClient();

// Create an order
$order = (new OrderBuilder())
    ->currency('USD')
    ->amount(25.00)
    ->make();

$created = $client->createOrder($order);

// Capture the payment
$captured = $client->captureOrder($created['id']);

// Assert calls were made
$calls = PayPalFake::getCalls('createOrder');
$this->assertCount(1, $calls);

// Clean up
PayPalFake::reset();

Manual Browser Testing

Start your Laravel app with PAYPAL_USE_FAKE=true and navigate to /paypal-fake/checkout/{orderId} after creating an order. The checkout page lets you click Approve, Decline, or Cancel to test the full flow, including webhooks hitting your application.

Test Helpers

Development

Code style is enforced with Laravel Pint (laravel preset, see pint.json). The test suite is fully isolated — it never reaches the network, so no PayPal credentials are required.

composer install
composer test            # run the test suite (vendor/bin/phpunit)
composer test-coverage   # generate an HTML coverage report under ./coverage
composer lint            # check code style (vendor/bin/pint --test) — this is what CI runs
composer format          # fix code style (vendor/bin/pint)

Please run composer format before opening a pull request. See CONTRIBUTING.md for the full contribution guide.

Requirements

• PHP >= 8.4
• Laravel 13+

Changelog

See CHANGELOG.md for the list of changes per version.

Releases are cut from GitHub's "Generate release notes" button (grouping configured in .github/release.yml). When a release is published, the update-changelog workflow writes its notes into CHANGELOG.md and commits them back to main.