@ar-agents/mercadopago 0.7.0 → 0.9.0

package/cookbook/03-webhook-handler.ts

@@ -0,0 +1,162 @@
+/**
+ * Recipe 03 — Production-grade webhook handler.
+ *
+ * # The 3-line summary
+ *
+ * - Verify HMAC-SHA256 signature → reject with 401 if invalid (replay protection included)
+ * - Parse the event (topic + dataId) from query/body (MP sends in both)
+ * - Auto-fetch the underlying resource (Payment / Preapproval / Order)
+ * - Dispatch by topic to your business logic
+ *
+ * Without HMAC verify, ANYONE can POST to your webhook URL and forge
+ * payments/cancellations. The lib's `verifyWebhookSignature` rejects
+ * stale signatures (>5min old) too — replay attack protection.
+ *
+ * # Why use the agent's `handle_webhook` tool vs calling primitives manually
+ *
+ * The tool consolidates verify + parse + auto-fetch + dispatch into one
+ * call. Saves ~30 lines per webhook handler vs the manual chain.
+ *
+ * # Edge Runtime
+ *
+ * This recipe is fully Edge-compatible. Webhook handlers benefit from Edge
+ * (lower cold-start = faster MP-acked, fewer 500s during traffic spikes).
+ */
+
+import {
+  MercadoPagoClient,
+  parseWebhookEvent,
+  verifyWebhookSignature,
+} from "@ar-agents/mercadopago";
+
+export const runtime = "edge";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+const WEBHOOK_SECRET = process.env.MP_WEBHOOK_SECRET!;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Approach A — Manual primitives (more control, more code)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function POST(req: Request) {
+  // 1. Read the RAW body — DO NOT use req.json() before HMAC verify, as
+  //    JSON.stringify changes whitespace and breaks the signature.
+  const rawBody = await req.text();
+
+  const signatureHeader = req.headers.get("x-signature");
+  const requestId = req.headers.get("x-request-id");
+  const url = new URL(req.url);
+
+  // 2. Parse the event from body or query (MP sends in both).
+  let parsedBody: unknown;
+  try {
+    parsedBody = JSON.parse(rawBody);
+  } catch {
+    return new Response("invalid JSON", { status: 400 });
+  }
+  const event = parseWebhookEvent(parsedBody, url.searchParams);
+  if (!event) {
+    return new Response("unrecognized webhook shape", { status: 400 });
+  }
+
+  // 3. Verify HMAC + replay-tolerance window.
+  const verified = await verifyWebhookSignature({
+    requestId,
+    dataId: event.dataId,
+    signatureHeader,
+    secret: WEBHOOK_SECRET,
+  });
+  if (!verified) {
+    return new Response("unauthorized", { status: 401 });
+  }
+
+  // 4. Dispatch by topic.
+  try {
+    switch (event.topic) {
+      case "payment":
+      case "payment.created":
+      case "payment.updated": {
+        const payment = await mp.getPayment(event.dataId);
+        await handlePayment(payment);
+        break;
+      }
+      case "subscription_preapproval":
+      case "preapproval": {
+        const sub = await mp.getPreapproval(event.dataId);
+        await handleSubscription(sub);
+        break;
+      }
+      case "subscription_authorized_payment": {
+        // The dataId IS the authorized_payment id — list under parent
+        // preapproval to get full context.
+        await handleRecurringCharge(event.dataId);
+        break;
+      }
+      case "merchant_order": {
+        const mo = await mp.getMerchantOrder(event.dataId);
+        await handleMerchantOrder(mo);
+        break;
+      }
+      case "point_integration_wh": {
+        const intent = await mp.getPointPaymentIntent(event.dataId);
+        await handlePointPaymentIntent(intent);
+        break;
+      }
+      default:
+        // Unknown topic — log and acknowledge so MP doesn't retry forever.
+        console.warn(`Unhandled webhook topic: ${event.topic}`);
+    }
+  } catch (err) {
+    // Return 5xx so MP retries (it has built-in exponential backoff).
+    console.error("webhook handler failed:", err);
+    return new Response("internal error", { status: 500 });
+  }
+
+  return new Response("ok", { status: 200 });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Approach B — Agent tool (let the agent dispatch)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Alternative: pass everything to an agent + the `handle_webhook` tool.
+ * Useful when your business logic varies by webhook content and an LLM
+ * makes the decision (e.g., "if this payment is for an old SKU, refund it").
+ *
+ * Note: this is HIGHER LATENCY than approach A and uses LLM tokens. Only
+ * use when LLM reasoning is genuinely required.
+ */
+// export async function POST_via_agent(req: Request) {
+//   const rawBody = await req.text();
+//   const result = await agent.generate({
+//     prompt: `Procesá este webhook de MP. Topic + body:\n${rawBody}`,
+//     toolChoice: "required",
+//     tools: mercadoPagoTools(mp, {
+//       state, backUrl, webhookSecret: WEBHOOK_SECRET, oauth: {...}
+//     }),
+//   });
+// }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Business logic stubs
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function handlePayment(payment: unknown) {
+  // Update your DB, fire shipping flow, send notification, etc.
+}
+async function handleSubscription(sub: unknown) {
+  /* ... */
+}
+async function handleRecurringCharge(authorizedPaymentId: string) {
+  /* ... */
+}
+async function handleMerchantOrder(mo: unknown) {
+  /* ... */
+}
+async function handlePointPaymentIntent(intent: unknown) {
+  /* ... */
+}

package/cookbook/04-marketplace-split.ts

@@ -0,0 +1,194 @@
+/**
+ * Recipe 04 — Marketplace platform with seller OAuth + split payments.
+ *
+ * # The Rappi/Tienda Nube pattern
+ *
+ * Your platform aggregates sellers. Each seller has their own MP account.
+ * Buyers pay through your platform; you take a marketplace fee; the rest
+ * goes to the seller's MP account.
+ *
+ * # Flow
+ *
+ * **One-time per seller**:
+ * 1. Seller clicks "Conectar Mercado Pago" on your dashboard
+ * 2. Your server redirects them to MP's OAuth authorize URL
+ *    (`oauth_authorize_url` tool)
+ * 3. Seller approves; MP redirects back with `?code=...&state=...`
+ * 4. Your server exchanges code → token bundle (`oauth_exchange_code`)
+ * 5. You PERSIST the bundle keyed by `token.user_id` (use OAuthTokenStore)
+ *
+ * **Per transaction**:
+ * 1. Buyer completes purchase on your platform
+ * 2. Your server fetches the seller's persisted token
+ * 3. (If expired) refresh via `oauth_refresh_token`
+ * 4. Instantiate `new MercadoPagoClient({ accessToken })` AS THE SELLER
+ * 5. Create a Preference / Order with `marketplace_fee` + `collector_id`
+ * 6. Funds route to the seller; fee splits off to your account
+ *
+ * # Key insight
+ *
+ * `marketplace_fee` is in ARS, NOT a percentage. Compute it from your
+ * commission rate using `compute_marketplace_fee` (PURE helper, no network).
+ */
+
+import {
+  buildAuthorizeUrl,
+  computeMarketplaceFee,
+  exchangeCodeForToken,
+  expirationTimeMs,
+  InMemoryOAuthTokenStore,
+  isExpiringSoon,
+  MercadoPagoClient,
+  refreshAccessToken,
+} from "@ar-agents/mercadopago";
+
+// In production: VercelKVOAuthTokenStore
+const oauthStore = new InMemoryOAuthTokenStore();
+
+const CLIENT_ID = process.env.MP_CLIENT_ID!;
+const CLIENT_SECRET = process.env.MP_CLIENT_SECRET!;
+const REDIRECT_URI = "https://yourapp.com/api/mp/oauth/callback";
+const MARKETPLACE_NAME = "MyMarketplace";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1 — Send seller to MP for authorization
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function startSellerOAuthFlow(input: { sellerSessionId: string }) {
+  // `state` should be bound to the seller's session and verified on callback
+  // (CSRF protection). Use a secure random token + persist against the session.
+  const state = `${input.sellerSessionId}:${crypto.randomUUID()}`;
+  // ... persist state → sellerSessionId mapping in your DB ...
+  return buildAuthorizeUrl({
+    clientId: CLIENT_ID,
+    redirectUri: REDIRECT_URI,
+    state,
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2 — Handle the OAuth callback
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function handleOAuthCallback(req: Request) {
+  const url = new URL(req.url);
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  if (!code || !state) {
+    return new Response("missing code/state", { status: 400 });
+  }
+  // ... verify state matches the seller's session in your DB ...
+
+  const token = await exchangeCodeForToken({
+    clientId: CLIENT_ID,
+    clientSecret: CLIENT_SECRET,
+    code,
+    redirectUri: REDIRECT_URI,
+  });
+
+  // PERSIST the bundle. The user_id identifies which seller this is.
+  await oauthStore.set(token.user_id, {
+    user_id: token.user_id,
+    access_token: token.access_token,
+    refresh_token: token.refresh_token!,
+    expires_at: expirationTimeMs(Date.now(), token.expires_in),
+  });
+
+  return Response.json({ ok: true, sellerId: token.user_id });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3 — Per-transaction: get a per-seller MP client
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function getSellerMpClient(sellerUserId: string): Promise<MercadoPagoClient> {
+  let token = await oauthStore.get(sellerUserId);
+  if (!token) {
+    throw new Error(`Seller ${sellerUserId} hasn't connected MP yet.`);
+  }
+
+  // Proactive refresh: if within 5 min of expiration, refresh ahead of time.
+  if (isExpiringSoon(token.expires_at)) {
+    const fresh = await refreshAccessToken({
+      clientId: CLIENT_ID,
+      clientSecret: CLIENT_SECRET,
+      refreshToken: token.refresh_token,
+    });
+    token = {
+      user_id: fresh.user_id,
+      access_token: fresh.access_token,
+      refresh_token: fresh.refresh_token!,
+      expires_at: expirationTimeMs(Date.now(), fresh.expires_in),
+    };
+    await oauthStore.set(token.user_id, token);
+  }
+
+  return new MercadoPagoClient({ accessToken: token.access_token });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 4 — Create a marketplace preference with fee split
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function createMarketplacePreference(input: {
+  sellerUserId: string; // from oauth_exchange_code earlier
+  buyerEmail: string;
+  productTitle: string;
+  productPriceArs: number;
+  externalReference: string;
+}) {
+  // Compute the exact fee to charge (5% with $50 floor and $5000 ceiling)
+  const marketplaceFee = computeMarketplaceFee(input.productPriceArs, {
+    percent: 5,
+    minArs: 50,
+    maxArs: 5000,
+  });
+
+  const sellerClient = await getSellerMpClient(input.sellerUserId);
+
+  const preference = await sellerClient.createPreference({
+    items: [
+      {
+        title: input.productTitle,
+        quantity: 1,
+        unit_price: input.productPriceArs,
+        currency_id: "ARS",
+      },
+    ],
+    payer: { email: input.buyerEmail },
+    backUrls: {
+      success: "https://yourapp.com/payment-success",
+      failure: "https://yourapp.com/payment-failure",
+    },
+    autoReturn: "approved",
+    externalReference: input.externalReference,
+    notificationUrl: "https://yourapp.com/api/mp/webhook",
+
+    // The marketplace fields — these split the funds:
+    marketplace: MARKETPLACE_NAME,
+    marketplaceFee, // in ARS, NOT %
+    collectorId: input.sellerUserId, // funds route here; fee splits off to your platform
+  });
+
+  return {
+    preferenceId: preference.id,
+    initPoint: preference.init_point,
+    sellerReceives: input.productPriceArs - marketplaceFee,
+    platformFee: marketplaceFee,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 5 — Reconciliation: query merchant_orders to verify split
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function reconcileMarketplaceSale(input: {
+  sellerUserId: string;
+  preferenceId: string;
+}) {
+  const sellerClient = await getSellerMpClient(input.sellerUserId);
+  const result = await sellerClient.searchMerchantOrders({
+    preferenceId: input.preferenceId,
+  });
+  return result.elements;
+}

package/cookbook/05-qr-in-store.ts

@@ -0,0 +1,142 @@
+/**
+ * Recipe 05 — In-store QR payment with WhatsApp notification.
+ *
+ * # Use case
+ *
+ * Brick-and-mortar shop. Buyer scans a dynamic QR with any AR wallet (MP,
+ * Modo, BNA+, Cuenta DNI, Naranja X — interop is mandated by Transferencias 3.0).
+ *
+ * # Flow
+ *
+ * **One-time setup**:
+ * 1. `create_store` (per branch)
+ * 2. `create_pos` per cash register / agent
+ *
+ * **Per sale**:
+ * 1. Cashier triggers a QR for $X via the agent
+ * 2. `create_qr_payment` → returns base64 PNG + qr_data string
+ * 3. Display QR on screen (or print)
+ * 4. Buyer scans → MP fires `point_integration_wh` then `payment` webhooks
+ * 5. Cashier receives notification on WhatsApp ("✓ Cobro $X de Juan")
+ *
+ * # Why two webhooks (`point_integration_wh` + `payment`)
+ *
+ * - `point_integration_wh`: fires when the QR is scanned, BEFORE payment confirmation
+ * - `payment`: fires when the payment is approved
+ *
+ * Listen for both — the first is your "cashier knows it's being scanned"
+ * heads-up, the second is the source of truth for "money landed".
+ */
+
+import {
+  InMemoryStateAdapter,
+  MercadoPagoClient,
+} from "@ar-agents/mercadopago";
+import { WhatsAppClient, sendWhatsAppText } from "@ar-agents/whatsapp"; // hypothetical import path
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+const wa = new WhatsAppClient({
+  // ... WhatsApp Business credentials ...
+} as never);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1 — One-time setup: store + POS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function setupStoreAndPos(input: {
+  userId: string; // your MP user id (from get_account_info)
+  storeName: string;
+  storeExternalId: string; // your-system branch id
+  posExternalId: string; // your-system cash register id
+}) {
+  const store = await mp.createStore(input.userId, {
+    name: input.storeName,
+    external_id: input.storeExternalId,
+    location: { street_name: "—", street_number: 0, city: "Buenos Aires" },
+  } as never);
+
+  const pos = await mp.createPos({
+    name: `Caja ${input.posExternalId}`,
+    external_id: input.posExternalId,
+    store_id: store.id,
+    category: 621102, // "Other Food and Beverage Services" — adjust per MCC
+  } as never);
+
+  return { storeId: store.id, posId: pos.id, posExternalId: input.posExternalId };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2 — Cashier triggers a QR for $X
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function generateQrForSale(input: {
+  userId: string;
+  posExternalId: string; // unique per POS
+  amountArs: number;
+  description: string;
+  externalReference: string; // your-system order id
+  cashierWhatsAppNumber: string; // for notifications
+}) {
+  const qr = await mp.createQrPayment(input.userId, {
+    external_pos_id: input.posExternalId,
+    title: input.description,
+    description: input.description,
+    total_amount: input.amountArs,
+    items: [
+      {
+        sku_number: input.externalReference,
+        category: "marketplace",
+        title: input.description,
+        description: input.description,
+        unit_price: input.amountArs,
+        quantity: 1,
+        unit_measure: "unit",
+        total_amount: input.amountArs,
+      },
+    ],
+    expires_in_seconds: 600,
+    notification_url: "https://yourapp.com/api/mp/webhook",
+  } as never);
+
+  return {
+    qrDataUrl: qr.qr_data_url, // base64 PNG ready to display
+    qrString: qr.qr_data, // raw QR string (alt: emit your own image)
+    expiresInSeconds: 600,
+    instructions:
+      "Mostrale al cliente este QR. Tiene 10 minutos para escanear.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3 — Webhook: payment approved → notify cashier via WhatsApp
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function onPaymentApproved(input: {
+  paymentId: string;
+  cashierWhatsAppNumber: string;
+}) {
+  const payment = await mp.getPayment(input.paymentId);
+
+  if (payment.status !== "approved") return; // only notify on success
+
+  const buyerName = (payment.payer as { first_name?: string } | undefined)?.first_name ?? "cliente";
+  const amount = payment.transaction_amount;
+
+  await sendWhatsAppText({
+    waClient: wa,
+    to: input.cashierWhatsAppNumber,
+    text: `✓ Cobro confirmado\nMonto: $${amount.toLocaleString("es-AR")}\nCliente: ${buyerName}\nID: ${payment.id}`,
+  } as never);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 4 — Cancel a pending QR (buyer didn't scan)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function cancelStaleQr(userId: string, posExternalId: string) {
+  await mp.cancelQrPayment(userId, posExternalId);
+  return { ok: true };
+}

package/cookbook/06-3ds-challenge.ts

@@ -0,0 +1,139 @@
+/**
+ * Recipe 06 — 3DS challenge flow with detect → redirect → recover.
+ *
+ * # Background
+ *
+ * 3DS (Strong Customer Authentication) is the issuer-side 2FA layer for
+ * card payments. MP triggers it automatically when:
+ * - The card's issuer requires it (driven by MCC + amount + risk).
+ * - The buyer's country mandates it.
+ *
+ * In Argentina, 3DS is OPTIONAL but strongly recommended for high-value
+ * transactions. When triggered, the payment stays in `pending` until the
+ * buyer completes the issuer's challenge.
+ *
+ * # Flow
+ *
+ * 1. `create_payment` returns `status: "pending"` + `status_detail: "pending_challenge"`
+ * 2. Run `analyze_payment_3ds` (or call `analyze3DS(payment)` directly) to extract
+ *    the `challengeUrl` from `payment.three_ds_info.external_resource_url`
+ * 3. Redirect the buyer to `challengeUrl`
+ * 4. Buyer completes the challenge on the issuer's page
+ * 5. Issuer redirects buyer back to your `back_url`
+ * 6. MP fires a `payment` webhook with the final status (approved/rejected)
+ *
+ * # Critical
+ *
+ * Without redirecting to the challenge URL, the payment stays in `pending`
+ * INDEFINITELY. This is the most common cause of "stuck" payments.
+ */
+
+import { analyze3DS, MercadoPagoClient } from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1 — Create payment + immediately analyze 3DS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function createPaymentAndCheck3DS(input: {
+  amountArs: number;
+  cardToken: string;
+  payerEmail: string;
+  externalReference: string;
+}) {
+  const payment = await mp.createPayment({
+    transactionAmount: input.amountArs,
+    paymentMethodId: "visa", // get from list_payment_methods if uncertain
+    payerEmail: input.payerEmail,
+    token: input.cardToken,
+    description: "Compra " + input.externalReference,
+    externalReference: input.externalReference,
+    installments: 1,
+  });
+
+  const threeDs = analyze3DS(payment);
+
+  if (threeDs.status === "challenge_required" && threeDs.challengeUrl) {
+    return {
+      paymentId: payment.id,
+      status: "challenge_required" as const,
+      action: "redirect",
+      challengeUrl: threeDs.challengeUrl,
+      message:
+        "Redirigir al comprador a challengeUrl. El pago queda pending hasta que complete el desafío.",
+    };
+  }
+
+  if (threeDs.status === "rejected") {
+    return {
+      paymentId: payment.id,
+      status: "rejected" as const,
+      action: "show_error",
+      message: threeDs.description,
+    };
+  }
+
+  return {
+    paymentId: payment.id,
+    status: payment.status,
+    action: "done",
+    message:
+      threeDs.status === "frictionless"
+        ? "3DS aprobado sin desafiar al comprador."
+        : "Pago procesado.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2 — Render the redirect page (Next.js Server Component example)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Hypothetical Next.js page that handles the challenge URL redirect:
+ *
+ * ```tsx
+ * // app/checkout/3ds/[paymentId]/page.tsx
+ * export default async function ChallengePage({
+ *   params: { paymentId },
+ * }: { params: { paymentId: string } }) {
+ *   const payment = await mp.getPayment(paymentId);
+ *   const threeDs = analyze3DS(payment);
+ *
+ *   if (threeDs.status === "challenge_required" && threeDs.challengeUrl) {
+ *     redirect(threeDs.challengeUrl);
+ *   }
+ *
+ *   // If we land here, the challenge is over — show final status.
+ *   return <PaymentResultPage paymentId={paymentId} />;
+ * }
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3 — Webhook: payment.updated → check final 3DS state
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function on3DSPaymentWebhook(paymentId: string) {
+  const payment = await mp.getPayment(paymentId);
+  const threeDs = analyze3DS(payment);
+
+  // Possible end states:
+  // - approved + frictionless: 3DS was on, buyer wasn't challenged
+  // - approved (no 3DS info): 3DS not required, normal payment
+  // - rejected (status_detail with "3ds"): authentication failed
+  // - approved (after challenge): buyer completed the challenge successfully
+
+  if (payment.status === "approved") {
+    // Provision the order
+    return { ok: true, threeDs: threeDs.status };
+  }
+  if (payment.status === "rejected") {
+    // Show the user the failure reason; offer alternative payment method
+    return { ok: false, reason: threeDs.description };
+  }
+  // Still pending — webhook will fire again
+  return { ok: false, reason: "still pending" };
+}