@ar-agents/mercadopago 0.7.0 → 0.9.0

package/cookbook/07-auth-only-order.ts

@@ -0,0 +1,127 @@
+/**
+ * Recipe 07 — Auth-only Order with manual capture (ride-share / hotel pattern).
+ *
+ * # Use case
+ *
+ * You want to ESTIMATE the final amount upfront (e.g., taxi ride: max
+ * possible cost) but only CAPTURE the actual amount once the service
+ * completes. This is the "preauthorization + capture" pattern used by:
+ *
+ * - Ride-share: authorize at trip start, capture exact amount at end
+ * - Hotels: authorize for full stay at check-in, capture nightly
+ * - Marketplaces with delivery: authorize at order, capture at delivery
+ *
+ * # Flow
+ *
+ * 1. Buyer pays via your app — but it's an Order with `capture_mode: "manual"`
+ * 2. The funds are HELD on the buyer's card (auth-only) — they see it as
+ *    a pending charge
+ * 3. When the service completes, you call `capture_order(order_id, amount)`
+ *    with the FINAL amount (≤ the originally authorized amount)
+ * 4. If you don't capture within 7 days, the auth expires automatically
+ *    (funds released to the buyer)
+ * 5. To cancel before capture: `cancel_order(order_id)` releases the auth
+ *
+ * # Why Order instead of Payment?
+ *
+ * - Order has explicit lifecycle (created → action_required → processed/canceled)
+ * - Order can aggregate multiple Payments (partial captures, retries)
+ * - Order is MP's modern API for new flows
+ *
+ * Use Preference (Checkout Pro) when you just need a hosted pay-link.
+ * Use Order when you need this auth-only or multi-payment-per-order semantics.
+ */
+
+import {
+  explainPaymentStatus,
+  MercadoPagoClient,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 1 — Create the auth-only Order at "service start"
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function authorizeRideStart(input: {
+  rideId: string;
+  buyerEmail: string;
+  estimatedMaxArs: number; // upper bound — what you can capture up to
+}) {
+  const order = await mp.createOrder({
+    type: "online",
+    currency_id: "ARS",
+    total_amount: input.estimatedMaxArs,
+    external_reference: input.rideId,
+    capture_mode: "manual", // <-- THE KEY FIELD
+    payer: { email: input.buyerEmail },
+    notification_url: "https://yourapp.com/api/mp/webhook",
+  });
+
+  return {
+    orderId: order.id,
+    status: order.status, // "action_required"
+    note: "Funds authorized but not captured. Capture within 7 days or auth expires.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 2 — Capture the exact final amount when service completes
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function captureRideOnComplete(input: {
+  orderId: string;
+  finalAmountArs: number; // must be ≤ originally authorized amount
+}) {
+  const captured = await mp.captureOrder(input.orderId, input.finalAmountArs);
+
+  if (captured.status !== "processed") {
+    // Capture didn't succeed — surface the reason
+    throw new Error(
+      `Capture failed: status=${captured.status}, status_detail=${captured.status_detail}`,
+    );
+  }
+
+  return {
+    orderId: captured.id,
+    capturedAmount: input.finalAmountArs,
+    status: "captured",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 3 — Cancel before capture (e.g., buyer cancels the trip)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function cancelRide(input: { orderId: string }) {
+  const canceled = await mp.cancelOrder(input.orderId);
+  return {
+    orderId: canceled.id,
+    status: canceled.status, // "canceled"
+    note: "Auth released. Buyer's card is no longer hold.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Step 4 — Recovery: handle a stuck Order (rare but real)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function checkOrderHealth(orderId: string) {
+  const order = await mp.getOrder(orderId);
+
+  // If the underlying payment was rejected, surface why
+  const transactions = (order as { transactions?: { payments?: Array<{ id: string }> } }).transactions;
+  if (transactions?.payments && transactions.payments.length > 0) {
+    const lastPayment = await mp.getPayment(String(transactions.payments[0]!.id));
+    const explanation = explainPaymentStatus(lastPayment);
+    return {
+      orderStatus: order.status,
+      paymentStatus: lastPayment.status,
+      explanation,
+    };
+  }
+
+  return { orderStatus: order.status };
+}

package/cookbook/08-recovery-patterns.ts

@@ -0,0 +1,191 @@
+/**
+ * Recipe 08 — Recovery patterns: retry, recover stuck payments, handle expirations.
+ *
+ * # Common stuck states and how to recover
+ *
+ * 1. **Subscription card expired → recurring charge rejected**
+ *    Recover by: capture fresh card token from buyer + `update_subscription({ card_token_id })`
+ *
+ * 2. **Payment stuck in `pending_challenge` (3DS not completed)**
+ *    Recover by: redirect buyer back to the challenge URL via
+ *    `analyze_payment_3ds(payment_id).challengeUrl`
+ *
+ * 3. **Payment in `pending_review_manual` (MP fraud team review)**
+ *    Recover by: WAIT — MP processes within 24-72h. Don't retry.
+ *
+ * 4. **Subscription auto-cancelled because first payment failed**
+ *    Recover by: create a fresh subscription (the original is dead, MP doesn't
+ *    let you "reactivate" — that's documented in `MercadoPagoPaymentRejectedError`).
+ *
+ * 5. **`pending_waiting_payment` for cash methods (Rapipago, Pago Fácil)**
+ *    Recover by: NOTHING — the buyer must complete payment within the
+ *    timeout (typically 3-5 days). Polling or push-webhooks notify when done.
+ *
+ * 6. **Webhook arrived but payment not in your DB**
+ *    Recover by: idempotent upsert via `searchPayments({ external_reference })`
+ *    instead of trusting the webhook payload alone.
+ */
+
+import {
+  classifyError,
+  explainPaymentStatus,
+  MercadoPagoClient,
+  MercadoPagoPaymentRejectedError,
+  type PaymentStatusExplanation,
+} from "@ar-agents/mercadopago";
+
+const mp = new MercadoPagoClient({
+  accessToken: process.env.MP_ACCESS_TOKEN!,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 1 — Subscription card swap on rejection
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function recoverFromCardRejection(input: {
+  subscriptionId: string;
+  buyerWhatsAppNumber: string;
+}) {
+  const sub = await mp.getPreapproval(input.subscriptionId);
+  if (sub.status !== "paused" && sub.status !== "cancelled") {
+    return { ok: true, action: "none" };
+  }
+
+  // Send buyer a link to update their card via MP frontend SDK
+  const updateUrl = `https://yourapp.com/billing/update-card?sub=${input.subscriptionId}`;
+  // ... send via WhatsApp with the toolkit's whatsappTools ...
+
+  return {
+    ok: false,
+    action: "card_swap_required",
+    sentTo: input.buyerWhatsAppNumber,
+    updateUrl,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 2 — Recover stuck-pending payment with status explanation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function inspectStuckPayment(paymentId: string): Promise<{
+  paymentId: string;
+  status: string;
+  explanation: PaymentStatusExplanation;
+  nextAction: string;
+}> {
+  const payment = await mp.getPayment(paymentId);
+  const explanation = explainPaymentStatus(payment);
+
+  let nextAction = explanation.recommendedAction;
+  if (explanation.retryable) {
+    nextAction = `Reintentar con otra tarjeta. Razón: ${explanation.summary}`;
+  } else if (!explanation.final) {
+    nextAction = `Esperar webhook (${explanation.summary}). Sin acción de tu parte.`;
+  } else if (explanation.paid) {
+    nextAction = `Acreditado. Continuar con flujo posterior.`;
+  }
+
+  return {
+    paymentId,
+    status: payment.status as string,
+    explanation,
+    nextAction,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 3 — Idempotent upsert via search (don't trust webhook payload alone)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function reconcilePaymentByExternalRef(externalReference: string) {
+  // Search MP for ALL payments under this external_reference. There may be
+  // multiple if the buyer retried.
+  const result = await mp.searchPayments({ external_reference: externalReference });
+
+  // Find the latest approved one (winning attempt)
+  const approved = result.results
+    ?.filter((p) => p.status === "approved")
+    .sort((a, b) => (b.date_created ?? "").localeCompare(a.date_created ?? ""))[0];
+
+  if (approved) {
+    return { found: true, paymentId: approved.id, amount: approved.transaction_amount };
+  }
+
+  // No approved payment — find the latest attempt (could be pending or rejected)
+  const latest = result.results
+    ?.sort((a, b) => (b.date_created ?? "").localeCompare(a.date_created ?? ""))[0];
+
+  return { found: false, lastAttempt: latest };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 4 — Handle MercadoPagoPaymentRejectedError explicitly
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function chargeWithRetry(input: {
+  cardId: string;
+  customerId: string;
+  amountArs: number;
+  cvv: string;
+  externalReference: string;
+}): Promise<
+  { ok: true; paymentId: string } | { ok: false; reason: string; recoverable: boolean }
+> {
+  try {
+    const payment = await mp.chargeSavedCard({
+      cardId: input.cardId,
+      customerId: input.customerId,
+      transactionAmount: input.amountArs,
+      securityCode: input.cvv,
+      payerEmail: "—", // populated server-side from customer
+      description: "Recurring charge",
+      externalReference: input.externalReference,
+    });
+    return { ok: true, paymentId: payment.id };
+  } catch (err) {
+    if (err instanceof MercadoPagoPaymentRejectedError) {
+      // The lib's MercadoPagoPaymentRejectedError carries status_detail —
+      // use it to drive recovery.
+      const detail = (err as MercadoPagoPaymentRejectedError & { statusDetail?: string }).statusDetail;
+      const recoverable =
+        detail === "cc_rejected_call_for_authorize" ||
+        detail === "cc_rejected_insufficient_amount" ||
+        detail === "cc_rejected_bad_filled_security_code";
+      return { ok: false, reason: detail ?? "rejected", recoverable };
+    }
+    const classified = classifyError(err);
+    throw classified; // Re-throw for ops/observability
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pattern 5 — Cron-driven monitoring (Vercel Cron Job)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Hypothetical Vercel Cron Job (`vercel.json`):
+ * ```json
+ * { "crons": [{ "path": "/api/cron/mp-monitor", "schedule": "0 *\/4 * * *" }] }
+ * ```
+ *
+ * Runs every 4 hours; surfaces:
+ * - Subscriptions that haven't auto-charged in >35 days (probably broken)
+ * - Stuck-pending payments older than 24h (need investigation)
+ * - Disputes opened in the last 24h (need response)
+ */
+export async function cronMonitorMpHealth() {
+  const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString();
+  const stuck = await mp.searchPayments({
+    status: "pending",
+    range: "date_created",
+    begin_date: since.slice(0, 10),
+  } as never);
+
+  // Surface to ops via Slack/email/Sentry
+  const stuckCount = stuck.results?.length ?? 0;
+  if (stuckCount > 5) {
+    // alertOps(...)
+  }
+
+  return { stuckCount };
+}

package/cookbook/README.md

@@ -0,0 +1,36 @@
+# Cookbook — `@ar-agents/mercadopago`
+
+Real, copy-pasteable recipes for the most common MP integration flows. Every
+recipe is a self-contained Next.js route handler or agent loop you can
+deploy on Vercel as-is.
+
+## Recipes
+
+| #   | File                              | Pattern                                                                 |
+| --- | --------------------------------- | ----------------------------------------------------------------------- |
+| 01  | `01-checkout-pro-basic.ts`        | First-time hosted-checkout sale (Checkout Pro preference + back URLs)   |
+| 02  | `02-saas-subscription.ts`         | Reusable plan + subscription with first-payment + card swap on failure  |
+| 03  | `03-webhook-handler.ts`           | Vercel route handler with HMAC verify + auto-fetch + dispatch by topic  |
+| 04  | `04-marketplace-split.ts`         | OAuth seller link → preference with `marketplace_fee` → reconciliation  |
+| 05  | `05-qr-in-store.ts`               | Create POS → generate QR → poll status → notify buyer via WhatsApp      |
+| 06  | `06-3ds-challenge.ts`             | Detect challenge → redirect buyer → recover via webhook                 |
+| 07  | `07-auth-only-order.ts`           | `Order` with manual capture → capture later when service completes      |
+| 08  | `08-recovery-patterns.ts`         | Retry expired subscriptions, recover stuck-pending payments, etc.       |
+
+## Conventions
+
+- All recipes assume `MP_ACCESS_TOKEN` is set (TEST- prefix in sandbox).
+- All recipes show the agent path AND the manual-client path side by side
+  where relevant.
+- Recipes that need state use `VercelKVSubscriptionStateAdapter` —
+  swap for `InMemoryStateAdapter` in tests.
+- Recipes that need OAuth credentials assume `MP_CLIENT_ID` + `MP_CLIENT_SECRET`.
+- Recipes that need webhook secrets assume `MP_WEBHOOK_SECRET`.
+- All `Edge Runtime` compatible (Web Crypto only — no `node:crypto`).
+
+## Deploying as Vercel functions
+
+Each recipe is a standalone TypeScript file you can drop into
+`apps/your-app/src/app/api/mp/{route}.ts` (App Router) or
+`apps/your-app/pages/api/mp/{route}.ts` (Pages Router). Add `export const runtime = "edge"` if
+you want Edge Runtime; the toolkit is fully Edge-compatible.