@ar-agents/mercadopago 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
+var crypto = require('crypto');
 var ai = require('ai');
 var zod = require('zod');
-var crypto = require('crypto');
 
 // src/errors.ts
 var MercadoPagoError = class extends Error {
@@ -100,12 +100,38 @@ var MercadoPagoRateLimitError = class extends MercadoPagoError {
   }
   retryAfterSeconds;
 };
+var MercadoPagoOverloadedError = class extends MercadoPagoError {
+  constructor(endpoint, status) {
+    super(
+      `Mercado Pago appears overloaded \u2014 returned a non-JSON ${status} response for ${endpoint}. Wait a few seconds and retry.`,
+      status,
+      endpoint
+    );
+    this.name = "MercadoPagoOverloadedError";
+  }
+};
+var MercadoPagoTimeoutError = class extends MercadoPagoError {
+  constructor(endpoint, timeoutMs) {
+    super(
+      `Mercado Pago request timed out after ${timeoutMs}ms on ${endpoint}. Increase requestTimeoutMs or check connectivity.`,
+      0,
+      endpoint
+    );
+    this.timeoutMs = timeoutMs;
+    this.name = "MercadoPagoTimeoutError";
+  }
+  timeoutMs;
+};
 function classifyError(status, endpoint, body, context) {
   const bodyText = typeof body === "string" ? body : body && typeof body === "object" ? JSON.stringify(body) : "";
   const lower = bodyText.toLowerCase();
   if (status === 401) return new MercadoPagoAuthError(endpoint, body);
   if (status === 429) {
-    return new MercadoPagoRateLimitError(endpoint, null, body);
+    let retryAfter = null;
+    const obj = body;
+    if (obj?.retry_after) retryAfter = Number(obj.retry_after);
+    else if (obj?.["retry-after"]) retryAfter = Number(obj["retry-after"]);
+    return new MercadoPagoRateLimitError(endpoint, retryAfter, body);
   }
   if (status === 400) {
     if (lower.includes("back_url") && lower.includes("not a valid url")) {
@@ -131,10 +157,16 @@ function classifyError(status, endpoint, body, context) {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.mercadopago.com";
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var MercadoPagoClient = class {
   accessToken;
   baseUrl;
   fetchImpl;
+  requestTimeoutMs;
+  maxRetries;
+  onCall;
   constructor(options) {
     if (!options.accessToken) {
       throw new Error(
@@ -144,32 +176,123 @@ var MercadoPagoClient = class {
     this.accessToken = options.accessToken;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.fetchImpl = options.fetch;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+    this.maxRetries = Math.max(0, options.maxRetries ?? 1);
+    this.onCall = options.onCall;
   }
-  async request(method, path, body, classifyContext) {
-    const init = {
-      method,
-      headers: {
-        Authorization: `Bearer ${this.accessToken}`,
-        "Content-Type": "application/json"
-      }
+  async request(method, path, body, options) {
+    const headers = {
+      Authorization: `Bearer ${this.accessToken}`,
+      "Content-Type": "application/json"
     };
-    if (body !== void 0) {
-      init.body = JSON.stringify(body);
+    if (options?.idempotencyKey) {
+      headers["X-Idempotency-Key"] = options.idempotencyKey;
+    }
+    let url = `${this.baseUrl}${path}`;
+    if (options?.query) {
+      const search = new URLSearchParams();
+      for (const [k, v] of Object.entries(options.query)) {
+        if (v !== void 0 && v !== null && v !== "") {
+          search.set(k, String(v));
+        }
+      }
+      const qs = search.toString();
+      if (qs) url += `?${qs}`;
     }
     const fetchFn = this.fetchImpl ?? globalThis.fetch;
-    const res = await fetchFn(`${this.baseUrl}${path}`, init);
-    if (!res.ok) {
-      let parsed;
-      const text = await res.text();
+    const t0 = Date.now();
+    let attempt = 0;
+    let lastError;
+    let lastStatus = null;
+    while (attempt <= this.maxRetries) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+      const init = { method, headers, signal: controller.signal };
+      if (body !== void 0) init.body = JSON.stringify(body);
       try {
-        parsed = JSON.parse(text);
-      } catch {
-        parsed = text;
+        const res = await fetchFn(url, init);
+        clearTimeout(timer);
+        lastStatus = res.status;
+        if (res.ok) {
+          const text2 = await res.text();
+          this.onCall?.({
+            method,
+            path,
+            durationMs: Date.now() - t0,
+            httpStatus: res.status,
+            retried: attempt,
+            success: true
+          });
+          if (!text2) return void 0;
+          return JSON.parse(text2);
+        }
+        const isRetryable = res.status >= 500 || res.status === 429;
+        if (isRetryable && attempt < this.maxRetries) {
+          const retryAfter = res.headers.get("retry-after");
+          const waitMs = retryAfter ? Number(retryAfter) * 1e3 : 250 * Math.pow(2, attempt);
+          attempt++;
+          await sleep(waitMs);
+          continue;
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        if (res.status >= 500 && !contentType.includes("application/json")) {
+          this.onCall?.({
+            method,
+            path,
+            durationMs: Date.now() - t0,
+            httpStatus: res.status,
+            retried: attempt,
+            success: false
+          });
+          throw new MercadoPagoOverloadedError(path, res.status);
+        }
+        let parsed;
+        const text = await res.text();
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+        const err = classifyError(res.status, path, parsed, options?.classifyContext);
+        this.onCall?.({
+          method,
+          path,
+          durationMs: Date.now() - t0,
+          httpStatus: res.status,
+          retried: attempt,
+          success: false
+        });
+        throw err;
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof MercadoPagoError) throw err;
+        const isAbort = err instanceof Error && err.name === "AbortError";
+        const isNetwork = !lastStatus && !isAbort;
+        if ((isNetwork || isAbort) && attempt < this.maxRetries) {
+          lastError = err;
+          attempt++;
+          await sleep(250 * Math.pow(2, attempt - 1));
+          continue;
+        }
+        this.onCall?.({
+          method,
+          path,
+          durationMs: Date.now() - t0,
+          httpStatus: lastStatus,
+          retried: attempt,
+          success: false
+        });
+        if (isAbort) {
+          throw new MercadoPagoTimeoutError(path, this.requestTimeoutMs);
+        }
+        throw err;
       }
-      throw classifyError(res.status, path, parsed, classifyContext);
     }
-    return await res.json();
+    throw lastError ?? new Error(`MercadoPago request failed after ${this.maxRetries} retries`);
   }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Subscriptions (Preapprovals) — v0.1 surface, kept stable
+  // ───────────────────────────────────────────────────────────────────────────
   /**
    * Create a recurring subscription (preapproval). The returned `init_point`
    * URL is where the buyer must complete the FIRST payment with their card +
@@ -191,70 +314,452 @@ var MercadoPagoClient = class {
           currency_id: params.currency
         }
       },
-      { payerEmail: params.payerEmail }
+      { classifyContext: { payerEmail: params.payerEmail } }
     );
   }
+  async getPreapproval(id) {
+    return this.request("GET", `/preapproval/${id}`, void 0, {
+      classifyContext: { preapprovalId: id }
+    });
+  }
+  async cancelPreapproval(id) {
+    return this.request(
+      "PUT",
+      `/preapproval/${id}`,
+      { status: "cancelled" },
+      { classifyContext: { preapprovalId: id } }
+    );
+  }
+  async pausePreapproval(id) {
+    return this.request(
+      "PUT",
+      `/preapproval/${id}`,
+      { status: "paused" },
+      { classifyContext: { preapprovalId: id } }
+    );
+  }
+  async resumePreapproval(id) {
+    return this.request(
+      "PUT",
+      `/preapproval/${id}`,
+      { status: "authorized" },
+      { classifyContext: { preapprovalId: id } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Payments (v0.2)
+  // ───────────────────────────────────────────────────────────────────────────
   /**
-   * Fetch the current state of a preapproval. Useful to confirm whether the
-   * buyer has completed the first payment (`status: 'authorized'`) or whether
-   * the subscription was cancelled.
+   * Create a payment. Two main flows:
+   * - **Card payment**: pass `token` (from MP frontend Cardform) + payment_method_id.
+   * - **Account money / cash**: omit token, pass payment_method_id like "account_money", "rapipago", "pagofacil".
+   *
+   * For credit card payments where you don't have a card token (i.e., you only
+   * have a payer email and want to send them a payment link), use
+   * `createPreference` (Checkout Pro) instead.
+   *
+   * Idempotency: pass `idempotencyKey` to safely retry. Required for production
+   * to dedupe network-failed requests.
    */
-  async getPreapproval(id) {
+  async createPayment(params) {
+    const body = {
+      transaction_amount: params.transactionAmount,
+      payment_method_id: params.paymentMethodId,
+      payer: {
+        email: params.payerEmail,
+        ...params.identification ? { identification: params.identification } : {}
+      }
+    };
+    if (params.installments !== void 0) body.installments = params.installments;
+    if (params.token !== void 0) body.token = params.token;
+    if (params.description !== void 0) body.description = params.description;
+    if (params.externalReference !== void 0) body.external_reference = params.externalReference;
+    if (params.notificationUrl !== void 0) body.notification_url = params.notificationUrl;
+    if (params.statementDescriptor !== void 0)
+      body.statement_descriptor = params.statementDescriptor;
+    if (params.capture !== void 0) body.capture = params.capture;
+    if (params.additionalInfo !== void 0) body.additional_info = params.additionalInfo;
+    return this.request("POST", "/v1/payments", body, {
+      ...params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : {},
+      classifyContext: { payerEmail: params.payerEmail }
+    });
+  }
+  /** Fetch a payment by ID. */
+  async getPayment(id) {
+    return this.request("GET", `/v1/payments/${id}`, void 0, {
+      classifyContext: { paymentId: id }
+    });
+  }
+  /**
+   * Search payments with filters. Common: by external_reference (your-system
+   * id), by status, by date range. Pagination via offset + limit (max 100).
+   */
+  async searchPayments(params = {}) {
+    const query = {
+      limit: params.limit ?? 30,
+      offset: params.offset ?? 0
+    };
+    if (params.externalReference) query["external_reference"] = params.externalReference;
+    if (params.status) query["status"] = params.status;
+    if (params.payerEmail) query["payer.email"] = params.payerEmail;
+    if (params.beginDate) query["begin_date"] = params.beginDate;
+    if (params.endDate) query["end_date"] = params.endDate;
+    if (params.sort) query["sort"] = params.sort;
+    if (params.criteria) query["criteria"] = params.criteria;
     return this.request(
       "GET",
-      `/preapproval/${id}`,
+      "/v1/payments/search",
       void 0,
-      { preapprovalId: id }
+      { query }
     );
   }
   /**
-   * Cancel an active preapproval. Irreversible: MP will not charge the buyer
-   * again and the subscription cannot be reactivated.
+   * Capture a previously authorized payment. Only works for credit-card
+   * payments created with `capture: false`. Optional partial capture amount.
    */
-  async cancelPreapproval(id) {
+  async capturePayment(id, amount) {
     return this.request(
       "PUT",
-      `/preapproval/${id}`,
-      { status: "cancelled" },
-      { preapprovalId: id }
+      `/v1/payments/${id}`,
+      amount !== void 0 ? { capture: true, transaction_amount: amount } : { capture: true },
+      { classifyContext: { paymentId: id } }
     );
   }
   /**
-   * Pause an authorized preapproval. The subscription stops auto-charging but
-   * can be re-activated. Note: MP only allows pausing subs that are currently
-   * `authorized` — pending/cancelled subs reject this.
+   * Cancel a pending or in_process payment. Once approved, you must use
+   * `createRefund` instead.
    */
-  async pausePreapproval(id) {
+  async cancelPayment(id) {
     return this.request(
       "PUT",
-      `/preapproval/${id}`,
-      { status: "paused" },
-      { preapprovalId: id }
+      `/v1/payments/${id}`,
+      { status: "cancelled" },
+      { classifyContext: { paymentId: id } }
     );
   }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Refunds
+  // ───────────────────────────────────────────────────────────────────────────
   /**
-   * Re-activate a paused preapproval. Charges resume on the next scheduled
-   * date.
+   * Refund a payment fully (omit `amount`) or partially. Idempotency key
+   * recommended — refunds can fail mid-flight and you don't want double-refunds
+   * on retry.
    */
-  async resumePreapproval(id) {
+  async createRefund(params) {
+    const body = params.amount !== void 0 ? { amount: params.amount } : void 0;
+    return this.request(
+      "POST",
+      `/v1/payments/${params.paymentId}/refunds`,
+      body,
+      {
+        ...params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : {},
+        classifyContext: { paymentId: params.paymentId }
+      }
+    );
+  }
+  async listRefunds(paymentId) {
+    const res = await this.request(
+      "GET",
+      `/v1/payments/${paymentId}/refunds`,
+      void 0,
+      { classifyContext: { paymentId } }
+    );
+    return Array.isArray(res) ? res : res.refunds ?? [];
+  }
+  async getRefund(paymentId, refundId) {
+    return this.request(
+      "GET",
+      `/v1/payments/${paymentId}/refunds/${refundId}`,
+      void 0,
+      { classifyContext: { paymentId } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Checkout Pro (Preferences)
+  // ───────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a payment preference for Checkout Pro. Returns `init_point` URL
+   * where the buyer completes payment on MP-hosted form. This is the
+   * recommended flow when you don't have a card token (most common path for
+   * agents — you don't want to handle PCI data).
+   *
+   * Sandbox: use `sandbox_init_point` instead of `init_point`.
+   */
+  async createPreference(params) {
+    const body = {
+      items: params.items.map((it) => ({
+        title: it.title,
+        quantity: it.quantity,
+        unit_price: it.unit_price,
+        currency_id: it.currency_id ?? "ARS",
+        ...it.description ? { description: it.description } : {},
+        ...it.picture_url ? { picture_url: it.picture_url } : {}
+      }))
+    };
+    if (params.payer) body.payer = params.payer;
+    if (params.backUrls) body.back_urls = params.backUrls;
+    if (params.autoReturn) body.auto_return = params.autoReturn;
+    if (params.notificationUrl) body.notification_url = params.notificationUrl;
+    if (params.externalReference) body.external_reference = params.externalReference;
+    if (params.paymentMethods) body.payment_methods = params.paymentMethods;
+    if (params.statementDescriptor)
+      body.statement_descriptor = params.statementDescriptor;
+    if (params.expires !== void 0) body.expires = params.expires;
+    if (params.expirationDateFrom) body.expiration_date_from = params.expirationDateFrom;
+    if (params.expirationDateTo) body.expiration_date_to = params.expirationDateTo;
+    return this.request("POST", "/checkout/preferences", body);
+  }
+  async getPreference(id) {
+    return this.request("GET", `/checkout/preferences/${id}`);
+  }
+  async updatePreference(id, patch) {
+    return this.request("PUT", `/checkout/preferences/${id}`, patch);
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Customers + Saved Cards
+  // ───────────────────────────────────────────────────────────────────────────
+  async createCustomer(params) {
+    const body = { email: params.email };
+    if (params.firstName) body.first_name = params.firstName;
+    if (params.lastName) body.last_name = params.lastName;
+    if (params.phone) body.phone = { area_code: params.phone.areaCode, number: params.phone.number };
+    if (params.identification) body.identification = params.identification;
+    if (params.description) body.description = params.description;
+    return this.request("POST", "/v1/customers", body, {
+      classifyContext: { payerEmail: params.email }
+    });
+  }
+  async getCustomer(id) {
+    return this.request("GET", `/v1/customers/${id}`, void 0, {
+      classifyContext: { customerId: id }
+    });
+  }
+  /**
+   * Search customers. Most common: by email (returns 0 or 1 result).
+   * Note: MP's `/v1/customers/search` returns a paginated wrapper, not a flat array.
+   */
+  async searchCustomers(params = {}) {
+    const query = {
+      limit: params.limit ?? 10,
+      offset: params.offset ?? 0
+    };
+    if (params.email) query["email"] = params.email;
+    return this.request("GET", "/v1/customers/search", void 0, { query });
+  }
+  async listCustomerCards(customerId) {
+    return this.request(
+      "GET",
+      `/v1/customers/${customerId}/cards`,
+      void 0,
+      { classifyContext: { customerId } }
+    );
+  }
+  async getCustomerCard(customerId, cardId) {
+    return this.request(
+      "GET",
+      `/v1/customers/${customerId}/cards/${cardId}`,
+      void 0,
+      { classifyContext: { customerId } }
+    );
+  }
+  async deleteCustomerCard(customerId, cardId) {
+    await this.request(
+      "DELETE",
+      `/v1/customers/${customerId}/cards/${cardId}`,
+      void 0,
+      { classifyContext: { customerId } }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Payment Methods + Installments
+  // ───────────────────────────────────────────────────────────────────────────
+  /** List all payment methods enabled for the account's site (MLA = Argentina). */
+  async listPaymentMethods() {
+    return this.request("GET", "/v1/payment_methods");
+  }
+  /**
+   * Get installment options for an amount. THE killer AR feature — returns
+   * `payer_costs` with `recommended_message` strings like "12 cuotas sin
+   * interés de $X" that you should surface verbatim to the user.
+   *
+   * Pass `bin` (first 6 digits of card) for issuer-specific offers (e.g.,
+   * Naranja's interest-free promotions). Without bin, returns generic offers.
+   */
+  async getInstallments(params) {
+    const query = {
+      amount: params.amount
+    };
+    if (params.paymentMethodId) query["payment_method_id"] = params.paymentMethodId;
+    if (params.bin) query["bin"] = params.bin;
+    if (params.issuerId) query["issuer.id"] = params.issuerId;
+    return this.request(
+      "GET",
+      "/v1/payment_methods/installments",
+      void 0,
+      { query }
+    );
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Account
+  // ───────────────────────────────────────────────────────────────────────────
+  /** Get info about the account that owns this access token. */
+  async getMe() {
+    return this.request("GET", "/users/me");
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // Card tokens (server-side, for saved-card retokenization)
+  // ───────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a single-use card token from a saved card. This is the server-side
+   * retokenization path (PCI-safe because the card data lives in MP's vault,
+   * we only pass the saved card_id + customer_id + the user-supplied CVV).
+   *
+   * Tokens expire in 7 days but typically burn on first use. AR currently
+   * REQUIRES CVV on every charge (MP doesn't store it); skipping CVV requires
+   * a private MP product enablement, not a public API.
+   */
+  async createCardToken(params) {
+    return this.request("POST", "/v1/card_tokens", {
+      card_id: params.cardId,
+      customer_id: params.customerId,
+      security_code: params.securityCode
+    });
+  }
+  /**
+   * High-level helper: charge a saved card in 3 steps.
+   * 1. Mint a card token from {customer_id, card_id, security_code}
+   * 2. Lookup card to fill payment_method_id (avoids agent guessing)
+   * 3. Create the payment with the token + idempotency key
+   *
+   * Returns the resulting Payment. Uses deterministic idempotency from
+   * (card_id, amount, externalReference) so retries dedupe on MP's side.
+   */
+  async chargeSavedCard(params) {
+    const token = await this.createCardToken({
+      cardId: params.cardId,
+      customerId: params.customerId,
+      securityCode: params.securityCode
+    });
+    const card = await this.getCustomerCard(params.customerId, params.cardId);
+    const paymentMethodId = card.payment_method?.id;
+    if (!paymentMethodId) {
+      throw new MercadoPagoError(
+        `Saved card ${params.cardId} has no payment_method.id. Cannot charge.`,
+        0,
+        `/v1/customers/${params.customerId}/cards/${params.cardId}`
+      );
+    }
+    const body = {
+      transaction_amount: params.amount,
+      token: token.id,
+      payment_method_id: paymentMethodId,
+      installments: params.installments ?? 1,
+      description: params.description,
+      payer: { type: "customer", id: params.customerId }
+    };
+    if (params.externalReference) body.external_reference = params.externalReference;
+    if (params.statementDescriptor) body.statement_descriptor = params.statementDescriptor;
+    return this.request("POST", "/v1/payments", body, {
+      ...params.idempotencyKey !== void 0 ? { idempotencyKey: params.idempotencyKey } : {},
+      classifyContext: { customerId: params.customerId }
+    });
+  }
+  // ───────────────────────────────────────────────────────────────────────────
+  // QR (in-store dynamic) — Section 2 of v0.3 spec
+  // ───────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a dynamic in-store QR order. Returns `qr_data` (EMVCo TLV string)
+   * + `in_store_order_id`. The buyer scans the QR with any AR wallet (Modo,
+   * BNA+, Cuenta DNI, Naranja X, etc. — interop is mandated by Transferencias
+   * 3.0). On payment, MP fires `point_integration_wh` then `payment` topics.
+   *
+   * Requires a pre-configured POS (`external_pos_id` from MP dashboard or
+   * `POST /pos`). The seller's `user_id` is auto-fetched from `/users/me`.
+   *
+   * The lib does NOT render the QR image — pass `qr_data` to a QR renderer
+   * (e.g., `qrcode` package) to get a data URL. The agent tool layer wraps
+   * this and returns both raw + data URL.
+   */
+  async createQrPayment(userId, params) {
+    const body = {
+      total_amount: params.totalAmount,
+      title: params.title
+    };
+    if (params.description) body.description = params.description;
+    if (params.notificationUrl) body.notification_url = params.notificationUrl;
+    if (params.externalReference) body.external_reference = params.externalReference;
+    if (params.expirationDate) body.expiration_date = params.expirationDate;
+    body.items = params.items ?? [
+      {
+        title: params.title,
+        quantity: 1,
+        unit_price: params.totalAmount,
+        unit_measure: "unit",
+        total_amount: params.totalAmount
+      }
+    ];
     return this.request(
       "PUT",
-      `/preapproval/${id}`,
-      { status: "authorized" },
-      { preapprovalId: id }
+      `/instore/orders/qr/seller/collectors/${encodeURIComponent(userId)}/pos/${encodeURIComponent(params.externalPosId)}/qrs`,
+      body
+    );
+  }
+  /**
+   * Cancel a pending QR order on a POS. Necessary if the buyer never scans
+   * — otherwise the next `createQrPayment` on the same POS returns 409.
+   */
+  async cancelQrPayment(userId, externalPosId) {
+    await this.request(
+      "DELETE",
+      `/instore/orders/qr/seller/collectors/${encodeURIComponent(userId)}/pos/${encodeURIComponent(externalPosId)}/qrs`
     );
   }
 };
+function deterministicIdempotencyKey(...parts) {
+  const payload = parts.filter((p) => p !== void 0 && p !== null).map(String).join("|");
+  return crypto.createHash("sha256").update(payload).digest("hex").slice(0, 32);
+}
 var DEFAULT_DESCRIPTIONS = {
+  // ── Subscriptions ────────────────────────────────────────────────────────
   create_subscription: "Create a Mercado Pago recurring subscription. Returns an init_point URL where the customer must complete the FIRST payment with their card and CVV (this is a hard MP requirement; agents cannot bypass it). After they pay, MP will auto-charge at the configured frequency without further intervention.",
   get_subscription_status: "Check the current status of a Mercado Pago subscription. Use this to confirm the customer completed the first payment (status becomes 'authorized') or to inspect the next charge date.",
   cancel_subscription: "Cancel an active Mercado Pago subscription. After cancellation, MP will not charge the customer again. This action is irreversible \u2014 confirm with the user before calling.",
   pause_subscription: "Pause an authorized Mercado Pago subscription. Charges stop until resumed. Only works on subscriptions in 'authorized' status.",
-  resume_subscription: "Resume a paused Mercado Pago subscription. Charges resume on the next scheduled date. Only works on subscriptions in 'paused' status."
+  resume_subscription: "Resume a paused Mercado Pago subscription. Charges resume on the next scheduled date. Only works on subscriptions in 'paused' status.",
+  // ── Payments ─────────────────────────────────────────────────────────────
+  create_payment: "Create a one-time payment. Two flows: (a) with a card token from MP frontend Cardform \u2014 for transparent checkout; (b) without token, for non-card methods like 'account_money', 'rapipago', 'pagofacil'. For most agent flows where you only have a payer email and want to send them a payment link, use create_payment_preference instead (Checkout Pro hosted form). Returns the Payment object with status \u2014 typically 'approved' for account_money and 'pending' for tickets.",
+  get_payment: "Fetch a single payment by ID. Use to confirm status after webhook arrives, or to inspect details (status_detail explains rejections).",
+  search_payments: "Search payments with filters. Most common: by external_reference (your-system identifier) to find all payments for an order, or by status='approved' to list successful charges in a date range. Returns paginated results.",
+  cancel_payment: "Cancel a pending or in_process payment (only works before approval). Once approved, use refund_payment instead. Common use: cancel an unpaid ticket payment that's still pending.",
+  capture_payment: "Capture an authorized credit-card payment that was created with capture=false. Use for hold-then-capture flows (e.g., authorize on order, capture on shipment). Optional partial amount.",
+  // ── Refunds ──────────────────────────────────────────────────────────────
+  refund_payment: "Refund an approved payment. Pass amount for partial refund; omit for full refund. Idempotency key is auto-generated based on paymentId+amount to prevent double-refunds on retries.",
+  list_refunds: "List all refunds for a given payment. Returns array of Refund objects. Useful to confirm a refund was processed or to inspect partial-refund history.",
+  // ── Checkout Pro ─────────────────────────────────────────────────────────
+  create_payment_preference: "Create a Mercado Pago Checkout Pro preference and get back a payment URL (init_point) to send to the customer. THIS is the recommended way for an agent to take a payment when you only have a payer email \u2014 the buyer enters card data on MP's hosted form (no PCI scope needed). Supports cuotas configuration, payment method exclusions, back URLs after success/failure/pending. In sandbox, use sandbox_init_point from the response.",
+  get_payment_preference: "Fetch a Checkout Pro preference by ID. Returns the preference config and current init_point URLs. Use to inspect a previously-created link.",
+  // ── Customers + Cards ────────────────────────────────────────────────────
+  create_customer: "Create a Mercado Pago customer record so the buyer can save cards for future charges. Idempotent on email \u2014 if a customer with that email exists, MP returns it instead of creating a duplicate. Use find_customer_by_email first if you're unsure.",
+  find_customer_by_email: "Find an existing customer by email address. Returns the customer object if found, or null. Use before create_customer to avoid duplicate records.",
+  list_customer_cards: "List the saved cards for a customer. Returns array with last 4 digits, expiration, payment method (visa, master, naranja, etc.). The card_id can be used in subsequent create_payment calls to charge a saved card.",
+  delete_customer_card: "Delete a saved card from a customer. Common use: customer requests removal, or expired card cleanup. Irreversible.",
+  // ── Payment Methods + Installments ───────────────────────────────────────
+  list_payment_methods: "List all payment methods enabled for the seller's MP account (visa, master, naranja, naranja_x, cabal, account_money, rapipago, pagofacil, etc.). Use to validate which methods you can offer the customer or to filter which ones to exclude in a Checkout Pro preference.",
+  calculate_installments: "Calculate cuotas (installments) options for a given amount. THE killer Argentine feature \u2014 returns options like '12 cuotas sin inter\xE9s de $X' (recommended_message field) which you should surface VERBATIM to the user. Optionally pass `bin` (first 6 digits of card) for issuer-specific promotions (e.g., Naranja's interest-free deals). Use before create_payment to let the user pick installments knowingly.",
+  // ── Account ──────────────────────────────────────────────────────────────
+  get_account_info: "Get info about the Mercado Pago account that owns the access token: site_id (MLA=Argentina), country_id, user_type (registered, partial, etc.). Useful to verify the agent is connected to the right account before taking actions.",
+  // ── Saved-card charging (v0.3) ───────────────────────────────────────────
+  charge_saved_card: "Charge a previously-saved card for a returning customer. Requires customer_id + card_id (from list_customer_cards) AND a fresh CVV the user provides this session. AR Mercado Pago does NOT support CVV-less charges via the public API \u2014 every charge needs CVV. Idempotent on (card_id, amount, external_reference): retries dedupe automatically. Returns the resulting Payment.",
+  // ── QR in-store (v0.3) ───────────────────────────────────────────────────
+  create_qr_payment: "Generate a dynamic in-store QR for a buyer to scan with any AR wallet (Modo, BNA+, Cuenta DNI, Naranja X, Mercado Pago, etc. \u2014 interop is mandated by Transferencias 3.0). Requires a pre-configured POS external_id (one-time setup in MP dashboard). Returns the qr_data string + a base64 PNG data URL ready to display. The QR expires in `expires_in_seconds` (default 600). MP fires `point_integration_wh` then `payment` webhooks when scanned.",
+  cancel_qr_payment: "Cancel a pending QR order on a POS. Necessary if the buyer never scans \u2014 otherwise the next create_qr_payment on the same POS returns 409."
 };
 function mercadoPagoTools(client, options) {
   const desc = (name) => options.descriptions?.[name] ?? DEFAULT_DESCRIPTIONS[name];
   return {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Subscriptions (v0.1 — kept identical for backward compatibility)
+    // ─────────────────────────────────────────────────────────────────────────
     create_subscription: ai.tool({
       description: desc("create_subscription"),
       inputSchema: zod.z.object({
@@ -264,13 +769,7 @@ function mercadoPagoTools(client, options) {
         reason: zod.z.string().min(3).max(120).describe("Short description shown to the customer at checkout"),
         external_reference: zod.z.string().optional().describe("Optional id from your system to track this subscription")
       }),
-      execute: async ({
-        customer_email,
-        amount_ars,
-        frequency_months,
-        reason,
-        external_reference
-      }) => {
+      execute: async ({ customer_email, amount_ars, frequency_months, reason, external_reference }) => {
         const created = await client.createPreapproval({
           reason,
           payerEmail: customer_email,
@@ -340,9 +839,7 @@ function mercadoPagoTools(client, options) {
     }),
     pause_subscription: ai.tool({
       description: desc("pause_subscription"),
-      inputSchema: zod.z.object({
-        subscription_id: zod.z.string()
-      }),
+      inputSchema: zod.z.object({ subscription_id: zod.z.string() }),
       execute: async ({ subscription_id }) => {
         const paused = await client.pausePreapproval(subscription_id);
         await options.state.set(subscription_id, { status: paused.status });
@@ -355,9 +852,7 @@ function mercadoPagoTools(client, options) {
     }),
     resume_subscription: ai.tool({
       description: desc("resume_subscription"),
-      inputSchema: zod.z.object({
-        subscription_id: zod.z.string()
-      }),
+      inputSchema: zod.z.object({ subscription_id: zod.z.string() }),
       execute: async ({ subscription_id }) => {
         const resumed = await client.resumePreapproval(subscription_id);
         await options.state.set(subscription_id, { status: resumed.status });
@@ -367,6 +862,506 @@ function mercadoPagoTools(client, options) {
           message: "Subscription resumed. Charges will continue on next scheduled date."
         };
       }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Payments (v0.2)
+    // ─────────────────────────────────────────────────────────────────────────
+    create_payment: ai.tool({
+      description: desc("create_payment"),
+      inputSchema: zod.z.object({
+        amount_ars: zod.z.number().positive().describe("Amount in ARS"),
+        payment_method_id: zod.z.string().describe("MP payment method id (e.g. 'account_money', 'rapipago', 'visa', 'master', 'naranja')"),
+        payer_email: zod.z.string().email().describe("Email of the payer. Cannot equal seller email."),
+        token: zod.z.string().optional().describe("Card token from MP frontend Cardform. Required for credit/debit; omit for cash/account_money."),
+        installments: zod.z.number().int().min(1).max(24).optional().describe("Number of installments (cuotas). Default 1. Use calculate_installments first to see options."),
+        description: zod.z.string().max(255).optional().describe("Short description"),
+        external_reference: zod.z.string().optional().describe("Your-system identifier"),
+        identification: zod.z.object({
+          type: zod.z.enum(["DNI", "CUIT", "CUIL"]),
+          number: zod.z.string()
+        }).optional().describe("Payer identification \u2014 required for some payment types in AR"),
+        statement_descriptor: zod.z.string().max(13).optional().describe("Shows on buyer's card statement (max 13 chars)")
+      }),
+      execute: async (input) => {
+        const payment = await client.createPayment({
+          transactionAmount: input.amount_ars,
+          paymentMethodId: input.payment_method_id,
+          payerEmail: input.payer_email,
+          ...input.token !== void 0 ? { token: input.token } : {},
+          ...input.installments !== void 0 ? { installments: input.installments } : {},
+          ...input.description !== void 0 ? { description: input.description } : {},
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.identification !== void 0 ? { identification: input.identification } : {},
+          ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
+          ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
+          // Deterministic idempotency key — safe to retry, same inputs always
+          // produce the same key (MP dedupes on its side).
+          idempotencyKey: deterministicIdempotencyKey(
+            "create_payment",
+            input.external_reference ?? input.payer_email,
+            input.amount_ars,
+            input.payment_method_id,
+            input.token
+          )
+        });
+        return {
+          payment_id: payment.id,
+          status: payment.status,
+          status_detail: payment.status_detail,
+          amount: payment.transaction_amount,
+          currency: payment.currency_id,
+          installments: payment.installments,
+          payment_method: payment.payment_method_id,
+          payer_email: payment.payer?.email ?? null,
+          external_reference: payment.external_reference,
+          date_created: payment.date_created,
+          date_approved: payment.date_approved
+        };
+      }
+    }),
+    get_payment: ai.tool({
+      description: desc("get_payment"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string().describe("The MP payment ID")
+      }),
+      execute: async ({ payment_id }) => {
+        const p = await client.getPayment(payment_id);
+        return {
+          payment_id: p.id,
+          status: p.status,
+          status_detail: p.status_detail,
+          amount: p.transaction_amount,
+          currency: p.currency_id,
+          payment_method: p.payment_method_id,
+          installments: p.installments,
+          payer_email: p.payer?.email ?? null,
+          external_reference: p.external_reference,
+          date_created: p.date_created,
+          date_approved: p.date_approved,
+          net_received: p.transaction_details?.net_received_amount ?? null
+        };
+      }
+    }),
+    search_payments: ai.tool({
+      description: desc("search_payments"),
+      inputSchema: zod.z.object({
+        external_reference: zod.z.string().optional(),
+        status: zod.z.string().optional().describe("'approved' | 'pending' | 'rejected' | 'cancelled' | 'refunded' etc."),
+        payer_email: zod.z.string().optional(),
+        begin_date: zod.z.string().optional().describe("ISO 8601, e.g. 2026-01-01T00:00:00Z"),
+        end_date: zod.z.string().optional().describe("ISO 8601"),
+        limit: zod.z.number().int().min(1).max(100).optional().describe("Default 30, max 100"),
+        offset: zod.z.number().int().min(0).optional().describe("Pagination offset (default 0)")
+      }),
+      execute: async (input) => {
+        const result = await client.searchPayments({
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.status !== void 0 ? { status: input.status } : {},
+          ...input.payer_email !== void 0 ? { payerEmail: input.payer_email } : {},
+          ...input.begin_date !== void 0 ? { beginDate: input.begin_date } : {},
+          ...input.end_date !== void 0 ? { endDate: input.end_date } : {},
+          ...input.limit !== void 0 ? { limit: input.limit } : {},
+          ...input.offset !== void 0 ? { offset: input.offset } : {}
+        });
+        return {
+          total: result.paging.total,
+          returned: result.results.length,
+          offset: result.paging.offset,
+          payments: result.results.map((p) => ({
+            payment_id: p.id,
+            status: p.status,
+            amount: p.transaction_amount,
+            currency: p.currency_id,
+            payer_email: p.payer?.email ?? null,
+            external_reference: p.external_reference,
+            date_created: p.date_created
+          }))
+        };
+      }
+    }),
+    cancel_payment: ai.tool({
+      description: desc("cancel_payment"),
+      inputSchema: zod.z.object({ payment_id: zod.z.string() }),
+      execute: async ({ payment_id }) => {
+        const cancelled = await client.cancelPayment(payment_id);
+        return {
+          payment_id: cancelled.id,
+          status: cancelled.status,
+          message: "Payment cancelled. If it was already approved, use refund_payment instead."
+        };
+      }
+    }),
+    capture_payment: ai.tool({
+      description: desc("capture_payment"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string(),
+        amount_ars: zod.z.number().positive().optional().describe("Optional partial-capture amount. Omit to capture full authorized amount.")
+      }),
+      execute: async ({ payment_id, amount_ars }) => {
+        const captured = await client.capturePayment(payment_id, amount_ars);
+        return {
+          payment_id: captured.id,
+          status: captured.status,
+          amount: captured.transaction_amount
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Refunds
+    // ─────────────────────────────────────────────────────────────────────────
+    refund_payment: ai.tool({
+      description: desc("refund_payment"),
+      inputSchema: zod.z.object({
+        payment_id: zod.z.string(),
+        amount_ars: zod.z.number().positive().optional().describe("Partial-refund amount in ARS. Omit for full refund.")
+      }),
+      execute: async ({ payment_id, amount_ars }) => {
+        const refund = await client.createRefund({
+          paymentId: payment_id,
+          ...amount_ars !== void 0 ? { amount: amount_ars } : {},
+          idempotencyKey: deterministicIdempotencyKey("refund", payment_id, amount_ars ?? "full")
+        });
+        return {
+          refund_id: refund.id,
+          payment_id: refund.payment_id,
+          amount: refund.amount,
+          status: refund.status,
+          message: amount_ars === void 0 ? "Full refund issued. Funds return to the buyer in 3-10 business days." : `Partial refund of ${amount_ars} ARS issued.`
+        };
+      }
+    }),
+    list_refunds: ai.tool({
+      description: desc("list_refunds"),
+      inputSchema: zod.z.object({ payment_id: zod.z.string() }),
+      execute: async ({ payment_id }) => {
+        const refunds = await client.listRefunds(payment_id);
+        return {
+          payment_id,
+          count: refunds.length,
+          refunds: refunds.map((r) => ({
+            refund_id: r.id,
+            amount: r.amount,
+            status: r.status,
+            date_created: r.date_created
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Checkout Pro
+    // ─────────────────────────────────────────────────────────────────────────
+    create_payment_preference: ai.tool({
+      description: desc("create_payment_preference"),
+      inputSchema: zod.z.object({
+        items: zod.z.array(zod.z.object({
+          title: zod.z.string().min(1).max(256),
+          quantity: zod.z.number().int().positive(),
+          unit_price: zod.z.number().positive(),
+          description: zod.z.string().optional(),
+          picture_url: zod.z.string().url().optional()
+        })).min(1).describe("Items being charged. At least one required."),
+        payer_email: zod.z.string().email().optional().describe("Pre-fill the payer email on Checkout Pro form"),
+        external_reference: zod.z.string().optional(),
+        max_installments: zod.z.number().int().min(1).max(24).optional().describe("Limit max cuotas offered. Defaults to MP account config."),
+        statement_descriptor: zod.z.string().max(13).optional(),
+        excluded_payment_types: zod.z.array(zod.z.enum(["credit_card", "debit_card", "ticket", "atm", "bank_transfer"])).optional().describe("Block payment types \u2014 e.g., ['ticket'] to disable Rapipago/Pago F\xE1cil")
+      }),
+      execute: async (input) => {
+        const pref = await client.createPreference({
+          items: input.items.map((it) => ({
+            title: it.title,
+            quantity: it.quantity,
+            unit_price: it.unit_price,
+            currency_id: "ARS",
+            ...it.description !== void 0 ? { description: it.description } : {},
+            ...it.picture_url !== void 0 ? { picture_url: it.picture_url } : {}
+          })),
+          ...input.payer_email !== void 0 ? { payer: { email: input.payer_email } } : {},
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
+          backUrls: { success: options.backUrl, failure: options.backUrl, pending: options.backUrl },
+          autoReturn: "approved",
+          ...options.notificationUrl !== void 0 ? { notificationUrl: options.notificationUrl } : {},
+          ...input.max_installments !== void 0 || input.excluded_payment_types !== void 0 ? {
+            paymentMethods: {
+              ...input.max_installments !== void 0 ? { installments: input.max_installments } : {},
+              ...input.excluded_payment_types !== void 0 ? { excluded_payment_types: input.excluded_payment_types.map((id) => ({ id })) } : {}
+            }
+          } : {}
+        });
+        return {
+          preference_id: pref.id,
+          init_point_url: pref.init_point ?? null,
+          sandbox_init_point_url: pref.sandbox_init_point ?? null,
+          external_reference: pref.external_reference,
+          date_created: pref.date_created,
+          next_step: "Send init_point_url (or sandbox_init_point_url in sandbox) to the customer. After they pay, MP fires a webhook with the payment_id; use get_payment to confirm status."
+        };
+      }
+    }),
+    get_payment_preference: ai.tool({
+      description: desc("get_payment_preference"),
+      inputSchema: zod.z.object({ preference_id: zod.z.string() }),
+      execute: async ({ preference_id }) => {
+        const pref = await client.getPreference(preference_id);
+        return {
+          preference_id: pref.id,
+          init_point_url: pref.init_point ?? null,
+          sandbox_init_point_url: pref.sandbox_init_point ?? null,
+          external_reference: pref.external_reference,
+          items: pref.items,
+          date_created: pref.date_created
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Customers + Saved Cards
+    // ─────────────────────────────────────────────────────────────────────────
+    create_customer: ai.tool({
+      description: desc("create_customer"),
+      inputSchema: zod.z.object({
+        email: zod.z.string().email(),
+        first_name: zod.z.string().optional(),
+        last_name: zod.z.string().optional(),
+        identification: zod.z.object({
+          type: zod.z.enum(["DNI", "CUIT", "CUIL"]),
+          number: zod.z.string()
+        }).optional(),
+        description: zod.z.string().optional()
+      }),
+      execute: async (input) => {
+        const customer = await client.createCustomer({
+          email: input.email,
+          ...input.first_name !== void 0 ? { firstName: input.first_name } : {},
+          ...input.last_name !== void 0 ? { lastName: input.last_name } : {},
+          ...input.identification !== void 0 ? { identification: input.identification } : {},
+          ...input.description !== void 0 ? { description: input.description } : {}
+        });
+        return {
+          customer_id: customer.id,
+          email: customer.email,
+          first_name: customer.first_name,
+          last_name: customer.last_name,
+          date_created: customer.date_created
+        };
+      }
+    }),
+    find_customer_by_email: ai.tool({
+      description: desc("find_customer_by_email"),
+      inputSchema: zod.z.object({ email: zod.z.string().email() }),
+      execute: async ({ email }) => {
+        const result = await client.searchCustomers({ email, limit: 1 });
+        const customer = result.results[0] ?? null;
+        return customer ? {
+          found: true,
+          customer_id: customer.id,
+          email: customer.email,
+          first_name: customer.first_name,
+          last_name: customer.last_name
+        } : { found: false, customer_id: null };
+      }
+    }),
+    list_customer_cards: ai.tool({
+      description: desc("list_customer_cards"),
+      inputSchema: zod.z.object({ customer_id: zod.z.string() }),
+      execute: async ({ customer_id }) => {
+        const cards = await client.listCustomerCards(customer_id);
+        return {
+          customer_id,
+          count: cards.length,
+          cards: cards.map((c) => ({
+            card_id: c.id,
+            last_four_digits: c.last_four_digits,
+            expiration_month: c.expiration_month,
+            expiration_year: c.expiration_year,
+            payment_method: c.payment_method?.id ?? null,
+            payment_method_name: c.payment_method?.name ?? null
+          }))
+        };
+      }
+    }),
+    delete_customer_card: ai.tool({
+      description: desc("delete_customer_card"),
+      inputSchema: zod.z.object({
+        customer_id: zod.z.string(),
+        card_id: zod.z.string()
+      }),
+      execute: async ({ customer_id, card_id }) => {
+        await client.deleteCustomerCard(customer_id, card_id);
+        return { customer_id, card_id, deleted: true };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Payment Methods + Installments
+    // ─────────────────────────────────────────────────────────────────────────
+    list_payment_methods: ai.tool({
+      description: desc("list_payment_methods"),
+      inputSchema: zod.z.object({}),
+      execute: async () => {
+        const methods = await client.listPaymentMethods();
+        return {
+          count: methods.length,
+          methods: methods.map((m) => ({
+            id: m.id,
+            name: m.name,
+            payment_type: m.payment_type_id,
+            status: m.status,
+            min_amount: m.min_allowed_amount,
+            max_amount: m.max_allowed_amount
+          }))
+        };
+      }
+    }),
+    calculate_installments: ai.tool({
+      description: desc("calculate_installments"),
+      inputSchema: zod.z.object({
+        amount_ars: zod.z.number().positive(),
+        payment_method_id: zod.z.string().optional().describe("E.g. 'visa', 'master', 'naranja'. Omit for all available methods."),
+        bin: zod.z.string().min(6).max(8).optional().describe("First 6-8 digits of card for issuer-specific offers (e.g., Naranja interest-free promotions)")
+      }),
+      execute: async (input) => {
+        const offers = await client.getInstallments({
+          amount: input.amount_ars,
+          ...input.payment_method_id !== void 0 ? { paymentMethodId: input.payment_method_id } : {},
+          ...input.bin !== void 0 ? { bin: input.bin } : {}
+        });
+        return {
+          amount: input.amount_ars,
+          offers: offers.map((o) => ({
+            payment_method_id: o.payment_method_id,
+            payment_type_id: o.payment_type_id,
+            issuer_name: o.issuer?.name ?? null,
+            options: o.payer_costs.map((pc) => ({
+              installments: pc.installments,
+              installment_amount: pc.installment_amount,
+              total_amount: pc.total_amount,
+              installment_rate: pc.installment_rate,
+              recommended_message: pc.recommended_message
+            }))
+          }))
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Account
+    // ─────────────────────────────────────────────────────────────────────────
+    get_account_info: ai.tool({
+      description: desc("get_account_info"),
+      inputSchema: zod.z.object({}),
+      execute: async () => {
+        const me = await client.getMe();
+        return {
+          account_id: me.id,
+          email: me.email,
+          nickname: me.nickname,
+          country_id: me.country_id,
+          site_id: me.site_id,
+          user_type: me.user_type
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // Saved-card charging (v0.3)
+    // ─────────────────────────────────────────────────────────────────────────
+    charge_saved_card: ai.tool({
+      description: desc("charge_saved_card"),
+      inputSchema: zod.z.object({
+        customer_id: zod.z.string().describe("MP customer id (from create_customer / find_customer_by_email)"),
+        card_id: zod.z.string().describe("Saved card id (from list_customer_cards)"),
+        security_code: zod.z.string().regex(/^\d{3,4}$/).describe("CVV \u2014 3 digits (Visa/Master) or 4 (Amex). User must provide this each charge in AR."),
+        amount_ars: zod.z.number().positive(),
+        description: zod.z.string().min(1).max(255),
+        installments: zod.z.number().int().min(1).max(24).optional().describe("Default 1. Use calculate_installments first to pick a valid count."),
+        external_reference: zod.z.string().optional(),
+        statement_descriptor: zod.z.string().max(13).optional()
+      }),
+      execute: async (input) => {
+        const payment = await client.chargeSavedCard({
+          customerId: input.customer_id,
+          cardId: input.card_id,
+          securityCode: input.security_code,
+          amount: input.amount_ars,
+          description: input.description,
+          ...input.installments !== void 0 ? { installments: input.installments } : {},
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.statement_descriptor !== void 0 ? { statementDescriptor: input.statement_descriptor } : {},
+          idempotencyKey: deterministicIdempotencyKey(
+            "charge_saved_card",
+            input.card_id,
+            input.amount_ars,
+            input.external_reference
+          )
+        });
+        return {
+          payment_id: payment.id,
+          status: payment.status,
+          status_detail: payment.status_detail,
+          amount: payment.transaction_amount,
+          installments: payment.installments,
+          payment_method: payment.payment_method_id,
+          customer_id: input.customer_id,
+          card_id: input.card_id,
+          external_reference: payment.external_reference,
+          date_approved: payment.date_approved
+        };
+      }
+    }),
+    // ─────────────────────────────────────────────────────────────────────────
+    // QR in-store (v0.3)
+    // ─────────────────────────────────────────────────────────────────────────
+    create_qr_payment: ai.tool({
+      description: desc("create_qr_payment"),
+      inputSchema: zod.z.object({
+        external_pos_id: zod.z.string().describe("Pre-configured POS external_id from MP dashboard. Required."),
+        amount_ars: zod.z.number().positive(),
+        title: zod.z.string().min(1).max(80).describe("Display title shown when scanning"),
+        description: zod.z.string().max(255).optional(),
+        external_reference: zod.z.string().optional(),
+        notification_url: zod.z.string().url().optional().describe("Webhook URL \u2014 falls back to dashboard config if omitted"),
+        expires_in_seconds: zod.z.number().int().min(60).max(3600).optional().describe("Default 600 (10 min)")
+      }),
+      execute: async (input) => {
+        const QRCode = (await import('qrcode')).default;
+        const me = await client.getMe();
+        const userId = String(me.id);
+        const expiresAt = new Date(
+          Date.now() + (input.expires_in_seconds ?? 600) * 1e3
+        ).toISOString();
+        const qr = await client.createQrPayment(userId, {
+          externalPosId: input.external_pos_id,
+          totalAmount: input.amount_ars,
+          title: input.title,
+          ...input.description !== void 0 ? { description: input.description } : {},
+          ...input.external_reference !== void 0 ? { externalReference: input.external_reference } : {},
+          ...input.notification_url !== void 0 ? { notificationUrl: input.notification_url } : {},
+          expirationDate: expiresAt
+        });
+        const qrDataUrl = await QRCode.toDataURL(qr.qr_data, {
+          errorCorrectionLevel: "M",
+          margin: 1,
+          width: 512
+        });
+        return {
+          in_store_order_id: qr.in_store_order_id,
+          qr_data: qr.qr_data,
+          qr_data_url: qrDataUrl,
+          expires_at: expiresAt,
+          external_pos_id: input.external_pos_id,
+          amount: input.amount_ars,
+          next_step: "Display the qr_data_url image to the buyer. Wait for the payment webhook (point_integration_wh fires first, then payment topic). If buyer doesn't scan in time, call cancel_qr_payment to free the POS."
+        };
+      }
+    }),
+    cancel_qr_payment: ai.tool({
+      description: desc("cancel_qr_payment"),
+      inputSchema: zod.z.object({
+        external_pos_id: zod.z.string()
+      }),
+      execute: async ({ external_pos_id }) => {
+        const me = await client.getMe();
+        await client.cancelQrPayment(String(me.id), external_pos_id);
+        return { external_pos_id, cancelled: true };
+      }
     })
   };
 }
@@ -431,6 +1426,162 @@ var WebhookBodySchema = zod.z.object({
   id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
   live_mode: zod.z.boolean().optional()
 }).passthrough();
+var PaymentStatusSchema = zod.z.union([
+  zod.z.literal("pending"),
+  zod.z.literal("approved"),
+  zod.z.literal("authorized"),
+  zod.z.literal("in_process"),
+  zod.z.literal("in_mediation"),
+  zod.z.literal("rejected"),
+  zod.z.literal("cancelled"),
+  zod.z.literal("refunded"),
+  zod.z.literal("charged_back"),
+  zod.z.string()
+]);
+var PaymentSchema = zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  status: PaymentStatusSchema,
+  status_detail: zod.z.string().nullable().optional(),
+  date_created: zod.z.string().nullable().optional(),
+  date_approved: zod.z.string().nullable().optional(),
+  date_last_updated: zod.z.string().nullable().optional(),
+  transaction_amount: zod.z.number(),
+  currency_id: zod.z.string(),
+  installments: zod.z.number().int().nullable().optional(),
+  payment_method_id: zod.z.string().nullable().optional(),
+  payment_type_id: zod.z.string().nullable().optional(),
+  external_reference: zod.z.string().nullable().optional(),
+  description: zod.z.string().nullable().optional(),
+  payer: zod.z.object({
+    id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+    email: zod.z.string().nullable().optional(),
+    identification: zod.z.object({
+      type: zod.z.string().nullable().optional(),
+      number: zod.z.string().nullable().optional()
+    }).nullable().optional()
+  }).passthrough().optional(),
+  transaction_details: zod.z.object({
+    net_received_amount: zod.z.number().nullable().optional(),
+    total_paid_amount: zod.z.number().nullable().optional(),
+    installment_amount: zod.z.number().nullable().optional()
+  }).passthrough().optional()
+}).passthrough();
+zod.z.object({
+  paging: zod.z.object({
+    total: zod.z.number(),
+    limit: zod.z.number(),
+    offset: zod.z.number()
+  }),
+  results: zod.z.array(PaymentSchema)
+});
+zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  payment_id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  amount: zod.z.number(),
+  source: zod.z.object({
+    id: zod.z.string().nullable().optional(),
+    name: zod.z.string().nullable().optional(),
+    type: zod.z.string().nullable().optional()
+  }).nullable().optional(),
+  date_created: zod.z.string().nullable().optional(),
+  status: zod.z.string().nullable().optional()
+}).passthrough();
+var PreferenceItemSchema = zod.z.object({
+  id: zod.z.string().optional(),
+  title: zod.z.string(),
+  description: zod.z.string().optional(),
+  picture_url: zod.z.string().url().optional(),
+  category_id: zod.z.string().optional(),
+  quantity: zod.z.number().int().positive(),
+  unit_price: zod.z.number().positive(),
+  currency_id: CurrencyIdSchema.optional()
+});
+zod.z.object({
+  id: zod.z.string(),
+  init_point: zod.z.string().url().optional(),
+  sandbox_init_point: zod.z.string().url().optional(),
+  client_id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+  collector_id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+  items: zod.z.array(PreferenceItemSchema).optional(),
+  external_reference: zod.z.string().nullable().optional(),
+  date_created: zod.z.string().nullable().optional(),
+  expires: zod.z.boolean().optional(),
+  expiration_date_from: zod.z.string().nullable().optional(),
+  expiration_date_to: zod.z.string().nullable().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.string(),
+  email: zod.z.string(),
+  first_name: zod.z.string().nullable().optional(),
+  last_name: zod.z.string().nullable().optional(),
+  phone: zod.z.object({ area_code: zod.z.string().nullable().optional(), number: zod.z.string().nullable().optional() }).nullable().optional(),
+  identification: zod.z.object({ type: zod.z.string().nullable().optional(), number: zod.z.string().nullable().optional() }).nullable().optional(),
+  date_created: zod.z.string().nullable().optional(),
+  date_last_updated: zod.z.string().nullable().optional(),
+  description: zod.z.string().nullable().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.string(),
+  customer_id: zod.z.string(),
+  expiration_month: zod.z.number().int().nullable().optional(),
+  expiration_year: zod.z.number().int().nullable().optional(),
+  first_six_digits: zod.z.string().nullable().optional(),
+  last_four_digits: zod.z.string().nullable().optional(),
+  payment_method: zod.z.object({
+    id: zod.z.string().nullable().optional(),
+    name: zod.z.string().nullable().optional(),
+    payment_type_id: zod.z.string().nullable().optional()
+  }).nullable().optional(),
+  date_created: zod.z.string().nullable().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.string(),
+  name: zod.z.string(),
+  payment_type_id: zod.z.string(),
+  status: zod.z.string(),
+  thumbnail: zod.z.string().nullable().optional(),
+  secure_thumbnail: zod.z.string().nullable().optional(),
+  min_allowed_amount: zod.z.number().nullable().optional(),
+  max_allowed_amount: zod.z.number().nullable().optional()
+}).passthrough();
+zod.z.object({
+  payment_method_id: zod.z.string(),
+  payment_type_id: zod.z.string(),
+  issuer: zod.z.object({
+    id: zod.z.union([zod.z.string(), zod.z.number()]).optional(),
+    name: zod.z.string().nullable().optional()
+  }).nullable().optional(),
+  payer_costs: zod.z.array(
+    zod.z.object({
+      installments: zod.z.number().int(),
+      installment_rate: zod.z.number(),
+      discount_rate: zod.z.number().nullable().optional(),
+      installment_amount: zod.z.number(),
+      total_amount: zod.z.number(),
+      recommended_message: zod.z.string().nullable().optional()
+    }).passthrough()
+  )
+}).passthrough();
+zod.z.object({
+  in_store_order_id: zod.z.string(),
+  qr_data: zod.z.string()
+}).passthrough();
+zod.z.object({
+  id: zod.z.string(),
+  status: zod.z.string().optional(),
+  date_due: zod.z.string().optional(),
+  card_id: zod.z.string().optional(),
+  cardholder: zod.z.unknown().optional()
+}).passthrough();
+zod.z.object({
+  id: zod.z.union([zod.z.string(), zod.z.number()]).transform(String),
+  email: zod.z.string().nullable().optional(),
+  nickname: zod.z.string().nullable().optional(),
+  country_id: zod.z.string().nullable().optional(),
+  site_id: zod.z.string().nullable().optional(),
+  user_type: zod.z.string().nullable().optional(),
+  status: zod.z.object({ user_type: zod.z.string().nullable().optional() }).passthrough().nullable().optional()
+}).passthrough();
 
 // src/webhook.ts
 function parseWebhookEvent(body, searchParams) {
@@ -469,9 +1620,11 @@ exports.MercadoPagoAuthorizeForbiddenError = MercadoPagoAuthorizeForbiddenError;
 exports.MercadoPagoBackUrlInvalidError = MercadoPagoBackUrlInvalidError;
 exports.MercadoPagoClient = MercadoPagoClient;
 exports.MercadoPagoError = MercadoPagoError;
+exports.MercadoPagoOverloadedError = MercadoPagoOverloadedError;
 exports.MercadoPagoPaymentRejectedError = MercadoPagoPaymentRejectedError;
 exports.MercadoPagoRateLimitError = MercadoPagoRateLimitError;
 exports.MercadoPagoSelfPaymentError = MercadoPagoSelfPaymentError;
+exports.MercadoPagoTimeoutError = MercadoPagoTimeoutError;
 exports.classifyError = classifyError;
 exports.mercadoPagoTools = mercadoPagoTools;
 exports.parseWebhookEvent = parseWebhookEvent;