@ar-agents/mercadopago 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -217,6 +217,347 @@ 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 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. */
@@ -233,9 +574,11 @@ interface MercadoPagoClientOptions {
     fetch?: typeof fetch;
 }
 /**
- * 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;
@@ -249,28 +592,98 @@ 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>;
 }
 
 /**
@@ -333,12 +746,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";
 /**
- * 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 +818,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 CreateCustomerParams, type CreatePaymentParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateRefundParams, type CurrencyId, type Customer, type CustomerCard, type FrequencyType, InMemoryStateAdapter, type InstallmentOffer, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, type MercadoPagoToolsOptions, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type Refund, type SearchPaymentsParams, type SiteId, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, classifyError, mercadoPagoTools, parseWebhookEvent, verifyWebhookSignature };