PHPackages                             puntodev/mercadopago-fake - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. puntodev/mercadopago-fake

ActiveLibrary[Testing & Quality](/categories/testing)

puntodev/mercadopago-fake
=========================

Fake MercadoPago API Client for testing

0.0.1(1mo ago)01↑2900%MITPHPPHP >=8.4 <9.0CI passing

Since Mar 29Pushed 1mo agoCompare

[ Source](https://github.com/puntodev/mercadopago-fake)[ Packagist](https://packagist.org/packages/puntodev/mercadopago-fake)[ Docs](https://github.com/puntodev/mercadopago-fake)[ RSS](/packages/puntodev-mercadopago-fake/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (2)Used By (0)

mercadopago-fake
================

[](#mercadopago-fake)

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

Installation
------------

[](#installation)

```
composer require --dev puntodev/mercadopago-fake
```

Activation
----------

[](#activation)

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

```
MERCADOPAGO_USE_FAKE=true

```

The service provider auto-registers and swaps the `MercadoPago` binding in the container with `MercadoPagoFake`.

How It Works
------------

[](#how-it-works)

The library has four main parts:

### MercadoPagoFake

[](#mercadopagofake)

Implements `MercadoPago` and manages global test state. Stores preferences, payments, and merchant orders in a file-based cache, records method calls for assertions, and provides a `reset()` method to clean up between tests.

### MercadoPagoFakeApi

[](#mercadopagofakeapi)

Implements `MercadoPagoApi` with mock implementations:

- `createPaymentPreference(array $order)` — Generates a fake preference ID, stores it in cache, and returns the expected response structure including `init_point` and `sandbox_init_point`.
- `findMerchantOrders(array $query)` — Returns an empty list of merchant orders.
- `findMerchantOrderById(string $id)` — Retrieves a stored merchant order. Throws a `RequestException` if not found.
- `findPayments(array $query)` — Returns an empty list of payments.
- `findPaymentById(string $id)` — Retrieves a stored payment. Throws a `RequestException` if not found.

### FakeCheckoutController

[](#fakecheckoutcontroller)

Exposes HTTP routes that simulate MercadoPago's checkout UI:

MethodRouteDescriptionGET`/mercadopago-fake/checkout/{preferenceId}`Displays a styled checkout page with Pay, Decline, and Cancel buttonsPOST`/mercadopago-fake/checkout/{preferenceId}/approve`Simulates approval and posts a webhook (IPN) to your app's `notification_url`POST`/mercadopago-fake/checkout/{preferenceId}/decline`Marks the payment as declined and redirects to the failure URLGET`/mercadopago-fake/checkout/{preferenceId}/cancel`Redirects to the failure back URL### MercadoPagoFakeServiceProvider

[](#mercadopagofakeserviceprovider)

When `MERCADOPAGO_USE_FAKE` is `true`, it binds `MercadoPagoFake` as a singleton in place of `MercadoPago`, registers the checkout routes, and loads the Blade views.

Checkout Flow
-------------

[](#checkout-flow)

```
Your test creates a preference via MercadoPagoFakeApi::createPaymentPreference()
        |
Preference is stored in file cache (300s TTL)
        |
Test or browser approves the payment
        |
Webhook (IPN) POSTed to the preference's notification_url
        |
Redirect to back_urls with collection_id, status, preference_id, etc.
        |
Assertions via MercadoPagoFake::getCalls()

```

Usage
-----

[](#usage)

### Automated Tests

[](#automated-tests)

```
use Puntodev\MercadoPagoFake\MercadoPagoFake;
use Puntodev\MercadoPago\MercadoPago;
use Puntodev\MercadoPago\PaymentPreferenceBuilder;

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

// Create a payment preference
$order = (new PaymentPreferenceBuilder())
    ->item()
    ->title('Test Product')
    ->unitPrice(25.00)
    ->quantity(1)
    ->currency('ARS')
    ->make()
    ->payerFirstName('John')
    ->payerLastName('Doe')
    ->payerEmail('john@example.com')
    ->notificationUrl('https://example.com/mp/ipn/1')
    ->externalId('order-123')
    ->successBackUrl('https://example.com/success')
    ->make();

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

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

// Clean up
MercadoPagoFake::reset();
```

### Manual Browser Testing

[](#manual-browser-testing)

Start your Laravel app with `MERCADOPAGO_USE_FAKE=true` and navigate to the `init_point` URL returned by `createPaymentPreference()`. The checkout page lets you click Pay, Decline, or Cancel to test the full flow, including IPN webhooks hitting your application.

### Test Helpers

[](#test-helpers)

MethodDescription`MercadoPagoFake::storePreference($id, $preference)`Store a preference in the fake cache`MercadoPagoFake::getStoredPreference($id)`Retrieve a stored preference`MercadoPagoFake::storePayment($id, $payment)`Store a payment in the fake cache`MercadoPagoFake::getStoredPayment($id)`Retrieve a stored payment`MercadoPagoFake::storeMerchantOrder($id, $order)`Store a merchant order in the fake cache`MercadoPagoFake::getStoredMerchantOrder($id)`Retrieve a stored merchant order`MercadoPagoFake::markPaymentAsDeclined($id)`Mark a payment as declined`MercadoPagoFake::isPaymentDeclined($id)`Check if a payment is declined`MercadoPagoFake::recordCall($method, $args)`Record a method call`MercadoPagoFake::getCalls($method)`Get recorded calls, optionally filtered by method`MercadoPagoFake::reset()`Clear all stored state and recorded callsRequirements
------------

[](#requirements)

- PHP >= 8.4
- Laravel 12+
- `puntodev/mercadopago` ^v6.0

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance90

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7201db0e06c12ae2e12e1cf4ee5806b5b465dc538bee3cab6bfb1c0ec52e4dce?d=identicon)[Mariano Goldman](/maintainers/Mariano%20Goldman)

---

Top Contributors

[![marianogoldman](https://avatars.githubusercontent.com/u/959563?v=4)](https://github.com/marianogoldman "marianogoldman (2 commits)")

---

Tags

testingfakemercadopagopuntodev

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/puntodev-mercadopago-fake/health.svg)

```
[![Health](https://phpackages.com/badges/puntodev-mercadopago-fake/health.svg)](https://phpackages.com/packages/puntodev-mercadopago-fake)
```

###  Alternatives

[timacdonald/log-fake

A drop in fake logger for testing with the Laravel framework.

4235.9M56](/packages/timacdonald-log-fake)[laracasts/testdummy

Easy test stubs

4671.4M36](/packages/laracasts-testdummy)[sti3bas/laravel-scout-array-driver

Array driver for Laravel Scout

971.5M3](/packages/sti3bas-laravel-scout-array-driver)[laravel-shift/factory-generator

Generate factories from existing models

49697.9k](/packages/laravel-shift-factory-generator)[luthfi/simple-crud-generator

A simple CRUD generator for Laravel 5.5 (and later) with Bootstrap 5.

17218.4k](/packages/luthfi-simple-crud-generator)[timacdonald/callable-fake

A testing utility that allows you to fake and capture invokations of a callable / Closure

4519.5k3](/packages/timacdonald-callable-fake)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)