Overview The PreferenceService class handles creation of payment preferences for MercadoPago’s checkout experience. Preferences define the items being purchased, payment details, and redirect URLs.
Source : src/Services/PreferenceService.php:9Constructor public function __construct ( private MercadoPagoClientFactory $clientFactory , ) {}
Dependencies clientFactory
MercadoPagoClientFactory
required
Factory for creating and configuring MercadoPago SDK clients. Automatically injected by Laravel’s service container.
Methods create() Creates a new payment preference in MercadoPago.
public function create ( array $payload ) : mixed
Source : src/Services/PreferenceService.php:15Parameters The preference configuration data. Array of items being purchased. Each item must contain:
title (string, required): Item namequantity (integer, required): Quantityunit_price (numeric, required): Unit pricecurrency_id (string, optional): Currency code (e.g., “ARS”)description (string, optional): Item description Payer information:
email (string): Payer’s emailname (string): First namesurname (string): Last namephone (array): Phone detailsaddress (array): Address details Redirect URLs after payment:
success (string): URL for successful paymentpending (string): URL for pending paymentfailure (string): URL for failed payment Webhook URL for payment notifications
Your internal order or transaction reference
Enable preference expiration
ISO 8601 date when preference becomes active
ISO 8601 date when preference expires
Custom key-value data for your application
Returns MercadoPago preference object containing: Unique preference identifier
Sandbox/testing checkout URL
ISO 8601 creation timestamp
Array of preference items
Redirect URLs configuration
Usage Controller injection
Service container resolution
Route closure
use Fitodac\LaravelMercadoPago\Services\ PreferenceService ; use Illuminate\Http\ JsonResponse ; use Illuminate\Http\ Request ; final class CheckoutController { public function store ( Request $request , PreferenceService $preferenceService ) : JsonResponse { $preference = $preferenceService -> create ([ 'items' => [ [ 'title' => 'Premium Subscription' , 'quantity' => 1 , 'unit_price' => 99.99 , ], ], 'payer' => [ 'email' => '[email protected] ' , ], 'back_urls' => [ 'success' => route ( 'payment.success' ), 'pending' => route ( 'payment.pending' ), 'failure' => route ( 'payment.failure' ), ], 'notification_url' => route ( 'mercadopago.webhooks' ), 'external_reference' => 'ORDER-12345' , ]); return response () -> json ([ 'preference_id' => data_get ( $preference , 'id' ), 'checkout_url' => data_get ( $preference , 'init_point' ), ]); } }
Error Handling The service may throw the following exceptions:
MercadoPagoConfigurationException
Thrown when:
MercadoPago SDK is not installed
Required SDK classes are not found
SDK methods are unavailable
Thrown by the MercadoPago SDK for API errors:
Invalid credentials
Invalid payload data
Network errors
API rate limits
Error handling example use Fitodac\LaravelMercadoPago\Exceptions\ MercadoPagoConfigurationException ; try { $preference = $preferenceService -> create ( $payload ); } catch ( MercadoPagoConfigurationException $e ) { \ Log :: error ( 'MercadoPago configuration error' , [ 'message' => $e -> getMessage (), ]); return response () -> json ([ 'error' => 'Service configuration error' ], 500 ); } catch ( \ Exception $e ) { \ Log :: error ( 'Preference creation failed' , [ 'message' => $e -> getMessage (), 'payload' => $payload , ]); return response () -> json ([ 'error' => 'Preference creation failed' ], 500 ); }
PaymentService Process direct card payments
WebhookService Handle payment notifications
Additional Resources
Creating Preferences Guide Comprehensive guide to preference creation
MercadoPago API Documentation Official API reference