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

Build docs developers (and LLMs) love

Get started for freeTalk to us