Documentation Index
Fetch the complete documentation index at: https://mintlify.com/fitodac/laravel-mercadopago/llms.txt
Use this file to discover all available pages before exploring further.
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
Install the package
Add the package to your Laravel project using Composer:composer require fitodac/laravel-mercadopago:^1.0
Verify package registration
Confirm the package is installed and routes are registered:php artisan package:discover
php artisan route:list --name=mercadopago
mercadopago.preferences.store and mercadopago.webhooks.store. Publish configuration (optional)
If you want to customize the configuration file:php artisan vendor:publish --tag=mercadopago-config
config/mercadopago.php in your project. 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.
Test the configuration
Verify your credentials are properly configured:curl http://localhost:8000/api/mercadopago/health
{
"ok": true,
"data": {
"configured": true,
"has_public_key": true,
"has_webhook_secret": true,
"environment": "local"
},
"meta": []
}
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": "buyer@example.com"
},
"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"
}'
{
"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