Better Auth Mp

better-auth-mp

MercadoPago plugin for Better Auth — one-time payments, recurring subscriptions, webhook handling, and ORM-agnostic DB schema. Specifically built for Latin America.

• npm: better-auth-mp
• repo: https://github.com/IvanTsxx/better-auth-mp
• version: 1.0.0+

Installation

bun add better-auth-mp
# or
npm install better-auth-mp

Peer dependencies (must already be installed):

bun add better-auth @prisma/client zod

Environment Variables

MP_ACCESS_TOKEN=APP_USR-xxxxxxxxxxxxxxxxxxxx   # from MercadoPago dashboard
MP_WEBHOOK_SECRET=your-webhook-secret          # set when registering the webhook in MP
BETTER_AUTH_SECRET=your-auth-secret
BETTER_AUTH_URL=https://yourdomain.com         # must be HTTPS in production

Server Setup

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

const prisma = new PrismaClient();

export const auth = betterAuth({
  database: prismaAdapter(prisma, { provider: "postgresql" }),
  plugins: [
    mercadoPagoPlugin({
      accessToken: process.env.MP_ACCESS_TOKEN!,
      webhookSecret: process.env.MP_WEBHOOK_SECRET!,
      // optional:
      sandbox: process.env.NODE_ENV !== "production",
      baseUrl: process.env.BETTER_AUTH_URL,

      // Called every time MP sends a payment webhook
      onPaymentUpdate: async ({ payment, status, resultType, mpPayment }) => {
        if (resultType === "success") {
          // grant feature, send email, etc.
        }
      },

      // Called every time MP sends a subscription webhook
      onSubscriptionUpdate: async ({ subscription, status, mpSubscription }) => {
        if (status === "authorized") {
          // activate subscription in your app
        }
      },
    }),
  ],
});

Plugin Options

Client Setup

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

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

Database Schema

The plugin uses Better Auth's CLI to auto-generate database models — it is ORM-agnostic (Prisma, Drizzle, etc.).

# Generate migrations/models from your auth.ts config
bunx @better-auth/cli generate

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

This creates three models:

• mercadoPagoPayment — stores every one-time payment
• mercadoPagoSubscription — stores recurring subscriptions
• mercadoPagoPlan — stores subscription plan definitions

Next.js App Router Integration

// 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 these endpoints under /api/auth/mercado-pago/:

One-Time Payments — Checkout Pro

1. Create a preference (server action or route handler)

const { data } = await authClient.mercadopago.createPayment({
  items: [
    {
      id: "plan-pro",
      title: "Pro Plan",
      quantity: 1,
      unitPrice: 9999,     // in the smallest currency unit (ARS cents are NOT used — use full pesos)
      currencyId: "ARS",
    },
  ],
  backUrls: {
    success: "https://yourdomain.com/payments?status=success",
    failure: "https://yourdomain.com/payments?status=failure",
    pending: "https://yourdomain.com/payments?status=pending",
  },
  // optional: prevent duplicates
  idempotencyKey: "unique-key-per-intent",
});

// Redirect user to the checkout
window.location.href = data.checkoutUrl;

2. Handle the result back URL

After the user pays, MP redirects to your backUrls. Use getPaymentResultType on the server to map status:

import { getPaymentResultType } from "better-auth-mp";

// resultType is: "success" | "pending" | "error"
const resultType = getPaymentResultType(mpStatus);

3. Handle webhook (already done automatically)

MP calls POST /api/auth/mercado-pago/webhook. The plugin:

1. Verifies the HMAC signature (if webhookSecret is set)
2. Fetches full payment data from MP API
3. Updates mercadoPagoPayment in DB
4. Calls onPaymentUpdate if configured

Register your webhook in the MercadoPago dashboard pointing to: https://yourdomain.com/api/auth/mercado-pago/webhook

Subscriptions

Create a plan (admin, run once)

