@ar-agents/mercadopago 0.7.0 → 0.8.0

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" };
+}

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 };
+}