@ar-agents/mercadopago

@ar-agents/mercadopago

Mercado Pago Agent Toolkit. Built on Vercel. 89 typed tools across the agent-relevant Mercado Pago API surface (Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Order Management, Customers, Cards, Cuotas, QR, 3DS, Point devices, Stores+POS, Account/Balance/Settlements, Webhooks, Disputes, Lookups, Bank Accounts) for the Vercel AI SDK 6 Experimental_Agent. Edge-Runtime-safe.

Reading this as an agent? Skip to AGENTS.md: decision tree, result schemas to memorize, error patterns, latency table.

Quick start

pnpm add @ar-agents/mercadopago ai zod

import { Experimental_Agent as Agent, stepCountIs } from "ai";
import { MercadoPagoClient, mercadoPagoTools, InMemoryStateAdapter } from "@ar-agents/mercadopago";

const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });

export const agent = new Agent({
  model: "anthropic/claude-sonnet-4-6",
  instructions: "Sos un asistente de billing para una SaaS argentina.",
  tools: mercadoPagoTools(mp, { state: new InMemoryStateAdapter(), backUrl: "https://example.com/done" }),
  stopWhen: stepCountIs(8),
});

const { text } = await agent.generate({
  prompt: "Cobrale $25.000 mensual a juan@example.com con razón 'Plan Pro'."
});

That's it. The agent picks create_subscription, returns an init_point_url you send to the customer, and the rest of the flow (first payment confirmation, recurring charges, webhooks) just works.

At a glance

Tools	30: Subscriptions, Payments, Refunds, Checkout Pro, Cuotas, QR in-store, Saved cards, Marketplace OAuth, Order Management, Point devices, 3DS, Webhooks. Full list.
Bundle size	41 KB ESM brotli'd (bundlephobia). Tree-shakable subpath exports for /vercel-kv + /otel.
Runtime	Vercel Edge, Node 18+, Cloudflare Workers, Deno: Web Crypto under the hood.
Tests	290 unit + property + failure-injection + benchmark. pnpm test, pnpm bench.
TypeScript	Strict mode, noUncheckedIndexedAccess, exactOptionalPropertyTypes. publint + arethetypeswrong all .
AR-specific knowledge	Cuotas with regulatory text (RG 5286/2023), AR issuer promo catalog, Subscription replay-protection, MLA-verified, ARS default.

Server-only

This package MUST run on the server. The constructor throws if instantiated in a browser context: the access token would be exposed in the JavaScript bundle. Use Server Components, Route Handlers, or Server Actions.

// ❌ Never. Throws at runtime AND would leak the token if it didn't.
"use client";
const mp = new MercadoPagoClient({ accessToken: ... });

// ✅ Server Component / Route Handler / Server Action.
import { MercadoPagoClient } from "@ar-agents/mercadopago";
export async function POST(req: Request) {
  const mp = new MercadoPagoClient({ accessToken: process.env.MP_ACCESS_TOKEN! });
  // ...
}

API reference

new MercadoPagoClient(options)

Server-side MP API client. Edge-Runtime safe.

Option	Default	Description
accessToken (required)	no	TEST- prefix for sandbox, APP_USR- for production.
baseUrl	https://api.mercadopago.com	Override for tests / regional hosts.
fetch	globalThis.fetch	Custom fetch (e.g., MSW for tests).
requestTimeoutMs	30_000	Per-request timeout.
maxRetries	1	5xx + network retries. 4xx never retried.
circuitBreaker	no	new CircuitBreaker({ ... }) to fail fast on cascading failures.
traceContext	no	OpenTelemetry context propagator (W3C trace headers).
onCall	no	Observability hook fired after every request.

mercadoPagoTools(client, options)

Returns the agent tool set wired to the given client.

