Skip to main content

​
Publishing the Configuration

While the package works with environment variables alone, you can optionally publish the configuration file for advanced customization. 
php artisan vendor:publish --tag=mercadopago-config
This creates config/mercadopago.php in your Laravel application.

​
Environment Variables

All configuration options can be set via environment variables in your .env file.

​
Required Configuration

​
MERCADOPAGO_ACCESS_TOKEN
string
required
Your Mercado Pago access token. This is used by the SDK to authenticate API requests.Where to find it: Mercado Pago Dashboard → Your integrations → Credentials
.env
MERCADOPAGO_ACCESS_TOKEN=APP_USR-1234567890123456-123456-abc123def456ghi789jkl012mno345-123456789
Without a valid MERCADOPAGO_ACCESS_TOKEN, the package services will throw a configuration exception when attempting to make API calls.

​
Optional Configuration

​
MERCADOPAGO_PUBLIC_KEY
string
Your Mercado Pago public key. Used for frontend integrations like card tokenization.
.env
MERCADOPAGO_PUBLIC_KEY=APP_USR-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
​
MERCADOPAGO_WEBHOOK_SECRET
string
Secret used to validate webhook HMAC signatures. Highly recommended for production.When configured, the webhook endpoint validates the x-signature header to ensure notifications are authentic.
.env
MERCADOPAGO_WEBHOOK_SECRET=your-webhook-secret-from-mercadopago
If not configured, webhooks will be accepted without signature validation (validated: false in the response).
​
MERCADOPAGO_ROUTE_PREFIX
string
default:"api/mercadopago"
Prefix for all registered routes (webhook and demo endpoints).
.env
MERCADOPAGO_ROUTE_PREFIX=api/payments
Results in routes like:
  • POST /api/payments/webhooks
  • GET /api/payments/health
​
MERCADOPAGO_ENABLE_DEMO_ROUTES
boolean
default:"true"
Enable or disable demo routes. Demo routes are always disabled in production regardless of this setting.
.env
MERCADOPAGO_ENABLE_DEMO_ROUTES=true
Demo routes only respond when:
  • This is set to true AND
  • APP_ENV is local or testing
​
MERCADOPAGO_RUNTIME_ENVIRONMENT
string
Forces the Mercado Pago SDK runtime environment. If not set, the package automatically uses:
  • local when APP_ENV is local or testing
  • server in all other environments
.env
MERCADOPAGO_RUNTIME_ENVIRONMENT=server

​
Configuration File Structure

The published config/mercadopago.php file looks like this:
config/mercadopago.php
<?php

declare(strict_types=1);

return [
    'access_token' => env('MERCADOPAGO_ACCESS_TOKEN'),
    'public_key' => env('MERCADOPAGO_PUBLIC_KEY'),
    'webhook_secret' => env('MERCADOPAGO_WEBHOOK_SECRET'),
    'route_prefix' => env('MERCADOPAGO_ROUTE_PREFIX', 'api/mercadopago'),
    'enable_demo_routes' => (bool) env('MERCADOPAGO_ENABLE_DEMO_ROUTES', true),
    'runtime_environment' => env('MERCADOPAGO_RUNTIME_ENVIRONMENT'),
];
You can access these values in your application: 
config('mercadopago.access_token')
config('mercadopago.route_prefix')
config('mercadopago.enable_demo_routes')

​
Example Configurations

.env
APP_ENV=local

MERCADOPAGO_ACCESS_TOKEN=TEST-1234567890123456-123456-abc123def456
MERCADOPAGO_PUBLIC_KEY=TEST-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
MERCADOPAGO_WEBHOOK_SECRET=test-webhook-secret
MERCADOPAGO_ROUTE_PREFIX=api/mercadopago
MERCADOPAGO_ENABLE_DEMO_ROUTES=true
  • Demo routes are accessible
  • Webhook validation is enabled
  • SDK uses local runtime automatically

​
Configuration Reference Table

VariableRequiredDefaultDescription
MERCADOPAGO_ACCESS_TOKENYes-SDK authentication token for API calls
MERCADOPAGO_PUBLIC_KEYNo-Public key for frontend integrations
MERCADOPAGO_WEBHOOK_SECRETRecommended-Secret for validating webhook signatures
MERCADOPAGO_ROUTE_PREFIXNoapi/mercadopagoPrefix for all registered routes
MERCADOPAGO_ENABLE_DEMO_ROUTESNotrueEnable demo routes (only works in local/testing)
MERCADOPAGO_RUNTIME_ENVIRONMENTNoAuto-detectedForce SDK runtime: local or server

​
Verifying Configuration

After configuring the package, verify your setup using the health check endpoint:
1

Clear configuration cache

If you’ve cached your configuration, clear it to pick up new values:
php artisan config:clear
2

Test the health endpoint

The health endpoint is available when demo routes are enabled:
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": []
}
3

Verify route registration

php artisan route:list --name=mercadopago
Confirm that routes use your configured prefix.

​
Security Best Practices

Never commit credentials to version control. Always use environment variables and keep .env in your .gitignore.

​
Development

  • Use test credentials from Mercado Pago test users
  • Keep MERCADOPAGO_ENABLE_DEMO_ROUTES=true for easier testing
  • Webhook secret is optional but recommended

​
Production

1

Use production credentials

Replace all test credentials with production access tokens and public keys from your Mercado Pago account.
2

Configure webhook secret

Always set MERCADOPAGO_WEBHOOK_SECRET to validate incoming webhook notifications.
.env
MERCADOPAGO_WEBHOOK_SECRET=your-production-secret
3

Disable demo routes

Explicitly disable demo routes in production:
.env
MERCADOPAGO_ENABLE_DEMO_ROUTES=false
Even if left enabled, they won’t respond in production environments.
4

Use HTTPS

Ensure your webhook endpoint is accessible via HTTPS. Mercado Pago requires secure webhook URLs.
5

Cache configuration

In production, cache your configuration for better performance:
php artisan config:cache

​
Troubleshooting

​
”Mercado Pago access token is not configured”

Solution: Set MERCADOPAGO_ACCESS_TOKEN and clear config cache: 
php artisan config:clear

​
Demo routes returning 404

Causes:
  1. MERCADOPAGO_ENABLE_DEMO_ROUTES is not true
  2. APP_ENV is not local or testing
  3. Routes are cached without the middleware
Solution: 
php artisan route:clear
php artisan config:clear

​
Webhook returning 401 Unauthorized

Cause: HMAC signature validation is failing. Check:
  • MERCADOPAGO_WEBHOOK_SECRET matches the secret configured in Mercado Pago dashboard
  • The request includes x-signature and x-request-id headers
  • The data.id parameter is present in the query string or payload

​
Configuration changes not taking effect

Solution: Clear and recache configuration: 
php artisan config:clear
php artisan config:cache

​
Next Steps

Using Services

Learn how to inject and use the package services in your application

Demo Endpoints

Explore the webhook and demo routes registered by the package

Build docs developers (and LLMs) love

Get started for freeTalk to us