Skip to main content
This guide will walk you through installing the package, configuring credentials, and creating your first payment preference.

​
Prerequisites

Before you begin, ensure you have:
  • PHP ^8.2
  • Laravel ^12.0
  • A MercadoPago account with API credentials

​
Installation

1

Install the package

Add the package to your Laravel project using Composer:
composer require fitodac/laravel-mercadopago:^1.0
The package uses Laravel’s auto-discovery, so the service provider will be registered automatically.
2

Verify package registration

Confirm the package is installed and routes are registered:
php artisan package:discover
php artisan route:list --name=mercadopago
You should see routes like mercadopago.preferences.store and mercadopago.webhooks.store.
3

Publish configuration (optional)

If you want to customize the configuration file:
php artisan vendor:publish --tag=mercadopago-config
This creates config/mercadopago.php in your project.
4

Configure environment variables

Add your MercadoPago credentials to .env:
MERCADOPAGO_ACCESS_TOKEN=your_access_token_here
MERCADOPAGO_PUBLIC_KEY=your_public_key_here
MERCADOPAGO_WEBHOOK_SECRET=your_webhook_secret_here
MERCADOPAGO_ENABLE_DEMO_ROUTES=true
Never commit real credentials to your repository. Keep them in .env and add .env to .gitignore.
5

Test the configuration

Verify your credentials are properly configured:
curl http://localhost:8000/api/mercadopago/health
Expected response:
{
  "ok": true,
  "data": {
    "configured": true,
    "has_public_key": true,
    "has_webhook_secret": true,
    "environment": "local"
  },
  "meta": []
}
6

Create your first preference

Use the demo endpoint to create a payment preference:
curl --request POST \
  --url http://localhost:8000/api/mercadopago/preferences \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "title": "My First Product",
        "quantity": 1,
        "unit_price": 100.50
      }
    ],
    "payer": {
      "email": "[email protected]"
    },
    "back_urls": {
      "success": "https://your-app.test/payments/success",
      "pending": "https://your-app.test/payments/pending",
      "failure": "https://your-app.test/payments/failure"
    },
    "notification_url": "https://your-app.test/api/mercadopago/webhooks",
    "external_reference": "order-1001"
  }'
You’ll receive a response with:
{
  "ok": true,
  "data": {
    "id": "1234567890-abc123def456",
    "init_point": "https://www.mercadopago.com/checkout/v1/redirect?pref_id=...",
    "sandbox_init_point": "https://sandbox.mercadopago.com/checkout/v1/redirect?pref_id=..."
  },
  "meta": []
}
The init_point URL is where you redirect users to complete payment in production. Use sandbox_init_point for testing.

​
Using services in your own controllers

While demo routes are helpful for testing, in production you should inject services into your own controllers: 
<?php

namespace App\Http\Controllers;

use Fitodac\LaravelMercadoPago\Services\PreferenceService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class CheckoutController
{
    public function createPreference(
        Request $request,
        PreferenceService $preferenceService
    ): JsonResponse {
        $payload = $request->validate([
            'items' => ['required', 'array', 'min:1'],
            'items.*.title' => ['required', 'string'],
            'items.*.quantity' => ['required', 'integer', 'min:1'],
            'items.*.unit_price' => ['required', 'numeric', 'min:0'],
        ]);

        $preference = $preferenceService->create($payload);

        return response()->json([
            'id' => data_get($preference, 'id'),
            'init_point' => data_get($preference, 'init_point'),
        ], 201);
    }
}

​
Next steps

Creating Preferences

Learn about all preference options and customization

Processing Payments

Process direct payments with tokenized cards

Handling Webhooks

Receive and validate payment notifications

Testing

Set up local testing with test users

Build docs developers (and LLMs) love

Get started for freeTalk to us