Skip to main content

​
Overview

The Preferences API allows you to create payment preferences that define the items, amounts, and configuration for a Mercado Pago checkout experience. Preferences are used to initialize the Mercado Pago checkout flow.
This endpoint is only available in local and testing environments when MERCADOPAGO_ENABLE_DEMO_ROUTES=true. It is automatically disabled in production.

​
Create Preference

Creates a new payment preference with items and configuration.

​
Endpoint

POST /api/mercadopago/preferences

​
Request Parameters

​
items
array
required
Array of items to be purchased. Must contain at least one item.
​
payer
object
Payer information
​
back_urls
object
URLs to redirect after payment completion
​
notification_url
string
URL for webhook notifications. Must be a valid URL.
​
external_reference
string
Your internal reference ID for this preference
​
metadata
object
Custom metadata object for additional information
​
expires
boolean
Whether the preference has an expiration date
​
expiration_date_from
date
Start date for preference validity
​
expiration_date_to
date
End date for preference validity

​
Request Example

{
  "items": [
    {
      "title": "Producto demo",
      "quantity": 1,
      "unit_price": 100.5
    }
  ],
  "payer": {
    "email": "[email protected]"
  },
  "back_urls": {
    "success": "https://tu-app.test/pagos/exito",
    "pending": "https://tu-app.test/pagos/pendiente",
    "failure": "https://tu-app.test/pagos/error"
  },
  "notification_url": "https://tu-app.test/api/mercadopago/webhooks",
  "external_reference": "pedido-1001"
}

​
Response

Returns the created preference object from Mercado Pago.
​
ok
boolean
Indicates if the request was successful
​
data
object
The preference object returned by Mercado Pago
​
meta
array
Additional metadata (typically empty)

​
Response Example

{
  "ok": true,
  "data": {
    "id": "123456789-abc123-def456-ghi789",
    "init_point": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=123456789-abc123",
    "sandbox_init_point": "https://sandbox.mercadopago.com.ar/checkout/v1/redirect?pref_id=123456789-abc123",
    "items": [
      {
        "id": "item-001",
        "title": "Producto demo",
        "quantity": 1,
        "unit_price": 100.5
      }
    ],
    "payer": {
      "email": "[email protected]"
    },
    "back_urls": {
      "success": "https://tu-app.test/pagos/exito",
      "pending": "https://tu-app.test/pagos/pendiente",
      "failure": "https://tu-app.test/pagos/error"
    },
    "notification_url": "https://tu-app.test/api/mercadopago/webhooks",
    "external_reference": "pedido-1001"
  },
  "meta": []
}

​
cURL Example

curl --request POST \
  --url http://localhost:8000/api/mercadopago/preferences \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "title": "Producto demo",
        "quantity": 1,
        "unit_price": 100.5
      }
    ]
  }'

​
Error Response

{
  "ok": false,
  "message": "Error message describing what went wrong"
}

​
Implementation Notes

​
Availability

This endpoint is protected by the mercadopago.demo middleware and only responds when:
  • MERCADOPAGO_ENABLE_DEMO_ROUTES=true in configuration
  • Application environment is local or testing
In production or when demo routes are disabled, this endpoint returns 404.

​
Controller Reference

Implemented in: src/Http/Controllers/Api/PreferenceController.php:14 Request validation: src/Http/Requests/CreatePreferenceRequest.php:16

​
Best Practices

Production Usage: For production environments, create your own controllers that inject the PreferenceService and implement your application’s authentication, authorization, and business logic.
Security: Demo routes are for development and testing only. Never expose them in production environments.

​
Example Production Controller

use Fitodac\LaravelMercadoPago\Services\PreferenceService;

final class CheckoutPreferenceController
{
    public function store(Request $request, PreferenceService $preferenceService): JsonResponse
    {
        $payload = $request->validate([
            'items' => ['required', 'array', 'min:1'],
            'items.*.title' => ['required', 'string'],
            'items.*.quantity' => ['required', 'integer', 'min:1'],
            'items.*.unit_price' => ['required', 'numeric', 'min:0'],
            'external_reference' => ['sometimes', 'string'],
        ]);

        $preference = $preferenceService->create($payload);

        return response()->json([
            'id' => data_get($preference, 'id'),
            'init_point' => data_get($preference, 'init_point'),
        ], 201);
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us