README

Una integración optimizada, ligera y moderna de la API de Mercado Pago para Laravel.

A diferencia del SDK oficial o paquetes antiguos, esta librería no utiliza cURL nativo. Está construida completamente sobre el HTTP Client de Laravel (Guzzle Wrapper), lo que garantiza:

🚀 Mejor rendimiento: Aprovecha el manejo de conexiones de Guzzle.
🛡️ Seguridad: Manejo automático de certificados SSL y Timeouts.
🧹 Código Limpio: Sin archivos .pem manuales ni variables globales.
🐛 Depuración: Compatible con herramientas como Laravel Telescope o Ray.

📋 Requisitos

PHP >= 7.4
Laravel >= 8.x, 9.x, 10.x, 11.x, 12.x
Cuenta de desarrollador en Mercado Pago.

🚀 Instalación

Instala el paquete mediante Composer:

composer require aziendeglobal/laravel-mercadopago-rest

⚙️ Configuración

Publicar el archivo de configuración:

Esto creará el archivo config/mercadopago.php.

php artisan vendor:publish --tag=mercadopago-config

Configurar Variables de Entorno:

Agrega tus credenciales en el archivo .env. Se recomienda encarecidamente usar el ACCESS_TOKEN para integraciones modernas.

# Credenciales (Obtenidas en developers.mercadopago.com)
MP_ACCESS_TOKEN=APP_USR-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Opcional: Integrator ID (Si eres partner)
MP_INTEGRATOR_ID=

# Legacy (Solo si no usas Access Token)
MP_APP_ID=
MP_APP_SECRET=

## ⚡ Uso Rápido (Facade)

El paquete incluye un Facade MP para acceder rápidamente a los métodos de forma estática. Crear una Preferencia de Pago (Checkout Pro)

Este es el flujo para redirigir al usuario a pagar a Mercado Pago.

use MP;

public function createPreference()
{
    $preferenceData = [
        "items" => [
            [
                "title" => "Suscripción Premium",
                "quantity" => 1,
                "currency_id" => "ARS", // MXN, BRL, USD, CLP...
                "unit_price" => 1500.00
            ]
        ],
        "payer" => [
            "email" => "cliente@ejemplo.com"
        ],
        "back_urls" => [
            "success" => route('payment.success'),
            "failure" => route('payment.failure'),
            "pending" => route('payment.pending')
        ],
        "auto_return" => "approved",
        "external_reference" => "order_id_1234" // Tu ID de orden local
    ];

    try {
        $preference = MP::create_preference($preferenceData);
        
        // Redirigir al usuario al Checkout de Mercado Pago
        return redirect($preference['response']['init_point']);
        
    } catch (\Exception $e) {
        return back()->with('error', $e->getMessage());
    }
}

📡 Recibir Notificaciones (Webhooks)

Para recibir actualizaciones de estado de pagos en tiempo real (cuando el pago se acredita), configura una ruta en tu api.php.

Definir la ruta:

// routes/api.php
use App\Http\Controllers\PaymentController;

Route::post('/mp/webhook', [PaymentController::class, 'handleWebhook']);

Crear el controlador:

// App/Http/Controllers/PaymentController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use MP;

class PaymentController extends Controller
{
    public function handleWebhook(Request $request)
    {
        // Mercado Pago envía el ID y el tipo en el body o query params
        $type = $request->input('type') ?? $request->input('topic');
        $id   = $request->input('data.id') ?? $request->input('id');

        if ($type === 'payment') {
            // Importante: Consultar el estado real a la API para verificar autenticidad
            $payment = MP::get_payment($id);
            
            if ($payment['status'] == 200) {
                $status = $payment['response']['status'];
                $externalRef = $payment['response']['external_reference'];

                if ($status === 'approved') {
                    // TODO: Activar la orden en tu base de datos usando $externalRef
                }
            }
        }

        return response()->json(['status' => 'ok'], 200);
    }
}

🧪 Pruebas y Sandbox

Activar modo Sandbox

Puedes forzar el modo Sandbox en tiempo de ejecución. Esto hará que las peticiones vayan al entorno de pruebas.

MP::sandbox_mode(true);

Crear Usuarios de Prueba

Mercado Pago requiere usuarios "Test" (Comprador y Vendedor) para probar pagos en Sandbox sin usar dinero real.

// Crear un usuario de prueba
$testUser = MP::create_user_test([
    "site_id" => "MLA" // Cambiar según tu país: MLM, MLB, MCO, etc.
]);

// Guarda estos datos para hacer tus pruebas
echo "Email: " . $testUser['response']['email']; 
echo "Pass: " . $testUser['response']['password'];

🔄 Suscripciones (Preapproval)

Para cobros recurrentes (débitos automáticos).

$preapproval_data = [
    "payer_email" => "cliente@test.com",
    "back_url" => "[https://mitienda.com/success](https://mitienda.com/success)",
    "reason" => "Suscripción Mensual",
    "external_reference" => "sub_123",
    "auto_recurring" => [
        "frequency" => 1,
        "frequency_type" => "months",
        "transaction_amount" => 1000,
        "currency_id" => "ARS"
    ]
];

$subscription = MP::create_preapproval_payment($preapproval_data);

// Redirigir al usuario a suscribirse
return redirect($subscription['response']['init_point']);

🛠️ Métodos Disponibles

Pagos (Collections)

MP::get_payment($id)

MP::search_payment($filters, $offset, $limit)

MP::cancel_payment($id)

MP::refund_payment($id) (Devolución total)

Preferencias (Checkout)

MP::create_preference($data)

MP::update_preference($id, $data)

MP::get_preference($id)

Suscripciones (Preapprovals)

MP::create_preapproval_payment($data)

MP::get_preapproval_payment($id)

MP::cancel_preapproval_payment($id)

MP::create_preapproval_plan_payment($data)

MP::update_preapproval_plan_payment($id, $data)

Genéricos (Para endpoints no listados)

Si Mercado Pago lanza un endpoint nuevo que no está listado aquí, puedes usar los métodos genéricos. El paquete se encarga de la autenticación.

// GET
$res = MP::get('/v1/payment_methods');

// POST
$res = MP::post('/v1/advanced_payments', $dataArray);

💉 Inyección de Dependencias

Si prefieres no usar Facades, puedes inyectar la clase directamente en tus controladores.

use AziendeGlobal\LaravelMercadoPago\MP;

class PaymentController extends Controller
{
    protected $mp;

    public function __construct(MP $mp) 
    {
        $this->mp = $mp;
    }

    public function checkStatus($id) 
    {
        return $this->mp->get_payment($id);
    }
}

📝 Estructura de Respuesta

Todas las respuestas de la librería siguen este formato estandarizado para facilitar el manejo de errores:

[
    "status" => 200,      // Código HTTP (200, 201, 400, 404, etc.)
    "response" => [ ... ] // JSON decodificado de Mercado Pago con la data
]

Licencia

The MIT License (MIT). Por favor ve el Archivo de Licencia para más información.

aziendeglobal / laravel-mercadopago-rest

Maintainers

Details