Installation

Install Laravel MercadoPago using Composer with local path repository or versioned package approaches.

Installation Methods

Laravel MercadoPago can be installed in two ways depending on your project structure and package distribution strategy.

Local Path Repository

Use this method when the package lives within your repository or in a sibling directory. Ideal for monorepo setups or local development.

Versioned Package

Use this method when the package is available from a Composer registry, private repository, or VCS source.

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:

PreferenceService

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.