En este tutorial vamos a armar un mini proyecto con Next.js para integrar Mercado Pago usando Checkout Pro. Vas a aprender a crear un endpoint API en el backend que genere la preferencia de pago, y un frontend para enviar los datos del producto y así poder armar esa preferencia.

Recordá que cuando hablamos de “preferencia” nos referimos a la info básica del producto que querés vender: nombre, precio, cantidad y demás.

Primero en tu proyecto de next js hay que instalar el sdk de mercado pago corriendo el siguiente comando:

npm install @mercadopago/sdk-react

Una vez hecho eso te voy a mostrar los archivos que necesitas crear y cómo organizarlos dentro del sistema de rutas.

Acá hay tres archivos importantes que vamos a usar:

1. global.d.ts, donde vamos a agregar unas configuraciones mínimas para que todo funcione bien con TypeScript y mercadopago.

2. page.tsx, que es el archivo principal del frontend en Next.js donde vamos a mostrar el botón de pago.

3. route.ts, que va en la ruta api/mercadopago/route.ts y se encarga de la lógica del backend y del armado de la preferencia.

1) Archivo global.d.ts

Dentro de este archivo hay que poner esta simple linea

declare module 'mercadopago';

El archivo global.d.ts con declare module 'mercadopago'; le indica a TypeScript que existe un módulo llamado 'mercadopago', permitiendo importar y usar esa librería sin errores de tipado.

2) Archivo page.tsx: El Frontend

Este es el archivo principal de nextjs. Lo vamos a utilizar para construir el frontend que mostrará un botón de pago de Mercado Pago, generando la preferencia de pago con los datos de nuestro producto.

El código seria algo como esto 👇

'use client';

import { initMercadoPago, Wallet } from '@mercadopago/sdk-react';
import { useState } from 'react';

initMercadoPago('public_key', { locale: 'es-AR' });

export default function ClientWallet() {
  const [preferenceId, setPreferenceId] = useState<string | null>(null);

  const handleClick = async () => {
    const res = await fetch('/api/mercadopago', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: 'producto con next',
        price: 1000,
        quantity: 1,
      }),
    });

    const data = await res.json();
    setPreferenceId(data.id);
  };

  return (
    <div>
      <button onClick={handleClick}>Pagar</button>
      {preferenceId && <Wallet initialization={{ preferenceId }} />}
    </div>
  );
}

vamos a enternder un poco que es lo que estamos haciendo en este frontend

use client

en la primer linea con 'use client' se convierte el componente en client-side, y eso es clave porque usamos useState para manejar cuándo mostrar el botón de Mercado Pago.

imports

lo siguiente es importar las cosas que necesitamos de mercado pago como el initMercadoPago, Wallet y tambien el useState de React.

Inicialización del SDK

Llamamos a initMercadoPago con nuestra API_KEY(que hay que conseguirla desde el panel de mercadoPago) y la configuración regional. Esto prepara todo para que el SDK funcione correctamente en nuestra app.

preferenceId

Creamos un estado con useState para guardar el id de la preferencia. Cuando enviamos la información de nuestro producto al backend, Mercado Pago toma esos datos y genera una preferencia de pago. A cambio, nos devuelve un id único que representa esa preferencia.

Ese id es clave: es el que usamos cuando queremos mostrar el botón de pago con Checkout Pro, y le dice a Mercado Pago qué producto mostrar, con qué precio y cantidad.

Función handleClick

En este funcion hacemos un simple POST a nuestra api para enviarlos los datos de nuestro producto, para ello dentro del body de nuestro POST enviamos el title (nombre del producto), su precio y tambien su cantidad. Hay mas cosas que se podrian enviar al backend para que arme la preferencia pero estas son las cosas minimas que mercado pago necesita.

Por ultimo en la constante data guardamos la respuesta que nos devuelve el backend(el preference id de nuestor producto) y lo guardamos en nuestro estado.

Renderizado condicional del botón de pago

Si existe un preferenceId, mostramos el componente del SDK de Mercado Pago, que renderiza automáticamente el botón de pago con todos los datos cargados.

Este componente es simple, pero hace todo lo necesario: conecta el frontend con el backend, y con Mercado Pago.

1. Archivo route.ts: El Backend

import { NextRequest } from 'next/server';
import { MercadoPagoConfig, Preference } from 'mercadopago';

const client = new MercadoPagoConfig({
  accessToken: 'acces_token',
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();

    const preferenceData = {
      items: [
        {
          title: body.title,
          quantity: Number(body.quantity),
          unit_price: Number(body.price),
          currency_id: 'ARS',
        },
      ],
      back_urls: {
        success: 'https://www.youtube.com/@onthecode',
        failure: 'https://www.youtube.com/@onthecode',
        pending: 'https://www.youtube.com/@onthecode',
      },
      auto_return: 'approved',
    };

    const preference = new Preference(client);
    const result = await preference.create({ body: preferenceData });

    return new Response(JSON.stringify({ id: result.id }), {
      status: 200,
      headers: {
        'Content-Type': 'application/json',
      },
    });
  } catch (error) {
    console.error('Error al crear la preferencia:', error);
    return new Response(JSON.stringify({ error: 'Error al crear la preferencia :(' }), {
      status: 500,
      headers: {
        'Content-Type': 'application/json',
      },
    });
  }
}

Inicialización del cliente de Mercado Pago

Usamos MercadoPagoConfig para crear una instancia del cliente, pasándole nuestro accessToken (la clave secreta que obtenés desde tu cuenta de Mercado Pago). Con eso ya podemos hacer llamadas seguras al servicio desde el backend.

Función POST

Esta función se activa cuando el frontend hace una petición a /api/mercadopago. Recibimos los datos del producto desde el cuerpo del request: título, precio y cantidad.

Armado de la preferencia

Con esos datos, creamos un objeto llamado preferenceData. Acá le pasamos todo lo que necesita Mercado Pago para armar el checkout:

Los items (producto, precio, cantidad, moneda).

Las back_urls, que son las URLs adonde redirigir al usuario después del pago (sea exitoso, fallido o pendiente).

Y auto_return: 'approved', que hace que el usuario vuelva automáticamente cuando el pago se aprueba.

Creación de la preferencia

Con new Preference(client).create(...) mandamos los datos a Mercado Pago. Si todo sale bien, nos devuelve un id, que es la preferencia de pago ya lista.

Respuesta al frontend

Devolvemos ese id al frontend en formato JSON. Con eso, el botón de pago ya sabe qué mostrar.

Manejo de errores

Si algo sale mal, lo mostramos en consola y devolvemos una respuesta con error. Así evitamos que la app se rompa sin explicación.

Con esto ya deberíamos tener lista la pasarela de pago con Checkout Pro, usando los datos de nuestro producto. Al hacer clic en el botón "Pagar", se genera la preferencia y se renderiza automáticamente el botón de Mercado Pago.

Al presionar ese botón, nos lleva directo al flujo de pago, donde el usuario va a ver el producto con su precio, cantidad y podrá completar la compra.

Antes de cerrar, no quiero dejar de recomendarte un video que te puede ayudar mucho a configurar el ambiente de pruebas de Mercado Pago. En ese video te muestro cómo crear tu app desde el panel de desarrollador, cómo generar las credenciales necesarias (la public_key para el frontend y la access_token o secret_key para el backend), y también cómo crear cuentas de prueba para simular pagos.

también te dejo link al código completo en github

Me dejarias una estrella en el repo? ⭐️😊 Repositorio en Github

Muchas Gracias