const { data } = await authClient.mercadopago.createPlan({
  name: "Pro Monthly",
  autoRecurring: {
    frequency: 1,
    frequencyType: "months",
    transactionAmount: 9999,
    currencyId: "ARS",
  },
  description: "Full access to Pro features",
});

const planId = data.planId; // store this

Subscribe a user (with card token from MP Brick)

// cardTokenId comes from MercadoPago's CardPayment Brick or SDK
const { data } = await authClient.mercadopago.createSubscriptionWithPlan({
  planId: "YOUR_MP_PLAN_ID",
  payerEmail: session.user.email,
  cardTokenId: cardTokenId,
  identification: { type: "DNI", number: "12345678" }, // optional
});

Subscribe a user (redirect flow, no card upfront)

const { data } = await authClient.mercadopago.createSubscription({
  reason: "Pro Monthly",
  payerEmail: session.user.email,
  autoRecurring: {
    frequency: 1,
    frequencyType: "months",
    transactionAmount: 9999,
    currencyId: "ARS",
  },
  backUrl: "https://yourdomain.com/subscriptions",
});

// Redirect user to data.checkoutUrl

Manage subscriptions

// Pause
await authClient.mercadopago.updateSubscription({
  subscriptionId: mpSubscriptionId,
  status: "paused",
});

// Resume
await authClient.mercadopago.updateSubscription({
  subscriptionId: mpSubscriptionId,
  status: "authorized",
});

// Cancel
await authClient.mercadopago.cancelSubscription({
  subscriptionId: mpSubscriptionId,
});

// List user subscriptions
const { data } = await authClient.mercadopago.getSubscriptions({
  filters: { status: "authorized" },
  limit: 20,
  offset: 0,
});

Webhook Events Handled

Security — Built-in

The plugin includes these protections out of the box; no extra code needed:

• HMAC signature verification — validates x-signature + x-request-id headers from MP
• Rate limiting — 10 req/min per user on payment/subscription creation; 1000 req/min on the webhook
• Idempotency keys — pass idempotencyKey on create calls to prevent duplicate charges
• Amount validation — DB amount vs. MP payment amount is compared at webhook time
• Metadata sanitization — user-supplied metadata is sanitized before storing

TypeScript Types

import type {
  MercadoPagoPluginOptions,
  PaymentStatus,
  SubscriptionStatus,
  PreferenceItem,
  PreferenceOutput,
  PaymentOutput,
  PaginatedPayments,
  SubscriptionOutput,
  PlanOutput,
  PaginatedSubscriptions,
  MercadoPagoPaymentRecord,
  MercadoPagoSubscriptionRecord,
  MercadoPagoPlanRecord,
} from "better-auth-mp/types";

Key status types:

type PaymentStatus =
  | "pending" | "approved" | "authorized"
  | "in_process" | "in_mediation"
  | "rejected" | "cancelled" | "refunded" | "charged_back";

type SubscriptionStatus =
  | "pending" | "authorized" | "paused"
  | "cancelled" | "expired" | "unpaid";

Common Patterns

Protect routes based on subscription status

// In a Next.js Server Component or middleware
const subscriptions = await authClient.mercadopago.getSubscriptions({
  filters: { status: "authorized" },
});
const isSubscribed = subscriptions.data?.subscriptions.length > 0;

Grant access after payment webhook

mercadoPagoPlugin({
  accessToken: process.env.MP_ACCESS_TOKEN!,
  onPaymentUpdate: async ({ payment, resultType }) => {
    if (resultType === "success") {
      await db.user.update({
        where: { id: payment.userId },
        data: { isPro: true },
      });
    }
  },
})

Known Limitations (as of v1.0.0)

• The auto_return: "approved" on preferences requires an HTTPS URL — will not work on localhost without a tunnel (e.g. ngrok)
• Marketplace / split-payment features are in the plugin schema but not yet exposed as endpoints — do not implement them
• One-click Checkout Brick integration is planned but not released yet
• Refund management endpoints are planned — not in current release
• The client plugin (mercadopagoClient) provides type inference only; it does not add client-side state hooks beyond session