next-mercadopago

This repository provides various implementation patterns for integrating Mercado Pago into a Next.js application using the App Router. The primary use case demonstrated is a messaging application where users must pay or subscribe to post messages.

Available integration patterns include:

• Checkout Pro: Creates a payment preference and redirects the user to the Mercado Pago hosted checkout page. Includes webhook configuration for payment verification.
• Subscriptions: Implements subscription models (without an associated plan and with pending payments) and uses webhooks to handle subscription notifications.
• Checkout Bricks: Uses Mercado Pago's 'Bricks' to collect payment information directly within your application's UI.
• Marketplace (Split Payments): Acts as an intermediary between a buyer and a seller (e.g., a user wanting to post on someone else's wall), using Checkout Pro to split payments and retain a commission.
• Checkout API: Provides the highest level of UI control by using custom components and the Mercado Pago React component library to process payments securely and compliantly within your own platform.

To receive payment and subscription notifications, you must configure a Webhook in the Mercado Pago Developer Panel.

1. Expose your local environment: Before configuring, ensure your local port is exposed to the internet (e.g., using a tool like ngrok) so Mercado Pago can reach your machine.
2. Access Webhooks: Go to the Mercado Pago Developer Panel, select your application, and click on Webhooks in the left sidebar.
3. Configure Notifications: Click on Configurar notificaciones.
4. Set Environment and URL:
   • Select the desired environment (e.g., Modo productivo if using a test account).
   • In the Production URL field, use the base URL from your APP_URL environment variable and append your specific API endpoint. For example, if your endpoint is /api/mercadopago, the URL should look like https://your-exposed-url.com/api/mercadopago.
5. Select Events: Choose the specific events you wish to listen to and click Guardar configuración.

Testing: You can use the Simular notificación button in the panel to verify connectivity. Even if the simulation returns an error (e.g., because the payment ID doesn't exist), a successful log in your local terminal confirms that Mercado Pago can communicate with your application.

To implement subscriptions where users are redirected to Mercado Pago to complete a pending payment, use the PreApproval class from the mercadopago SDK. This method creates a subscription with a pending status and returns an init_point URL. You can then redirect the user to this URL to complete the transaction.

Key configuration options for the subscription body:

• back_url: The URL to redirect the user back to after the process.
• reason: A description of the subscription.
• auto_recurring: Defines the frequency (e.g., months), frequency type, amount, and currency.
• payer_email: The email of the user subscribing.
• status: Set to pending to allow the user to complete the payment on Mercado Pago's site.

import { PreApproval } from "mercadopago";

// Inside your API logic
const suscription = await new PreApproval(mercadopago).create({
  body: {
    back_url: process.env.APP_URL!,
    reason: "Suscripción a mensajes de muro",
    auto_recurring: {
      frequency: 1,
      frequency_type: "months",
      transaction_amount: 100,
      currency_id: "ARS",
    },
    payer_email: email,
    status: "pending",
  },
});

const url = suscription.init_point!;
// Redirect the user to this url

To update your application's state (e.g., granting access to a user) when a subscription is paid, you must implement a Webhook endpoint (Route Handler) to listen for subscription_preapproval events from Mercado Pago.

Workflow:

1. Receive a POST request from Mercado Pago.
2. Verify the type is subscription_preapproval.
3. Use the id from body.data.id to fetch the subscription details using PreApproval.get({ id }).
4. If preapproval.status is authorized, update your local database with the subscription ID.
5. Crucial: Always return a 200 OK response to Mercado Pago to acknowledge receipt. Only return non-200 status codes if you want Mercado Pago to retry the notification.

import { PreApproval } from "mercadopago";
import api, { mercadopago } from "@/api";

export async function POST(request: Request) {
  const body: { data: { id: string }; type: string } = await request.json();

  if (body.type === "subscription_preapproval") {
    const preapproval = await new PreApproval(mercadopago).get({ id: body.data.id });

    if (preapproval.status === "authorized") {
      // Update your user/database with the subscription ID
      await api.user.update({ suscription: preapproval.id });
    }
  }

  return new Response(null, { status: 200 });
}