Option	Required	Description
state	yes	SubscriptionStateAdapter: InMemoryStateAdapter, VercelKVSubscriptionStateAdapter, or your own.
backUrl	yes	HTTPS URL where MP redirects buyers after first payment. localhost rejected.
notificationUrl	no	Webhook URL for new payments / status changes.
oauth	no	{ clientId, clientSecret, redirectUri, tokenStore } for marketplace OAuth flows.
webhookSecret	no	HMAC secret for handle_webhook (paste from MP dev panel).
descriptions	no	Override individual tool descriptions for fine-tuning the LLM.

Subpath exports

Subpath	When to use
@ar-agents/mercadopago	The 30 tools + client. Always-on.
@ar-agents/mercadopago/vercel-kv	Vercel KV–backed adapters: VercelKVSubscriptionStateAdapter, VercelKVOAuthTokenStore, VercelKVIdempotencyCache, VercelKVAuditLog, VercelKVRateLimiter (distributed). Pulls in @vercel/kv peer dep.
@ar-agents/mercadopago/otel	instrumentMercadoPagoClient + instrumentMercadoPagoTools for OpenTelemetry spans + metrics. Pulls in @opentelemetry/api peer dep.

Production patterns

Idempotency by default

Every POST request gets an auto-generated UUID idempotency key: your app survives network blips without double-charging. For LLM-driven retries, create_payment, create_subscription, create_payment_preference, and refund_payment use a deterministic key derived from the inputs, so a tool retried with the same inputs returns the existing resource instead of creating a duplicate.

Webhook verification

import { verifyWebhookSignature, parseWebhookEvent } from "@ar-agents/mercadopago";

export async function POST(req: Request) {
  const url = new URL(req.url);
  const rawBody = await req.text();
  const event = parseWebhookEvent(JSON.parse(rawBody), url.searchParams);

  const ok = await verifyWebhookSignature({
    requestId: req.headers.get("x-request-id"),
    dataId: event!.dataId,
    signatureHeader: req.headers.get("x-signature"),
    secret: process.env.MP_WEBHOOK_SECRET!,
  });
  if (!ok) return new Response("Invalid signature", { status: 401 });
  // process event...
}

5-minute replay-tolerance window built in. Constant-time HMAC comparison.

Distributed rate limiting

For multi-region or marketplace deploys where serverless instances would each get their own per-process bucket:

import { VercelKVRateLimiter } from "@ar-agents/mercadopago/vercel-kv";

const limiter = new VercelKVRateLimiter({
  key: "mp-account-prod",
  capacity: 50,
  refillPerSecond: 25,
});

Cookbook

9 recipes in ./cookbook: Checkout Pro, SaaS subscription, webhook handler, marketplace split, QR in-store, 3DS challenge, manual capture, recovery patterns, full OpenTelemetry wiring.

Comparison

	@ar-agents/mercadopago	mercadopago (official SDK)	Hand-rolled
Tools as Vercel AI SDK 6 schemas	✓	no	build it
AR-specific (cuotas, AR issuer promos, AR phone, MLA-verified)	✓	no	weeks
AGENTS.md per package (LLM-readable)	✓	no	:
Idempotency-by-default for state mutations	✓	no	build it
Webhook signature verify + 5-min replay window	✓	client only	build it
Edge Runtime support	✓	Node-only	build it
Vercel KV adapters via subpath	✓	no	:
OpenTelemetry instrumentation + recipe	✓	no	build it
Circuit breaker + deadline propagation	✓	no	build it
Tool middleware (compose audit/rate/metrics)	✓	no	:
Time to first cobro	30 min	1+ week	6-8 weeks

See MIGRATION.md for a side-by-side mercadopago → @ar-agents/mercadopago migration guide.

Security

This package handles money. Read SECURITY.md before deploying:

• The constructor refuses to instantiate in a browser context (token leak prevention).
• Every webhook handler MUST call verifyWebhookSignature before trusting payload contents.
• Irreversible tools (refund_payment, cancel_*, delete_customer_card) include explicit confirm-with-user instructions in their descriptions; the LLM should ask before calling.
• Report vulnerabilities privately per SECURITY.md.

License

MIT · Nazareno Clemente

If this saves your team weeks of MP integration work, consider sponsoring.