Skip to main content
This guide covers deploying the Laravel MercadoPago package to production servers, including configuration, caching, and environment-specific settings.

​
Prerequisites

Before deploying to production, ensure you have:
  • PHP ^8.2 installed on your production server
  • Laravel ^12.0 configured and working
  • Valid MercadoPago production credentials (access token, public key, webhook secret)
  • HTTPS enabled on your domain
  • Composer available for dependency installation

​
Environment Variables

1

Configure production environment

Set the following environment variables in your production .env file:
APP_ENV=production
MERCADOPAGO_ACCESS_TOKEN=your_production_access_token
MERCADOPAGO_PUBLIC_KEY=your_production_public_key
MERCADOPAGO_WEBHOOK_SECRET=your_webhook_secret
MERCADOPAGO_ENABLE_DEMO_ROUTES=false
MERCADOPAGO_ROUTE_PREFIX=api/mercadopago
Never commit production credentials to your repository. Always use environment variables or secure secret management systems.
2

Install dependencies

Install package dependencies with production optimizations:
composer install --no-dev --optimize-autoloader
The --no-dev flag excludes development dependencies, and --optimize-autoloader improves class loading performance.
3

Verify package registration

Confirm the package is properly registered:
php artisan package:discover
php artisan route:list --name=mercadopago
You should see the webhook route registered. Demo routes will not appear when MERCADOPAGO_ENABLE_DEMO_ROUTES=false.

​
Disabling Demo Routes

Critical: Always disable demo routes in production to prevent unauthorized access to MercadoPago operations.
Demo routes are automatically disabled in production when:
  1. MERCADOPAGO_ENABLE_DEMO_ROUTES=false in your .env
  2. APP_ENV is set to anything other than local or testing
The middleware at src/Http/Middleware/EnsureDemoRoutesEnabled.php:18-28 enforces this protection: 
if (
    ! $this->config->get('mercadopago.enable_demo_routes', true)
    || ! app()->environment(['local', 'testing'])
) {
    abort(404);
}
Demo routes include:
  • /api/mercadopago/health
  • /api/mercadopago/payment-methods
  • /api/mercadopago/preferences
  • /api/mercadopago/payments
  • /api/mercadopago/customers
  • /api/mercadopago/test-users
The webhook route (POST /api/mercadopago/webhooks) remains active in all environments as it’s required for production operations.

​
Cache Optimization

Optimize Laravel’s configuration and route caching for production performance:
1

Clear existing caches

php artisan config:clear
php artisan cache:clear
php artisan route:clear
2

Build production caches

php artisan config:cache
php artisan route:cache
php artisan view:cache
Configuration caching reads all config files once and creates a single cached file, significantly improving bootstrap performance.
3

Verify webhook accessibility

Test that your webhook endpoint is publicly accessible:
curl --request POST \
  --url https://your-domain.com/api/mercadopago/webhooks \
  --header 'Content-Type: application/json' \
  --data '{"type":"payment","data":{"id":"123"}}'
Expected response structure:
{
  "ok": true,
  "data": {
    "acknowledged": true,
    "validated": false,
    "topic": "payment",
    "resource": "123",
    "payload": {...}
  },
  "meta": []
}
If validated is false, your webhook secret is not configured. This is not recommended for production.

​
Runtime Environment Configuration

The package automatically configures the MercadoPago SDK runtime based on your Laravel environment:
  • Local/Testing: Uses local runtime mode
  • Production: Uses server runtime mode
You can override this behavior with: 
MERCADOPAGO_RUNTIME_ENVIRONMENT=server
In most cases, you don’t need to set this variable. The package selects the appropriate runtime automatically.

​
Production Deployment Checklist

Use this checklist before deploying to production:
1

Security configuration

  • MERCADOPAGO_ENABLE_DEMO_ROUTES=false
  • MERCADOPAGO_WEBHOOK_SECRET configured
  • HTTPS enabled and enforced
  • Production credentials stored securely
  • No credentials committed to repository
2

Application setup

  • Dependencies installed with --no-dev --optimize-autoloader
  • Configuration cached with php artisan config:cache
  • Routes cached with php artisan route:cache
  • Package discovery completed
3

Monitoring and logging

  • Centralized logging configured
  • Error monitoring for 401, 422, and 500 responses
  • Webhook endpoint monitoring active
  • Alert system configured for payment failures
4

MercadoPago configuration

  • Webhook URL registered in MercadoPago dashboard
  • Webhook URL points to your HTTPS domain
  • Webhook secret matches between MercadoPago and your .env
  • Production credentials tested
5

Business logic

  • Custom controllers implement authentication
  • Authorization rules configured
  • Payment state persistence implemented
  • Webhook retry logic configured
  • Edge cases handled (partial refunds, failed payments, etc.)

​
Testing Production Deployment

After deployment, verify your setup:

​
1. Verify Demo Routes Are Disabled

curl https://your-domain.com/api/mercadopago/health
Expected: 404 Not Found

​
2. Verify Webhook Is Active

curl --request POST \
  --url https://your-domain.com/api/mercadopago/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-signature: v1=test,ts=12345' \
  --header 'x-request-id: test-request' \
  --data '{"type":"payment","data":{"id":"123"}}'
Expected: 200 or 401 (if signature validation is active)

​
3. Trigger a Real Webhook

Create a test payment through MercadoPago’s interface and verify your webhook receives and processes the notification correctly.

​
Post-Deployment Operations

​
Configuration Updates

When updating environment variables: 
# After editing .env
php artisan config:clear
php artisan config:cache

​
Package Updates

When updating the package version: 
composer update fitodac/laravel-mercadopago
php artisan package:discover
php artisan route:cache

​
Troubleshooting Production Issues

​
Demo Routes Still Accessible

Symptom: Demo routes return 200 in production Solution:
  1. Verify MERCADOPAGO_ENABLE_DEMO_ROUTES=false in .env
  2. Verify APP_ENV=production
  3. Clear and rebuild config cache: 
    php artisan config:clear
php artisan config:cache

​
Webhook Returns 422

Symptom: Mercado Pago access token is not configured. Solution:
  1. Verify MERCADOPAGO_ACCESS_TOKEN is set in .env
  2. Clear config cache: 
    php artisan config:clear
  3. Verify credentials are not expired

​
Package Routes Not Found

Symptom: All MercadoPago routes return 404 Solution: 
composer dump-autoload
php artisan package:discover
php artisan route:cache
php artisan route:list --name=mercadopago

​
Next Steps

Security Best Practices

Implement security measures for production

Webhooks

Handle webhook notifications properly

Build docs developers (and LLMs) love

Get started for freeTalk to us