⚠️ Disclaimer: This plugin is community-maintained and is not officially affiliated with MercadoPago or Better Auth. See DISCLAIMER.md for full details.

Table of Contents

• Features
• Installation
• Quick Start
  • Server Setup
  • Client Setup
• Configuration
• Integrations
• Roadmap
• Contributing
• License

Features

• 🔐 Authentication-first payments — Payments tied to authenticated Better Auth users
• 💳 Subscription management — Create and manage recurring subscriptions with MercadoPago
• 🔔 Webhook handling — Built-in webhook verification and event processing
• 📦 Type-safe — Full TypeScript support with Zod validation
• 🔌 Pluggable — Drop-in Better Auth plugin with minimal configuration
• 🌎 LATAM-ready — Built specifically for MercadoPago's Latin American market

Installation

# npm
npm install better-auth-mp

# yarn
yarn add better-auth-mp

# pnpm
pnpm add better-auth-mp

# bun
bun add better-auth-mp

Peer Dependencies

Make sure you have the required peer dependencies installed:

bun add better-auth @prisma/client

Quick Start

Server Setup

Add the plugin to your Better Auth configuration:

// auth.ts (server)
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { mercadopago } from "better-auth-mp";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

export const auth = betterAuth({
  database: prismaAdapter(prisma, {
    provider: "postgresql",
  }),
  plugins: [
    mercadopago({
      accessToken: process.env.MP_ACCESS_TOKEN!,
      webhookSecret: process.env.MP_WEBHOOK_SECRET!,
    }),
  ],
});

Client Setup

Add the client plugin to your Better Auth client:

// auth-client.ts (client)
import { createAuthClient } from "better-auth/react";
import { mercadopagoClient } from "better-auth-mp/client";

export const authClient = createAuthClient({
  plugins: [mercadopagoClient()],
});

Environment Variables

# MercadoPago credentials
MP_ACCESS_TOKEN=APP_USR-xxxxxxxxxxxxxxxxxxxx
MP_WEBHOOK_SECRET=your-webhook-secret

# Better Auth
BETTER_AUTH_SECRET=your-auth-secret
BETTER_AUTH_URL=http://localhost:3000

Configuration

Plugin Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | accessToken | string | ✅ | MercadoPago Access Token (production or sandbox) | | webhookSecret | string | ✅ | Secret for webhook signature verification | | sandbox | boolean | ❌ | Enable sandbox mode (default: false) | | notificationUrl | string | ❌ | Override webhook URL (default: auto-detected from BETTER_AUTH_URL) |

mercadopago({
  accessToken: process.env.MP_ACCESS_TOKEN!,
  webhookSecret: process.env.MP_WEBHOOK_SECRET!,
  sandbox: process.env.NODE_ENV !== "production",
  notificationUrl: "https://yourdomain.com/api/auth/mercadopago/webhook",
})

Database Schema (ORM-agnostic)

This plugin is fully ORM-agnostic — it works with Prisma, Drizzle, or any other ORM/database supported by Better Auth.

The required schema is generated automatically using the Better Auth CLI. Run it once after configuring the plugin:

# bun
bunx @better-auth/cli generate

# npm
npx @better-auth/cli@latest generate

# pnpm
pnpm dlx @better-auth/cli@latest generate

# yarn
yarn dlx @better-auth/cli@latest generate

The CLI reads your auth.ts configuration and generates the necessary models/migrations for your configured ORM and database automatically.

Integrations

Next.js App Router

Create the webhook route handler:

// app/api/auth/[...betterauth]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);

The plugin automatically registers the webhook endpoint at /api/auth/mercadopago/webhook.

Webhook Events

The plugin handles the following MercadoPago webhook events:

| Event | Description | |-------|-------------| | subscription_preapproval | Subscription created or updated | | payment | Payment received, refunded, or failed |

Client Hooks (React)

import { authClient } from "@/lib/auth-client";

// In your component
const { data: session } = authClient.useSession();
const subscription = authClient.mercadopago.useSubscription();

Roadmap

| Feature | Status | |---------|--------| | ✅ Basic payment webhooks | Released | | ✅ Subscription management | Released | | ✅ Webhook signature verification | Released | | 🔄 One-click checkout via Brick | In progress | | 🔄 Subscription plan management UI | In progress | | 📋 Refund management | Planned | | 📋 Payment analytics endpoints | Planned | | 📋 Multi-currency support | Planned | | 📋 Installment (cuotas) support | Planned |

Contributing

We welcome contributions! Please read our CONTRIBUTING.md guide before submitting a PR.

License

MIT — Copyright © 2025 better-auth-mp contributors.

See DISCLAIMER.md for important legal information.