@ar-agents/mercadopago 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -66,6 +66,23 @@ declare class MercadoPagoRateLimitError extends MercadoPagoError {
     retryAfterSeconds: number | null;
     constructor(endpoint: string, retryAfterSeconds: number | null, body?: unknown);
 }
+/**
+ * Thrown when MP is overloaded and serves an HTML 503 page instead of a JSON
+ * error. The library detects content-type !== application/json on 5xx and
+ * raises this typed error so retry logic + agent UX can branch correctly.
+ */
+declare class MercadoPagoOverloadedError extends MercadoPagoError {
+    constructor(endpoint: string, status: number);
+}
+/**
+ * Thrown when a request exceeds the configured `requestTimeoutMs`. Retried
+ * automatically up to `maxRetries`; this surfaces only when the budget runs
+ * out.
+ */
+declare class MercadoPagoTimeoutError extends MercadoPagoError {
+    readonly timeoutMs: number;
+    constructor(endpoint: string, timeoutMs: number);
+}
 /**
  * Maps an MP error response body to the most specific known error class. Falls
  * back to the generic MercadoPagoError when no specific pattern matches.
@@ -217,6 +234,391 @@ interface ParsedWebhookEvent {
     /** Raw body MP sent, for caller inspection / debugging. */
     raw: WebhookBody;
 }
