Configuration

Overview

The Laravel MercadoPago package configuration controls SDK authentication, webhook security, route registration, and runtime behavior. All options can be set via environment variables or by publishing and modifying the configuration file.

Publishing the Configuration File

While the package works with environment variables alone, you can publish the configuration file for advanced customization or programmatic configuration:

php artisan vendor:publish --tag=mercadopago-config

This creates config/mercadopago.php in your Laravel application, allowing you to access configuration values via config('mercadopago.{key}').

Configuration Options

access_token

string

required

Your Mercado Pago access token used by the SDK to authenticate API requests.Environment variable: MERCADOPAGO_ACCESS_TOKENDefault: nullThis token is essential for all API operations. Without it, the package services will throw a configuration exception when attempting to make API calls.

.env

MERCADOPAGO_ACCESS_TOKEN=APP_USR-1234567890123456-123456-abc123def456ghi789jkl012mno345-123456789

Where to find it: Mercado Pago Dashboard → Your integrations → Credentials

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

public_key

string

Your Mercado Pago public key used for frontend integrations like card tokenization and Checkout Pro.Environment variable: MERCADOPAGO_PUBLIC_KEYDefault: nullWhile not required for server-side operations, this is necessary if you’re implementing client-side payment flows that require tokenizing card data before sending it to your backend.

.env

MERCADOPAGO_PUBLIC_KEY=APP_USR-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890

Use cases:

Card tokenization in the browser
Frontend validation of card details
Checkout Pro initialization

webhook_secret

string

Secret used to validate webhook HMAC signatures for enhanced security.Environment variable: MERCADOPAGO_WEBHOOK_SECRETDefault: nullHighly recommended for production environments. When configured, the webhook endpoint validates the x-signature header to ensure notifications are authentic and originate from Mercado Pago.

.env

MERCADOPAGO_WEBHOOK_SECRET=your-webhook-secret-from-mercadopago

How it works:

Mercado Pago sends a signature in the x-signature header
The package computes an HMAC hash using this secret
If signatures match, the webhook is validated
If not configured, webhooks are accepted without validation

If webhook_secret is not configured, webhooks will still be processed but the response will include "validated": false.

Where to configure: Mercado Pago Dashboard → Your integrations → Webhooks → Signature

route_prefix

string

default:"api/mercadopago"

URL prefix for all routes registered by the package, including webhooks and demo endpoints.Environment variable: MERCADOPAGO_ROUTE_PREFIXDefault: "api/mercadopago"This allows you to customize where package routes are mounted in your application’s URL structure.

.env

MERCADOPAGO_ROUTE_PREFIX=api/payments

Example routes with custom prefix:

POST /api/payments/webhooks (webhook endpoint)
GET /api/payments/health (health check)
POST /api/payments/preferences (demo preference creation)

Type: string

Use a descriptive prefix that aligns with your application’s routing conventions. Avoid leading/trailing slashes.

enable_demo_routes

boolean

default:"true"

Enable or disable demo routes for testing and development.Environment variable: MERCADOPAGO_ENABLE_DEMO_ROUTESDefault: trueType: boolean (cast from string in .env)Demo routes provide convenient endpoints for testing the package functionality without writing custom controllers. They’re useful during development but should be disabled in production.

.env

MERCADOPAGO_ENABLE_DEMO_ROUTES=true

Important security note: Demo routes are always disabled in production regardless of this setting. The package checks APP_ENV and only enables demo routes when the environment is local or testing.Conditions for demo routes to be accessible:

enable_demo_routes must be true AND
APP_ENV must be local or testing

Available demo routes:

GET /api/mercadopago/health - Configuration health check
POST /api/mercadopago/preferences - Create payment preference
POST /api/mercadopago/payments - Process payment
GET /api/mercadopago/customers - List customers
POST /api/mercadopago/customers - Create customer
GET /api/mercadopago/payment-methods - Get payment methods
POST /api/mercadopago/test-users - Create test user

Demo routes should never be relied upon in production code. They’re intended for testing and prototyping only.

runtime_environment

string|null

Forces the Mercado Pago SDK runtime environment mode.Environment variable: MERCADOPAGO_RUNTIME_ENVIRONMENTDefault: null (auto-detected)Type: string|nullPossible values:

"local" - Development/testing mode
"server" - Production mode
null - Auto-detect based on APP_ENV

When not explicitly set, the package automatically determines the runtime environment:

Uses local when APP_ENV is local or testing
Uses server in all other environments (production, staging, etc.)

.env

# Force production mode even in local environment
MERCADOPAGO_RUNTIME_ENVIRONMENT=server

# Force development mode
MERCADOPAGO_RUNTIME_ENVIRONMENT=local

When to override:

Testing production behavior in local environment
Debugging SDK issues
Special deployment scenarios

In most cases, you should leave this unset and let the package auto-detect the appropriate runtime mode.

Configuration File Structure

After publishing, the config/mercadopago.php file contains:

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'),
];

Accessing Configuration Values

You can access configuration values anywhere in your Laravel application:

// Get access token
$accessToken = config('mercadopago.access_token');

// Get route prefix
$routePrefix = config('mercadopago.route_prefix');

// Check if demo routes are enabled
$demoEnabled = config('mercadopago.enable_demo_routes');

// Get all config
$config = config('mercadopago');

Environment-Specific Examples

Local Development
Production
Testing/CI
Staging

.env

APP_ENV=local

# Use test credentials
MERCADOPAGO_ACCESS_TOKEN=TEST-1234567890123456-123456-abc123def456
MERCADOPAGO_PUBLIC_KEY=TEST-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
MERCADOPAGO_WEBHOOK_SECRET=test-webhook-secret

# Enable demo routes for testing
MERCADOPAGO_ENABLE_DEMO_ROUTES=true

# Default route prefix
MERCADOPAGO_ROUTE_PREFIX=api/mercadopago

# Auto-detects to 'local' runtime
# MERCADOPAGO_RUNTIME_ENVIRONMENT not needed

Configuration summary:

Demo routes are accessible at /api/mercadopago/*
Webhook validation is enabled with test secret
SDK automatically uses local runtime mode
Health check available at /api/mercadopago/health

.env

APP_ENV=production

# Use production credentials
MERCADOPAGO_ACCESS_TOKEN=APP_USR-1234567890123456-123456-abc123def456
MERCADOPAGO_PUBLIC_KEY=APP_USR-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890

# Required for webhook security
MERCADOPAGO_WEBHOOK_SECRET=your-production-webhook-secret

# Explicitly disable demo routes (also disabled automatically)
MERCADOPAGO_ENABLE_DEMO_ROUTES=false

# Production route prefix
MERCADOPAGO_ROUTE_PREFIX=api/mercadopago

# Auto-detects to 'server' runtime
# MERCADOPAGO_RUNTIME_ENVIRONMENT not needed

Configuration summary:

Demo routes are disabled (enforced by package)
Webhook endpoint at /api/mercadopago/webhooks with signature validation
SDK uses server runtime mode
Only webhook route is publicly accessible

Always use HTTPS in production. Mercado Pago requires secure webhook URLs.

.env

APP_ENV=testing

# Use test credentials
MERCADOPAGO_ACCESS_TOKEN=TEST-1234567890123456-123456-abc123def456
MERCADOPAGO_PUBLIC_KEY=TEST-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890

# Optional for automated tests
MERCADOPAGO_WEBHOOK_SECRET=

# Enable demo routes for integration tests
MERCADOPAGO_ENABLE_DEMO_ROUTES=true

MERCADOPAGO_ROUTE_PREFIX=api/mercadopago

# Auto-detects to 'local' runtime
# MERCADOPAGO_RUNTIME_ENVIRONMENT not needed

Configuration summary:

Demo routes are accessible for integration tests
Webhook validation is optional (useful for testing)
SDK uses local runtime mode
Test credentials prevent real charges

.env

APP_ENV=staging

# Use test credentials or production credentials depending on needs
MERCADOPAGO_ACCESS_TOKEN=TEST-1234567890123456-123456-abc123def456
MERCADOPAGO_PUBLIC_KEY=TEST-a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
MERCADOPAGO_WEBHOOK_SECRET=staging-webhook-secret

# Disable demo routes (production-like)
MERCADOPAGO_ENABLE_DEMO_ROUTES=false

MERCADOPAGO_ROUTE_PREFIX=api/mercadopago

# Use server runtime for production-like behavior
MERCADOPAGO_RUNTIME_ENVIRONMENT=server

Configuration summary:

Production-like configuration for pre-deployment testing
Demo routes disabled
Webhook validation enabled
Server runtime mode for accurate testing

Configuration Reference Table

Option	Type	Required	Default	Environment Variable
`access_token`	`string`	Yes	`null`	`MERCADOPAGO_ACCESS_TOKEN`
`public_key`	`string`	No	`null`	`MERCADOPAGO_PUBLIC_KEY`
`webhook_secret`	`string`	Recommended	`null`	`MERCADOPAGO_WEBHOOK_SECRET`
`route_prefix`	`string`	No	`"api/mercadopago"`	`MERCADOPAGO_ROUTE_PREFIX`
`enable_demo_routes`	`boolean`	No	`true`	`MERCADOPAGO_ENABLE_DEMO_ROUTES`
`runtime_environment`	`string\|null`	No	Auto-detected	`MERCADOPAGO_RUNTIME_ENVIRONMENT`

Validating Configuration

After configuring the package, verify your setup is correct.

Clear configuration cache

If you’ve previously cached configuration, clear it to pick up new values:

php artisan config:clear

Test with health endpoint

When demo routes are enabled, use the health endpoint to verify configuration:

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": []
}

Response fields:

configured: true if access_token is set
has_public_key: true if public_key is set
has_webhook_secret: true if webhook_secret is set
environment: Current runtime environment (local or server)

Verify route registration

List all package routes to confirm they use your configured prefix:

php artisan route:list --name=mercadopago

You should see routes matching your route_prefix configuration.

Test webhook validation

If you’ve configured webhook_secret, test webhook signature validation by sending a test notification from the Mercado Pago dashboard or using their webhook testing tools.

Security Best Practices

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

Development Environment

Use test credentials from Mercado Pago test users

Enable demo routes for easier testing (MERCADOPAGO_ENABLE_DEMO_ROUTES=true)

Configure webhook secret even in development for testing validation logic

Use test mode access tokens (starting with TEST-)

Production Environment

Use production credentials from your Mercado Pago account

Configure webhook secret for signature validation (required)

Disable demo routes explicitly (MERCADOPAGO_ENABLE_DEMO_ROUTES=false)

Use HTTPS for all webhook endpoints

Cache configuration for performance (php artisan config:cache)

Rotate credentials periodically and when team members leave

Monitor webhook failures and failed signature validations

Troubleshooting

”Mercado Pago access token is not configured”

Cause: The access_token configuration is missing or empty. Solution:

Set MERCADOPAGO_ACCESS_TOKEN in your .env file
Clear configuration cache:
```
php artisan config:clear
```

Verify the value is loaded:

php artisan tinker
>>> config('mercadopago.access_token')

Demo routes returning 404

Possible causes:

MERCADOPAGO_ENABLE_DEMO_ROUTES is not true
APP_ENV is not local or testing (production environment)
Routes are cached with old configuration

Solution:

# Clear route and config cache
php artisan route:clear
php artisan config:clear

# Verify routes are registered
php artisan route:list --name=mercadopago

Webhook returning 401 Unauthorized

Cause: Webhook HMAC signature validation is failing. Check:

MERCADOPAGO_WEBHOOK_SECRET matches the secret configured in Mercado Pago dashboard
Request includes required headers: x-signature, x-request-id
Request includes data.id parameter in query string or payload

Debug:

// Log webhook validation details
Log::info('Webhook received', [
    'signature' => request()->header('x-signature'),
    'request_id' => request()->header('x-request-id'),
    'data_id' => request()->input('data.id'),
]);

Configuration changes not taking effect

Cause: Laravel’s configuration is cached. Solution:

# Development: Clear cache
php artisan config:clear

# Production: Re-cache configuration
php artisan config:clear
php artisan config:cache

Routes registered with wrong prefix

Cause: Configuration cached before route_prefix was updated. Solution:

php artisan route:clear
php artisan config:clear
php artisan optimize:clear

Installation

Install the package and set up your environment

Credentials Guide

Learn how to obtain and manage Mercado Pago credentials

Webhook Handling

Implement secure webhook processing with signature validation

Production Deployment

Best practices for deploying to production

Services

Demo Endpoints

Configuration

Overview

Publishing the Configuration File

Configuration Options

Configuration File Structure

Accessing Configuration Values

Environment-Specific Examples

Configuration Reference Table

Validating Configuration

Security Best Practices

Development Environment

Production Environment

Troubleshooting

”Mercado Pago access token is not configured”

Demo routes returning 404

Webhook returning 401 Unauthorized

Configuration changes not taking effect

Routes registered with wrong prefix

Installation

Credentials Guide

Webhook Handling

Production Deployment

Build docs developers (and LLMs) love

Services

Demo Endpoints

Configuration

​Overview

​Publishing the Configuration File

​Configuration Options

​Configuration File Structure

​Accessing Configuration Values

​Environment-Specific Examples

​Configuration Reference Table

​Validating Configuration

​Security Best Practices

​Development Environment

​Production Environment

​Troubleshooting

​”Mercado Pago access token is not configured”

​Demo routes returning 404

​Webhook returning 401 Unauthorized

​Configuration changes not taking effect

​Routes registered with wrong prefix

​Related Documentation

Installation

Credentials Guide

Webhook Handling

Production Deployment

Build docs developers (and LLMs) love

Overview

Publishing the Configuration File

Configuration Options

Configuration File Structure

Accessing Configuration Values

Environment-Specific Examples

Configuration Reference Table

Validating Configuration

Security Best Practices

Development Environment

Production Environment

Troubleshooting

”Mercado Pago access token is not configured”

Demo routes returning 404

Webhook returning 401 Unauthorized

Configuration changes not taking effect

Routes registered with wrong prefix

Related Documentation