Skip to main content

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.

​
Configuration Issues

Error Message:
Mercado Pago access token is not configured.
Cause: The package cannot find the MERCADOPAGO_ACCESS_TOKEN environment variable.Solution:
  1. Add the access token to your .env file: 
    MERCADOPAGO_ACCESS_TOKEN=your_access_token_here
  2. Clear the configuration cache: 
    php artisan config:clear
  3. Verify the configuration: 
    curl http://localhost:8000/api/mercadopago/health
Never commit your access token to version control. Keep it in .env and add .env to your .gitignore.
Symptoms:
  • Running php artisan route:list --name=mercadopago shows no routes
  • Requests to /api/mercadopago/* return 404
Solution:
  1. Regenerate the package discovery cache: 
    composer dump-autoload
php artisan package:discover
  2. Clear the route cache: 
    php artisan route:clear
  3. Verify routes are registered: 
    php artisan route:list --name=mercadopago
If using route caching in production, regenerate it with:
php artisan route:cache

​
Demo Routes Issues

Error: Demo routes like /api/mercadopago/health or /api/mercadopago/preferences return 404.Cause: Demo routes are protected by the EnsureDemoRoutesEnabled middleware and only work when both conditions are met:
  • MERCADOPAGO_ENABLE_DEMO_ROUTES=true
  • Application environment is local or testing
Solution:
  1. Check your .env file: 
    APP_ENV=local
MERCADOPAGO_ENABLE_DEMO_ROUTES=true
  2. Clear configuration cache: 
    php artisan config:clear
  3. Verify the environment: 
    php artisan env
In production (APP_ENV=production), demo routes are always disabled regardless of the ENABLE_DEMO_ROUTES setting. This is a security feature.
Alternative: Create your own controllers that use the package services instead of relying on demo routes. See the Quickstart guide for examples.
Error: Routes conflict with your application’s existing endpoints.Solution:Change the route prefix in your .env:
MERCADOPAGO_ROUTE_PREFIX=api/payments/mercadopago
Or publish and modify the configuration:
php artisan vendor:publish --tag=mercadopago-config
Then edit config/mercadopago.php:
return [
    'route_prefix' => env('MERCADOPAGO_ROUTE_PREFIX', 'api/payments/mp'),
    // ...
];

​
Webhook Issues

Error Message:
{
  "ok": false,
  "message": "Mercado Pago webhook signature is invalid."
}
Cause: The webhook signature validation failed. This happens when:
  • MERCADOPAGO_WEBHOOK_SECRET doesn’t match the secret configured in Mercado Pago
  • Required headers are missing
  • The signature format is incorrect
Solution:
  1. Verify your webhook secret matches Mercado Pago: 
    MERCADOPAGO_WEBHOOK_SECRET=your_webhook_secret_here
  2. Ensure Mercado Pago is sending these headers:
    • x-signature: Contains ts and v1 parameters
    • x-request-id: Unique request identifier
  3. Verify the URL includes data.id in query string or payload: 
    POST /api/mercadopago/webhooks?data.id=123456
During local development, you can test webhooks without a secret. The package will set validated: false but still process the payload.
Debugging signature validation:The package validates signatures using this manifest:
id:{data.id};request-id:{x-request-id};ts:{timestamp};
Check your logs to see what values the package received.
Error Message:
{
  "ok": false,
  "message": "Mercado Pago webhook signature header is malformed."
}
Cause: The x-signature header doesn’t contain the required ts and v1 parameters.Expected format:
x-signature: ts=1234567890,v1=abc123def456...
Solution:
  1. Verify you’re receiving webhooks directly from Mercado Pago
  2. Check if a proxy or load balancer is modifying headers
  3. Ensure the webhook URL is configured correctly in Mercado Pago dashboard
If you’re using a testing tool like Postman, make sure to format the header exactly as Mercado Pago sends it.
Problem: Mercado Pago isn’t calling your webhook endpoint.Solution:
  1. Verify the webhook URL is publicly accessible:
    • Must use HTTPS in production
    • Must be reachable from Mercado Pago servers
  2. For local development, use a tunnel service: 
    # Example with ngrok
ngrok http 8000
  3. Configure the public URL in Mercado Pago: 
    https://your-domain.com/api/mercadopago/webhooks
  4. Test the endpoint manually: 
    curl --request POST \
  --url https://your-domain.com/api/mercadopago/webhooks \
  --header 'Content-Type: application/json' \
  --data '{"type":"payment","data":{"id":"123"}}'
You can also specify notification_url when creating preferences or payments to override the default webhook URL.

​
SDK and API Errors

Error Message:
Mercado Pago PHP SDK is not installed.
Solution:The package requires mercadopago/dx-php. Install it:
composer require mercadopago/dx-php:^3.8
Then clear caches:
composer dump-autoload
php artisan config:clear
Error Message:
No Mercado Pago SDK client class was found.
Cause: The package couldn’t find the expected SDK client class.Solution:
  1. Verify the SDK version: 
    composer show mercadopago/dx-php
  2. Ensure you’re using version ^3.8: 
    composer require mercadopago/dx-php:^3.8
  3. Clear composer cache: 
    composer clear-cache
composer install
Error: Mercado Pago API returns 422 when creating preferences or payments.Common causes:
  1. Invalid payload structure - Check the required fields in the API Reference
  2. Invalid email format - Ensure payer.email is valid
  3. Invalid amount - Must be positive and properly formatted
  4. Invalid payment method - Verify the payment method ID is valid for your country
Solution:Validate your payload against the examples:
{
  "items": [
    {
      "title": "Product name",
      "quantity": 1,
      "unit_price": 100.50
    }
  ],
  "payer": {
    "email": "buyer@example.com"
  }
}
Enable debugging to see the exact error from Mercado Pago:
Log::channel('daily')->info('MP Error', [
    'payload' => $payload,
    'response' => $exception->getMessage()
]);
Error: API requests return 401 Unauthorized.Cause: Invalid or expired access token.Solution:
  1. Verify your access token in Mercado Pago dashboard
  2. Ensure you’re using the correct token for your environment:
    • Test mode: Test access token
    • Production mode: Production access token
  3. Update your .env: 
    MERCADOPAGO_ACCESS_TOKEN=APP-1234567890-VALID-TOKEN
  4. Clear configuration: 
    php artisan config:clear
Never mix test and production credentials. Use separate .env files for each environment.

​
Testing Issues

Problem: Cannot create test users via /api/mercadopago/test-users.Solution:
  1. Ensure demo routes are enabled: 
    APP_ENV=local
MERCADOPAGO_ENABLE_DEMO_ROUTES=true
  2. Use a valid site_id: 
    {
  "site_id": "MLA",
  "description": "Test user for QA"
}
Valid site IDs: MLA, MLB, MLC, MLM, MLU, MCO, MPE
Test user creation requires a valid production access token, even in test mode.
Error: Payment creation fails with invalid card token.Cause: Card tokens generated by MercadoPago.js expire after a short time.Solution:
  1. Generate the token immediately before creating the payment
  2. Don’t store tokens for later use
  3. Handle token expiration errors gracefully: 
    try {
    $payment = $paymentService->create($payload);
} catch (Exception $e) {
    if (str_contains($e->getMessage(), 'token')) {
        return response()->json([
            'error' => 'Card token expired. Please try again.'
        ], 422);
    }
    throw $e;
}
For development, use test cards from the Testing guide.

​
Need More Help?

If your issue isn’t listed here:
  1. Check the Debugging guide for diagnostic techniques
  2. Enable detailed logging to capture error details
  3. Review the GitHub issues for similar problems
  4. Consult the official Mercado Pago documentation