+/**
+ * Top-level lifecycle status of a payment. MP-canonical values; widened to
+ * string for forward compatibility.
+ */
+declare const PaymentStatusSchema: z.ZodUnion<readonly [z.ZodLiteral<"pending">, z.ZodLiteral<"approved">, z.ZodLiteral<"authorized">, z.ZodLiteral<"in_process">, z.ZodLiteral<"in_mediation">, z.ZodLiteral<"rejected">, z.ZodLiteral<"cancelled">, z.ZodLiteral<"refunded">, z.ZodLiteral<"charged_back">, z.ZodString]>;
+type PaymentStatus = z.infer<typeof PaymentStatusSchema>;
+/**
+ * The full Payment object MP returns. Many fields are optional because they
+ * vary by payment method, status, and integration mode (Checkout Pro vs API).
+ */
+declare const PaymentSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodUnion<readonly [z.ZodLiteral<"pending">, z.ZodLiteral<"approved">, z.ZodLiteral<"authorized">, z.ZodLiteral<"in_process">, z.ZodLiteral<"in_mediation">, z.ZodLiteral<"rejected">, z.ZodLiteral<"cancelled">, z.ZodLiteral<"refunded">, z.ZodLiteral<"charged_back">, z.ZodString]>;
+    status_detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_created: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_approved: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_last_updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transaction_amount: z.ZodNumber;
+    currency_id: z.ZodString;
+    installments: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    payment_method_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    payment_type_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    external_reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    payer: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        identification: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$loose>>;
+    transaction_details: z.ZodOptional<z.ZodObject<{
+        net_received_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        total_paid_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        installment_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type Payment = z.infer<typeof PaymentSchema>;
+/** Params for creating a payment (Checkout API / transparent flow). */
+interface CreatePaymentParams {
+    /** Amount in account currency. ARS for Argentina. */
+    transactionAmount: number;
+    /** Number of installments. Use 1 for no cuotas; AR cards typically allow up to 12. */
+    installments?: number;
+    /** MP payment_method_id — `visa`, `master`, `naranja`, `account_money`, etc. */
+    paymentMethodId: string;
+    /** Payer email — REQUIRED. Cannot equal seller email. */
+    payerEmail: string;
+    /** Card token from MP frontend SDK (Cardform). Required for credit/debit; omit for `account_money` etc. */
+    token?: string;
+    /** Description shown in payer's MP statement. */
+    description?: string;
+    /** Your-system identifier for correlation. */
+    externalReference?: string;
+    /** Optional payer identification (DNI/CUIT) — required for some payment types. */
+    identification?: {
+        type: "DNI" | "CUIT" | "CUIL";
+        number: string;
+    };
+    /** Webhook override URL. Falls back to dashboard config if omitted. */
+    notificationUrl?: string;
+    /** AFIP/ARCA discount/fee/tax additions. Used to discriminate IVA, marketplace fees, etc. */
+    additionalInfo?: {
+        items?: Array<{
+            id?: string;
+            title: string;
+            quantity: number;
+            unit_price: number;
+            description?: string;
+        }>;
+    };
+    /** Statement descriptor — what shows on the buyer's card statement. Max 13 chars. */
+    statementDescriptor?: string;
+    /** When true, capture is deferred (only for credit cards) — useful for hold flows. */
+    capture?: boolean;
+    /** Idempotency key — pass the same value on retries to dedupe. Required for non-GET. */
+    idempotencyKey?: string;
+}
+interface SearchPaymentsParams {
+    /** Filter by external_reference (your-system id). */
+    externalReference?: string;
+    /** Filter by payment status. */
+    status?: PaymentStatus;
+    /** Filter by payer email. */
+    payerEmail?: string;
+    /** Date range for date_created (ISO 8601). */
+    beginDate?: string;
+    endDate?: string;
+    /** Result page (default 0). */
+    offset?: number;
+    /** Page size (default 30, max 100). */
+    limit?: number;
+    /** Sort: e.g. "date_created" desc. */
+    sort?: string;
+    criteria?: "asc" | "desc";
+}
+declare const PaymentsSearchResultSchema: z.ZodObject<{
+    paging: z.ZodObject<{
+        total: z.ZodNumber;
+        limit: z.ZodNumber;
+        offset: z.ZodNumber;
+    }, z.core.$strip>;
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+        status: z.ZodUnion<readonly [z.ZodLiteral<"pending">, z.ZodLiteral<"approved">, z.ZodLiteral<"authorized">, z.ZodLiteral<"in_process">, z.ZodLiteral<"in_mediation">, z.ZodLiteral<"rejected">, z.ZodLiteral<"cancelled">, z.ZodLiteral<"refunded">, z.ZodLiteral<"charged_back">, z.ZodString]>;
+        status_detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        date_created: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        date_approved: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        date_last_updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        transaction_amount: z.ZodNumber;
+        currency_id: z.ZodString;
+        installments: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        payment_method_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        payment_type_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        external_reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        payer: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            identification: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>;
+        }, z.core.$loose>>;
+        transaction_details: z.ZodOptional<z.ZodObject<{
+            net_received_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            total_paid_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            installment_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+type PaymentsSearchResult = z.infer<typeof PaymentsSearchResultSchema>;
+declare const RefundSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    payment_id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    amount: z.ZodNumber;
+    source: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    date_created: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+type Refund = z.infer<typeof RefundSchema>;
+interface CreateRefundParams {
+    paymentId: string;
+    /** Partial refund amount. Omit for full refund. */
+    amount?: number;
+    /** Idempotency key — required for retry-safety. */
+    idempotencyKey?: string;
+}
+declare const PreferenceItemSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    picture_url: z.ZodOptional<z.ZodString>;
+    category_id: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodNumber;
+    unit_price: z.ZodNumber;
+    currency_id: z.ZodOptional<z.ZodEnum<{
+        ARS: "ARS";
+        USD: "USD";
+        BRL: "BRL";
+        MXN: "MXN";
+    }>>;
+}, z.core.$strip>;
+type PreferenceItem = z.infer<typeof PreferenceItemSchema>;
+declare const PreferenceSchema: z.ZodObject<{
+    id: z.ZodString;
+    init_point: z.ZodOptional<z.ZodString>;
+    sandbox_init_point: z.ZodOptional<z.ZodString>;
+    client_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    collector_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        picture_url: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodString>;
+        quantity: z.ZodNumber;
+        unit_price: z.ZodNumber;
+        currency_id: z.ZodOptional<z.ZodEnum<{
+            ARS: "ARS";
+            USD: "USD";
+            BRL: "BRL";
+            MXN: "MXN";
+        }>>;
+    }, z.core.$strip>>>;
+    external_reference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_created: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expires: z.ZodOptional<z.ZodBoolean>;
+    expiration_date_from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expiration_date_to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+type Preference = z.infer<typeof PreferenceSchema>;
+interface CreatePreferenceParams {
+    items: Array<{
+        title: string;
+        quantity: number;
+        unit_price: number;
+        currency_id?: CurrencyId;
+        description?: string;
+        picture_url?: string;
+    }>;
+    payer?: {
+        name?: string;
+        surname?: string;
+        email?: string;
+        phone?: {
+            area_code?: string;
+            number?: string;
+        };
+        identification?: {
+            type: string;
+            number: string;
+        };
+        address?: {
+            street_name?: string;
+            street_number?: number;
+            zip_code?: string;
+        };
+    };
+    /** Where to send the buyer after success/failure/pending. */
+    backUrls?: {
+        success?: string;
+        failure?: string;
+        pending?: string;
+    };
+    /** "approved" → auto-redirect on success; "all" → always; "" → never. */
+    autoReturn?: "approved" | "all";
+    /** Webhook URL. */
+    notificationUrl?: string;
+    /** Your-system id for correlation. */
+    externalReference?: string;
+    /** Max installments offered. Defaults to MP account config. */
+    paymentMethods?: {
+        excluded_payment_types?: Array<{
+            id: string;
+        }>;
+        excluded_payment_methods?: Array<{
+            id: string;
+        }>;
+        installments?: number;
+        default_installments?: number;
+    };
+    /** Statement descriptor — shows on buyer's card statement. */
+    statementDescriptor?: string;
+    /** Expiration window for the link itself. */
+    expires?: boolean;
+    expirationDateFrom?: string;
+    expirationDateTo?: string;
+}
+declare const CustomerSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    first_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    phone: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        area_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    identification: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    date_created: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_last_updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+type Customer = z.infer<typeof CustomerSchema>;
+declare const CustomerCardSchema: z.ZodObject<{
+    id: z.ZodString;
+    customer_id: z.ZodString;
+    expiration_month: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    expiration_year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    first_six_digits: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_four_digits: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    payment_method: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        payment_type_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    date_created: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+type CustomerCard = z.infer<typeof CustomerCardSchema>;
+interface CreateCustomerParams {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: {
+        areaCode?: string;
+        number?: string;
+    };
+    identification?: {
+        type: "DNI" | "CUIT" | "CUIL";
+        number: string;
+    };
+    description?: string;
+}
+declare const PaymentMethodSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    payment_type_id: z.ZodString;
+    status: z.ZodString;
+    thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    secure_thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    min_allowed_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    max_allowed_amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+type PaymentMethod = z.infer<typeof PaymentMethodSchema>;
+declare const InstallmentOfferSchema: z.ZodObject<{
+    payment_method_id: z.ZodString;
+    payment_type_id: z.ZodString;
+    issuer: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    payer_costs: z.ZodArray<z.ZodObject<{
+        installments: z.ZodNumber;
+        installment_rate: z.ZodNumber;
+        discount_rate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        installment_amount: z.ZodNumber;
+        total_amount: z.ZodNumber;
+        recommended_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type InstallmentOffer = z.infer<typeof InstallmentOfferSchema>;
+declare const QrOrderSchema: z.ZodObject<{
+    in_store_order_id: z.ZodString;
+    qr_data: z.ZodString;
+}, z.core.$loose>;
+type QrOrder = z.infer<typeof QrOrderSchema>;
+interface CreateQrPaymentParams {
+    /** Pre-configured POS external_id from MP dashboard. Required. */
+    externalPosId: string;
+    /** Total amount in ARS. */
+    totalAmount: number;
+    /** Display title shown to the buyer when scanning. */
+    title: string;
+    description?: string;
+    /** Webhook URL — MP fires `point_integration_wh` then `payment` topic. */
+    notificationUrl?: string;
+    /** Your-system identifier for correlation. */
+    externalReference?: string;
+    /** ISO 8601 expiration (default 10 min from now). */
+    expirationDate?: string;
+    /** Itemized line items (optional but improves analytics). */
+    items?: Array<{
+        title: string;
+        quantity: number;
+        unit_price: number;
+        unit_measure?: string;
+        total_amount?: number;
+    }>;
+}
+declare const CardTokenSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    date_due: z.ZodOptional<z.ZodString>;
+    card_id: z.ZodOptional<z.ZodString>;
+    cardholder: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type CardToken = z.infer<typeof CardTokenSchema>;
+interface CreateCardTokenParams {
+    /** Saved card id (from list_customer_cards). */
+    cardId: string;
+    /** Customer that owns the card. */
+    customerId: string;
+    /** CVV — required for AR; MP doesn't store CVV. */
+    securityCode: string;
+}
+declare const AccountInfoSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    nickname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    country_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    site_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    user_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        user_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+type AccountInfo = z.infer<typeof AccountInfoSchema>;
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -231,16 +633,44 @@ interface MercadoPagoClientOptions {
      * inject your own retry/instrumentation layer or to test with MSW.
      */
     fetch?: typeof fetch;
+    /**
+     * Per-request timeout in ms. Aborts the request and throws if exceeded.
+     * Default 30_000 (30s). MP can be slow under load; 30s is a safe upper bound.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Number of retries on 5xx + network errors. Default 1 (single retry).
+     * 4xx errors are NEVER retried (they're user/config errors). Each retry
+     * uses exponential backoff: 250ms, 500ms, 1000ms, ...
+     */
+    maxRetries?: number;
+    /**
+     * Observability hook fired AFTER every request (success or failure).
+     * Useful for logging, metrics, tracing. Synchronous, fire-and-forget.
+     */
+    onCall?: (event: {
+        method: string;
+        path: string;
+        durationMs: number;
+        httpStatus: number | null;
+        retried: number;
+        success: boolean;
+    }) => void;
 }
 /**
- * Thin, typed wrapper around Mercado Pago's REST API. Only the endpoints the
- * agent layer needs are exposed; this is deliberately narrow rather than a
- * full SDK rebuild.
+ * Thin, typed wrapper around Mercado Pago's REST API. Exposes the surface
+ * the agent layer needs: Subscriptions (Preapprovals), Payments, Checkout Pro
+ * (Preferences), Customers + saved Cards, Refunds, Payment Methods +
+ * Installments, and Account info. Deliberately narrower than a full SDK
+ * rebuild — we add endpoints when the agent layer needs them.
  */
 declare class MercadoPagoClient {
     private readonly accessToken;
     private readonly baseUrl;
     private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly maxRetries;
+    private readonly onCall;
     constructor(options: MercadoPagoClientOptions);
     private request;
     /**
@@ -249,28 +679,147 @@ declare class MercadoPagoClient {
      * CVV — there is no API path that bypasses this human step.
      */
     createPreapproval(params: CreatePreapprovalParams): Promise<Preapproval>;
+    getPreapproval(id: string): Promise<Preapproval>;
+    cancelPreapproval(id: string): Promise<Preapproval>;
+    pausePreapproval(id: string): Promise<Preapproval>;
+    resumePreapproval(id: string): Promise<Preapproval>;
     /**
-     * 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.
      */
-    getPreapproval(id: string): Promise<Preapproval>;
+    createPayment(params: CreatePaymentParams): Promise<Payment>;
+    /** Fetch a payment by ID. */
+    getPayment(id: string): Promise<Payment>;
     /**
-     * Cancel an active preapproval. Irreversible: MP will not charge the buyer
-     * again and the subscription cannot be reactivated.
+     * Search payments with filters. Common: by external_reference (your-system
+     * id), by status, by date range. Pagination via offset + limit (max 100).
      */
-    cancelPreapproval(id: string): Promise<Preapproval>;
+    searchPayments(params?: SearchPaymentsParams): Promise<PaymentsSearchResult>;
     /**
-     * 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.
+     * Capture a previously authorized payment. Only works for credit-card
+     * payments created with `capture: false`. Optional partial capture amount.
      */
-    pausePreapproval(id: string): Promise<Preapproval>;
+    capturePayment(id: string, amount?: number): Promise<Payment>;
     /**
-     * Re-activate a paused preapproval. Charges resume on the next scheduled
-     * date.
+     * Cancel a pending or in_process payment. Once approved, you must use
+     * `createRefund` instead.
      */
-    resumePreapproval(id: string): Promise<Preapproval>;
+    cancelPayment(id: string): Promise<Payment>;
+    /**
+     * 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.
+     */
+    createRefund(params: CreateRefundParams): Promise<Refund>;
+    listRefunds(paymentId: string): Promise<Refund[]>;
+    getRefund(paymentId: string, refundId: string): Promise<Refund>;
+    /**
+     * 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`.
+     */
+    createPreference(params: CreatePreferenceParams): Promise<Preference>;
+    getPreference(id: string): Promise<Preference>;
+    updatePreference(id: string, patch: Partial<CreatePreferenceParams>): Promise<Preference>;
+    createCustomer(params: CreateCustomerParams): Promise<Customer>;
+    getCustomer(id: string): Promise<Customer>;
+    /**
+     * 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.
+     */
+    searchCustomers(params?: {
+        email?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        paging: {
+            total: number;
+            limit: number;
+            offset: number;
+        };
+        results: Customer[];
+    }>;
+    listCustomerCards(customerId: string): Promise<CustomerCard[]>;
+    getCustomerCard(customerId: string, cardId: string): Promise<CustomerCard>;
+    deleteCustomerCard(customerId: string, cardId: string): Promise<void>;
+    /** List all payment methods enabled for the account's site (MLA = Argentina). */
+    listPaymentMethods(): Promise<PaymentMethod[]>;
+    /**
+     * 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.
+     */
+    getInstallments(params: {
+        amount: number;
+        paymentMethodId?: string;
+        bin?: string;
+        issuerId?: string;
+    }): Promise<InstallmentOffer[]>;
+    /** Get info about the account that owns this access token. */
+    getMe(): Promise<AccountInfo>;
+    /**
+     * 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.
+     */
+    createCardToken(params: CreateCardTokenParams): Promise<CardToken>;
+    /**
+     * 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.
+     */
+    chargeSavedCard(params: {
+        customerId: string;
+        cardId: string;
+        securityCode: string;
+        amount: number;
+        description: string;
+        installments?: number;
+        externalReference?: string;
+        statementDescriptor?: string;
+        idempotencyKey?: string;
+    }): Promise<Payment>;
+    /**
+     * 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.
+     */
+    createQrPayment(userId: string, params: CreateQrPaymentParams): Promise<QrOrder>;
+    /**
+     * Cancel a pending QR order on a POS. Necessary if the buyer never scans
+     * — otherwise the next `createQrPayment` on the same POS returns 409.
+     */
+    cancelQrPayment(userId: string, externalPosId: string): Promise<void>;
 }
 
 /**
@@ -333,12 +882,17 @@ interface MercadoPagoToolsOptions {
      * Useful for localizing the agent's tool reasoning.
      */
     descriptions?: Partial<Record<ToolName, string>>;
+    /**
+     * Default notification webhook URL used when callers don't supply one.
+     * Optional — MP falls back to dashboard config if not set.
+     */
+    notificationUrl?: string;
 }
-type ToolName = "create_subscription" | "get_subscription_status" | "cancel_subscription" | "pause_subscription" | "resume_subscription";
+type ToolName = "create_subscription" | "get_subscription_status" | "cancel_subscription" | "pause_subscription" | "resume_subscription" | "create_payment" | "get_payment" | "search_payments" | "cancel_payment" | "capture_payment" | "refund_payment" | "list_refunds" | "create_payment_preference" | "get_payment_preference" | "create_customer" | "find_customer_by_email" | "list_customer_cards" | "delete_customer_card" | "list_payment_methods" | "calculate_installments" | "get_account_info" | "charge_saved_card" | "create_qr_payment" | "cancel_qr_payment";
 /**
- * Build a tool set for the Vercel AI SDK that exposes Mercado Pago Subscriptions
- * to an agent. Pass directly to `Experimental_Agent`'s `tools` option, or merge
- * with other tool sets.
+ * Build a tool set for the Vercel AI SDK that exposes Mercado Pago to an
+ * agent. Pass directly to `Experimental_Agent`'s `tools` option, or merge with
+ * other tool sets.
  *
  * @example
  * ```ts
@@ -400,4 +954,4 @@ declare function verifyWebhookSignature(params: {
     secret: string;
 }): boolean;
 
-export { type AutoRecurring, type CreatePreapprovalParams, type CurrencyId, type FrequencyType, InMemoryStateAdapter, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, type MercadoPagoToolsOptions, type ParsedWebhookEvent, type Preapproval, type PreapprovalStatus, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };
+export { type AccountInfo, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreatePaymentParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CurrencyId, type Customer, type CustomerCard, type FrequencyType, InMemoryStateAdapter, type InstallmentOffer, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };