Skip to main content

​
Installation Methods

Laravel MercadoPago can be installed in two ways depending on your project structure and package distribution strategy.
Use this method when the package lives within your repository or in a sibling directory. Ideal for monorepo setups or local development.

​
Option A: Local Path Repository

This is the most direct approach when the package exists within your project structure.
1

Copy or clone the package

Place the package inside your Laravel project directory. A common convention is to use a plugins/ or packages/ folder:
my-laravel-app/
├── app/
├── config/
├── plugins/
│   └── laravel-mercadopago/
│       ├── src/
│       ├── config/
│       ├── routes/
│       └── composer.json
└── composer.json
2

Register the local repository

Add the path repository configuration to your project’s composer.json:
composer.json
{
    "repositories": [
        {
            "type": "path",
            "url": "plugins/laravel-mercadopago",
            "options": {
                "symlink": true
            }
        }
    ]
}
The symlink: true option creates a symbolic link instead of copying files, allowing you to edit the package code directly.
3

Install the package

Run Composer to require the package:
composer require fitodac/laravel-mercadopago:^1.0
Composer will use the local path and install the package via symlink.
4

Verify auto-discovery

Confirm that Laravel has registered the package provider and routes:
php artisan package:discover
Check that routes are registered:
php artisan route:list --name=mercadopago
You should see routes like:
  • POST api/mercadopago/webhooks
  • GET api/mercadopago/health (demo route)
  • GET api/mercadopago/payment-methods (demo route)
  • And more…

​
Option B: Versioned Package

If your project has access to the package from a Composer registry, private repository, or VCS source, installation is straightforward.
1

Install via Composer

Simply require the package with the desired version constraint:
composer require fitodac/laravel-mercadopago:^1.0
2

Verify installation

Confirm package discovery and route registration:
php artisan package:discover
php artisan route:list --name=mercadopago
With this method, you don’t need the repositories section in your composer.json. Composer will resolve the package from your configured sources.

​
Auto-Discovery

The package uses Laravel’s package auto-discovery feature. The service provider is automatically registered via the extra.laravel.providers key in the package’s composer.json:
composer.json
{
    "extra": {
        "laravel": {
            "providers": [
                "Fitodac\\LaravelMercadoPago\\LaravelMercadoPagoServiceProvider"
            ]
        }
    }
}
This means no manual provider registration is required in your config/app.php.

​
Registered Services

Once installed, the following services are available for dependency injection: 
use Fitodac\LaravelMercadoPago\Services\PreferenceService;

public function __construct(
    private PreferenceService $preferenceService
) {}
All services are registered as singletons in the service container:
  • PaymentMethodService
  • PreferenceService
  • PaymentService
  • RefundService
  • CustomerService
  • CardService
  • WebhookService
  • TestUserService

​
Verification

After installation, verify everything is working correctly:
1

Check package discovery

php artisan package:discover
Should output information about discovered packages including fitodac/laravel-mercadopago.
2

List registered routes

php artisan route:list --name=mercadopago
You should see the webhook route and demo routes (if enabled).
3

Check autoloading (optional)

If routes aren’t appearing, regenerate the autoloader:
composer dump-autoload
php artisan package:discover
php artisan route:list --name=mercadopago

​
Troubleshooting

​
Routes not appearing

If routes aren’t registered after installation: 
composer dump-autoload
php artisan package:discover
php artisan route:clear
php artisan route:list --name=mercadopago

​
Demo routes returning 404

Demo routes are only available when:
  1. MERCADOPAGO_ENABLE_DEMO_ROUTES=true in your .env
  2. Your APP_ENV is local or testing
In production environments, demo routes are always disabled regardless of configuration.
Demo routes are protected by the mercadopago.demo middleware and will return 404 in production even if enabled in configuration.

​
Next Steps

Configuration

Configure environment variables, publish the config file, and set up your Mercado Pago credentials.

Build docs developers (and LLMs) love

Get started for freeTalk to us