Introduction

​

Overview

​

What It Solves

• Credential Management - Resolves credentials from configuration and environment variables automatically
• SDK Configuration - Configures the Mercado Pago SDK with access tokens and runtime environment settings
• Service Layer - Provides injectable services for all major Mercado Pago operations
• Webhook Security - Registers a webhook endpoint with HMAC signature validation when a secret is configured
• Development Support - Exposes demo routes for local testing and development

​

Key Features

​

Comprehensive Service Coverage

• PreferenceService - Create and manage payment preferences for Checkout Pro
• PaymentService - Process and query payments
• RefundService - Handle full and partial refunds
• CustomerService - Manage customer records
• CardService - Store and manage customer cards
• PaymentMethodService - Query available payment methods
• TestUserService - Generate test users for QA environments
• WebhookService - Receive and validate Mercado Pago notifications

​

Auto-Discovery Support

Fitodac\LaravelMercadoPago\LaravelMercadoPagoServiceProvider::class

​

Flexible Route Configuration

• Always Active: Production webhook endpoint at /api/mercadopago/webhooks
• Demo Routes: Development and testing endpoints (enabled only in local and testing environments)
• Customizable Prefix: Configure route prefixes via environment variables

​

Security First

• HMAC signature validation for webhook authenticity
• Environment-based credential resolution
• Demo route protection (disabled in production)
• Configurable runtime environments

​

Requirements

​

What’s NOT Included

• Database migrations - Payment persistence logic belongs in your application
• Blade views - Frontend integration is project-specific
• UI components - JavaScript widgets and checkout forms are implemented separately
• Job queues - Queue configuration depends on your architecture
• Business logic - Authentication, authorization, and domain rules stay in your app

​

Architecture Philosophy

1. Services encapsulate SDK calls - Each service wraps specific Mercado Pago API functionality
2. Dependency injection ready - All services are registered as singletons in the container
3. Controller-agnostic - Use the services in controllers, actions, jobs, or commands
4. Testable - Services can be mocked and tested independently

​

Recommended Implementation Pattern

use Fitodac\LaravelMercadoPago\Services\PreferenceService;
use Illuminate\Http\Request;

class CheckoutController
{
    public function __construct(
        private PreferenceService $preferenceService
    ) {}
    
    public function createPreference(Request $request)
    {
        $validated = $request->validate([
            'items' => 'required|array',
            'items.*.title' => 'required|string',
            'items.*.quantity' => 'required|integer|min:1',
            'items.*.unit_price' => 'required|numeric|min:0',
        ]);
        
        $preference = $this->preferenceService->create($validated);
        
        return response()->json([
            'id' => $preference['id'],
            'init_point' => $preference['init_point'],
        ]);
    }
}

​

Next Steps