@ar-agents/mercadopago 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -951,6 +951,72 @@ interface MarketplaceParams {
      */
     application_fee?: number;
 }
+/**
+ * Account balance snapshot. Sum of `available + unavailable` is the seller's
+ * total Mercado Pago balance.
+ *
+ * - `available` — funds the seller can withdraw or pay with right now.
+ * - `unavailable` — funds in retention (typically 14-21 days for new sellers
+ *   or for risk-flagged transactions). Becomes `available` automatically.
+ */
+declare const AccountBalanceSchema: z.ZodObject<{
+    user_id: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>>;
+    available_balance: z.ZodNumber;
+    unavailable_balance: z.ZodNumber;
+    total_amount: z.ZodNumber;
+    currency_id: z.ZodDefault<z.ZodString>;
+}, z.core.$loose>;
+type AccountBalance = z.infer<typeof AccountBalanceSchema>;
+/**
+ * Account movement (a single line in the seller's MP "movements" log).
+ * Includes incoming payments, outgoing transfers, refunds, holdings, etc.
+ */
+declare const AccountMovementSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    amount: z.ZodNumber;
+    currency_id: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    date_released: z.ZodOptional<z.ZodString>;
+    reference_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    payment_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$loose>;
+type AccountMovement = z.infer<typeof AccountMovementSchema>;
+/**
+ * A scheduled or completed transfer from the MP account to the seller's
+ * registered bank account (CBU). Settlements are the core of "when do I
+ * actually get paid".
+ */
+declare const SettlementSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    currency_id: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    date_scheduled: z.ZodOptional<z.ZodString>;
+    date_processed: z.ZodOptional<z.ZodString>;
+    bank_account: z.ZodOptional<z.ZodObject<{
+        cbu: z.ZodOptional<z.ZodString>;
+        bank_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type Settlement = z.infer<typeof SettlementSchema>;
+type ThreeDSStatus = "not_required" | "frictionless" | "challenge_required" | "rejected" | "unknown";
+interface ThreeDSInfo {
+    /** High-level status — the field most agents care about. */
+    status: ThreeDSStatus;
+    /** Raw `three_d_secure_mode` field from the payment, if present. */
+    mode: string | null;
+    /**
+     * URL the buyer must visit to complete the 3DS challenge, if one was
+     * triggered. `null` for frictionless/not_required.
+     */
+    challengeUrl: string | null;
+    /** Human-readable explanation suitable for surfacing to the user. */
+    description: string;
+}
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -1284,6 +1350,54 @@ declare class MercadoPagoClient {
      * For orders that have already been captured, use `createRefund` instead.
      */
     cancelOrder(id: string): Promise<Order>;
+    /**
+     * Get the seller's current MP wallet balance (available + unavailable).
+     * - `available_balance`: spendable / withdrawable right now.
+     * - `unavailable_balance`: in retention (e.g., 14-21 days for new sellers).
+     * - `total_amount` = sum of both.
+     */
+    getAccountBalance(): Promise<AccountBalance>;
+    /**
+     * List wallet movements (incoming payments, transfers, refunds, holdings).
+     * Defaults to most-recent-first, paginated. Filter by date range with
+     * `from`/`to` (ISO 8601).
+     */
+    listAccountMovements(params?: {
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        movements: AccountMovement[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * List settlements (transfers from MP wallet to your bank account).
+     * Useful for monthly conciliation reports.
+     */
+    listSettlements(params?: {
+        from?: string;
+        to?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        settlements: Settlement[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * Get a single settlement by id. Returns the full Settlement object
+     * including bank_account info (CBU, bank name).
+     */
+    getSettlement(id: string): Promise<Settlement>;
 }
 
 /**
@@ -1370,7 +1484,7 @@ interface MercadoPagoToolsOptions {
         clientSecret: string;
     };
 }
-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" | "create_subscription_plan" | "list_subscription_plans" | "update_subscription_plan" | "subscribe_to_plan" | "list_subscription_payments" | "create_store" | "list_stores" | "create_pos" | "list_pos" | "list_payment_disputes" | "get_dispute" | "list_identification_types" | "list_issuers" | "list_webhooks" | "create_webhook" | "update_webhook" | "delete_webhook" | "handle_webhook" | "oauth_authorize_url" | "oauth_exchange_code" | "oauth_refresh_token" | "create_order" | "get_order" | "update_order" | "capture_order" | "cancel_order";
+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" | "create_subscription_plan" | "list_subscription_plans" | "update_subscription_plan" | "subscribe_to_plan" | "list_subscription_payments" | "create_store" | "list_stores" | "create_pos" | "list_pos" | "list_payment_disputes" | "get_dispute" | "list_identification_types" | "list_issuers" | "list_webhooks" | "create_webhook" | "update_webhook" | "delete_webhook" | "handle_webhook" | "oauth_authorize_url" | "oauth_exchange_code" | "oauth_refresh_token" | "create_order" | "get_order" | "update_order" | "capture_order" | "cancel_order" | "get_account_balance" | "list_account_movements" | "list_settlements" | "get_settlement" | "analyze_payment_3ds" | "get_test_cards";
 /**
  * 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
@@ -1548,4 +1662,131 @@ declare function expirationTimeMs(issuedAtMs: number, expiresInSeconds: number |
  */
 declare function isExpiringSoon(expirationMs: number, skewSeconds?: number): boolean;
 
-export { type AccountInfo, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, type CreatePosParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CreateStoreParams, type CreateSubscriptionPlanParams, type CreateWebhookParams, type CurrencyId, type Customer, type CustomerCard, type Dispute, type FrequencyType, type IdentificationType, InMemoryStateAdapter, type InstallmentOffer, type Issuer, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Pos, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, type WebhookConfig, type WebhookTopic, buildAuthorizeUrl, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+/**
+ * MP sandbox test cards for AR (MLA) — the official numbers MP publishes for
+ * its TEST environment. Use these in unit tests + integration tests to
+ * exercise the create_payment / charge_saved_card flows without touching a
+ * real card.
+ *
+ * # When this matters
+ *
+ * Most non-trivial dev flows hit the issue of "I want to test approved /
+ * rejected / pending paths" but MP's docs scatter the test card numbers
+ * across multiple pages. This module collects them so you can `import { TEST_CARDS_AR }`
+ * and pick the scenario you need.
+ *
+ * # Source
+ *
+ * AR (MLA) test cards published at
+ * https://www.mercadopago.com.ar/developers/es/docs/checkout-api/additional-content/test-cards
+ *
+ * Last sync: 2026-05.
+ */
+/**
+ * The full data needed to test a payment:
+ * - `number` — 16 digits
+ * - `cvv` — 3 digits
+ * - `exp` — MM/YY (use any future date in TEST mode)
+ * - `paymentMethodId` — what to pass as `payment_method_id` to create_payment
+ * - `holderName` — special string that triggers the desired status
+ *   (e.g. "APRO" → approved, "OTHE" → rejected with bad CVV)
+ */
+interface TestCard {
+    brand: string;
+    number: string;
+    cvv: string;
+    exp: string;
+    paymentMethodId: string;
+    /**
+     * Holder-name "magic strings" — MP routes the payment to a specific
+     * status_detail based on this:
+     * - `APRO` → status: approved
+     * - `OTHE` → rejected (status_detail: cc_rejected_other_reason)
+     * - `CONT` → pending (status_detail: pending_contingency)
+     * - `CALL` → rejected (status_detail: cc_rejected_call_for_authorize)
+     * - `FUND` → rejected (status_detail: cc_rejected_insufficient_amount)
+     * - `SECU` → rejected (status_detail: cc_rejected_bad_filled_security_code)
+     * - `EXPI` → rejected (status_detail: cc_rejected_bad_filled_date)
+     * - `FORM` → rejected (status_detail: cc_rejected_bad_filled_other)
+     */
+    holderNameToTest: Record<string, string>;
+}
+/**
+ * The MP-published test cards for AR. Pass `holderName: "APRO"` for an
+ * approved payment, `"OTHE"` for a rejected one, etc.
+ */
+declare const TEST_CARDS_AR: Record<string, TestCard>;
+/**
+ * Pre-built payer objects that MP recognizes as test buyers. Pair with
+ * an APRO test card → status: approved.
+ *
+ * **Use a NEW email per call** if you don't want MP's idempotency-on-email
+ * to dedupe — append a timestamp.
+ */
+declare const TEST_PAYERS_AR: {
+    readonly approvedBuyer: () => {
+        email: string;
+        identification: {
+            type: string;
+            number: string;
+        };
+    };
+};
+/**
+ * Resolve a `(card, scenario)` pair to a ready-to-use `CreatePaymentParams`-like
+ * object. Reduces boilerplate in test files.
+ *
+ * @example
+ * ```ts
+ * const card = buildTestCardScenario("VISA_CREDIT", "APRO", 1500);
+ * await client.createPayment({ ...card, externalReference: "test-1" });
+ * ```
+ */
+declare function buildTestCardScenario(cardKey: keyof typeof TEST_CARDS_AR, scenario: string, amountArs: number): {
+    transactionAmount: number;
+    paymentMethodId: string;
+    payerEmail: string;
+    description: string;
+    installments: number;
+    /**
+     * Magic holder name — pass to MP frontend's CardForm `cardholderName`
+     * field. (For server-side create_payment, pass via additional_info.)
+     */
+    holderName: string;
+};
+
+/**
+ * 3DS (Strong Customer Authentication) analyzer for Mercado Pago Payments.
+ *
+ * # Background
+ *
+ * 3DS (3-D Secure / "verified by Visa", "Mastercard SecureCode") is the
+ * issuer-side 2FA layer for card payments. MP triggers it automatically when:
+ * - The card's issuer requires it (driven by MCC + amount + risk).
+ * - The buyer's country mandates it (MX, BR, several EU countries).
+ *
+ * In Argentina (MLA), 3DS is OPTIONAL but strongly recommended for
+ * high-value transactions and is required for some FCE MiPyMEs flows.
+ *
+ * # What this module does
+ *
+ * Given a `Payment` returned by `getPayment()` or `createPayment()`, derive
+ * a normalized `ThreeDSInfo` telling you:
+ * - Whether 3DS was triggered at all
+ * - Whether it was frictionless (no buyer interaction) or required a challenge
+ * - The challenge URL (if any) you must redirect the buyer to
+ * - A human-readable description suitable for surfacing to the user
+ *
+ * # When to use
+ *
+ * Call `analyze3DS(payment)` after EVERY `createPayment()` for credit cards.
+ * If `info.challengeUrl !== null`, you MUST redirect the buyer there before
+ * the payment can complete — otherwise it stays in `pending` forever.
+ */
+
+/**
+ * Analyze a Payment's 3DS state. Pure function, no I/O.
+ */
+declare function analyze3DS(payment: Payment): ThreeDSInfo;
+
+export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, type CreatePosParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CreateStoreParams, type CreateSubscriptionPlanParams, type CreateWebhookParams, type CurrencyId, type Customer, type CustomerCard, type Dispute, type FrequencyType, type IdentificationType, InMemoryStateAdapter, type InstallmentOffer, type Issuer, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Pos, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type Settlement, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, type SubscriptionStateAdapter, type SubscriptionStateRecord, TEST_CARDS_AR, TEST_PAYERS_AR, type TestCard, type ThreeDSInfo, type ThreeDSStatus, type WebhookBody, type WebhookConfig, type WebhookTopic, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };

package/dist/index.d.ts

@@ -951,6 +951,72 @@ interface MarketplaceParams {
      */
     application_fee?: number;
 }
+/**
+ * Account balance snapshot. Sum of `available + unavailable` is the seller's
+ * total Mercado Pago balance.
+ *
+ * - `available` — funds the seller can withdraw or pay with right now.
+ * - `unavailable` — funds in retention (typically 14-21 days for new sellers
+ *   or for risk-flagged transactions). Becomes `available` automatically.
+ */
+declare const AccountBalanceSchema: z.ZodObject<{
+    user_id: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>>;
+    available_balance: z.ZodNumber;
+    unavailable_balance: z.ZodNumber;
+    total_amount: z.ZodNumber;
+    currency_id: z.ZodDefault<z.ZodString>;
+}, z.core.$loose>;
+type AccountBalance = z.infer<typeof AccountBalanceSchema>;
+/**
+ * Account movement (a single line in the seller's MP "movements" log).
+ * Includes incoming payments, outgoing transfers, refunds, holdings, etc.
+ */
+declare const AccountMovementSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    amount: z.ZodNumber;
+    currency_id: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    date_released: z.ZodOptional<z.ZodString>;
+    reference_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    payment_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$loose>;
+type AccountMovement = z.infer<typeof AccountMovementSchema>;
+/**
+ * A scheduled or completed transfer from the MP account to the seller's
+ * registered bank account (CBU). Settlements are the core of "when do I
+ * actually get paid".
+ */
+declare const SettlementSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodNumber>;
+    currency_id: z.ZodOptional<z.ZodString>;
+    date_created: z.ZodOptional<z.ZodString>;
+    date_scheduled: z.ZodOptional<z.ZodString>;
+    date_processed: z.ZodOptional<z.ZodString>;
+    bank_account: z.ZodOptional<z.ZodObject<{
+        cbu: z.ZodOptional<z.ZodString>;
+        bank_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type Settlement = z.infer<typeof SettlementSchema>;
+type ThreeDSStatus = "not_required" | "frictionless" | "challenge_required" | "rejected" | "unknown";
+interface ThreeDSInfo {
+    /** High-level status — the field most agents care about. */
+    status: ThreeDSStatus;
+    /** Raw `three_d_secure_mode` field from the payment, if present. */
+    mode: string | null;
+    /**
+     * URL the buyer must visit to complete the 3DS challenge, if one was
+     * triggered. `null` for frictionless/not_required.
+     */
+    challengeUrl: string | null;
+    /** Human-readable explanation suitable for surfacing to the user. */
+    description: string;
+}
 
 interface MercadoPagoClientOptions {
     /** Access token. TEST- prefix for sandbox, APP_USR- for production. */
@@ -1284,6 +1350,54 @@ declare class MercadoPagoClient {
      * For orders that have already been captured, use `createRefund` instead.
      */
     cancelOrder(id: string): Promise<Order>;
+    /**
+     * Get the seller's current MP wallet balance (available + unavailable).
+     * - `available_balance`: spendable / withdrawable right now.
+     * - `unavailable_balance`: in retention (e.g., 14-21 days for new sellers).
+     * - `total_amount` = sum of both.
+     */
+    getAccountBalance(): Promise<AccountBalance>;
+    /**
+     * List wallet movements (incoming payments, transfers, refunds, holdings).
+     * Defaults to most-recent-first, paginated. Filter by date range with
+     * `from`/`to` (ISO 8601).
+     */
+    listAccountMovements(params?: {
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        movements: AccountMovement[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * List settlements (transfers from MP wallet to your bank account).
+     * Useful for monthly conciliation reports.
+     */
+    listSettlements(params?: {
+        from?: string;
+        to?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        settlements: Settlement[];
+        paging: {
+            limit: number;
+            offset: number;
+            total: number;
+        };
+    }>;
+    /**
+     * Get a single settlement by id. Returns the full Settlement object
+     * including bank_account info (CBU, bank name).
+     */
+    getSettlement(id: string): Promise<Settlement>;
 }
 
 /**
@@ -1370,7 +1484,7 @@ interface MercadoPagoToolsOptions {
         clientSecret: string;
     };
 }
-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" | "create_subscription_plan" | "list_subscription_plans" | "update_subscription_plan" | "subscribe_to_plan" | "list_subscription_payments" | "create_store" | "list_stores" | "create_pos" | "list_pos" | "list_payment_disputes" | "get_dispute" | "list_identification_types" | "list_issuers" | "list_webhooks" | "create_webhook" | "update_webhook" | "delete_webhook" | "handle_webhook" | "oauth_authorize_url" | "oauth_exchange_code" | "oauth_refresh_token" | "create_order" | "get_order" | "update_order" | "capture_order" | "cancel_order";
+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" | "create_subscription_plan" | "list_subscription_plans" | "update_subscription_plan" | "subscribe_to_plan" | "list_subscription_payments" | "create_store" | "list_stores" | "create_pos" | "list_pos" | "list_payment_disputes" | "get_dispute" | "list_identification_types" | "list_issuers" | "list_webhooks" | "create_webhook" | "update_webhook" | "delete_webhook" | "handle_webhook" | "oauth_authorize_url" | "oauth_exchange_code" | "oauth_refresh_token" | "create_order" | "get_order" | "update_order" | "capture_order" | "cancel_order" | "get_account_balance" | "list_account_movements" | "list_settlements" | "get_settlement" | "analyze_payment_3ds" | "get_test_cards";
 /**
  * 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
@@ -1548,4 +1662,131 @@ declare function expirationTimeMs(issuedAtMs: number, expiresInSeconds: number |
  */
 declare function isExpiringSoon(expirationMs: number, skewSeconds?: number): boolean;
 
-export { type AccountInfo, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, type CreatePosParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CreateStoreParams, type CreateSubscriptionPlanParams, type CreateWebhookParams, type CurrencyId, type Customer, type CustomerCard, type Dispute, type FrequencyType, type IdentificationType, InMemoryStateAdapter, type InstallmentOffer, type Issuer, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Pos, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, type SubscriptionStateAdapter, type SubscriptionStateRecord, type WebhookBody, type WebhookConfig, type WebhookTopic, buildAuthorizeUrl, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+/**
+ * MP sandbox test cards for AR (MLA) — the official numbers MP publishes for
+ * its TEST environment. Use these in unit tests + integration tests to
+ * exercise the create_payment / charge_saved_card flows without touching a
+ * real card.
+ *
+ * # When this matters
+ *
+ * Most non-trivial dev flows hit the issue of "I want to test approved /
+ * rejected / pending paths" but MP's docs scatter the test card numbers
+ * across multiple pages. This module collects them so you can `import { TEST_CARDS_AR }`
+ * and pick the scenario you need.
+ *
+ * # Source
+ *
+ * AR (MLA) test cards published at
+ * https://www.mercadopago.com.ar/developers/es/docs/checkout-api/additional-content/test-cards
+ *
+ * Last sync: 2026-05.
+ */
+/**
+ * The full data needed to test a payment:
+ * - `number` — 16 digits
+ * - `cvv` — 3 digits
+ * - `exp` — MM/YY (use any future date in TEST mode)
+ * - `paymentMethodId` — what to pass as `payment_method_id` to create_payment
+ * - `holderName` — special string that triggers the desired status
+ *   (e.g. "APRO" → approved, "OTHE" → rejected with bad CVV)
+ */
+interface TestCard {
+    brand: string;
+    number: string;
+    cvv: string;
+    exp: string;
+    paymentMethodId: string;
+    /**
+     * Holder-name "magic strings" — MP routes the payment to a specific
+     * status_detail based on this:
+     * - `APRO` → status: approved
+     * - `OTHE` → rejected (status_detail: cc_rejected_other_reason)
+     * - `CONT` → pending (status_detail: pending_contingency)
+     * - `CALL` → rejected (status_detail: cc_rejected_call_for_authorize)
+     * - `FUND` → rejected (status_detail: cc_rejected_insufficient_amount)
+     * - `SECU` → rejected (status_detail: cc_rejected_bad_filled_security_code)
+     * - `EXPI` → rejected (status_detail: cc_rejected_bad_filled_date)
+     * - `FORM` → rejected (status_detail: cc_rejected_bad_filled_other)
+     */
+    holderNameToTest: Record<string, string>;
+}
+/**
+ * The MP-published test cards for AR. Pass `holderName: "APRO"` for an
+ * approved payment, `"OTHE"` for a rejected one, etc.
+ */
+declare const TEST_CARDS_AR: Record<string, TestCard>;
+/**
+ * Pre-built payer objects that MP recognizes as test buyers. Pair with
+ * an APRO test card → status: approved.
+ *
+ * **Use a NEW email per call** if you don't want MP's idempotency-on-email
+ * to dedupe — append a timestamp.
+ */
+declare const TEST_PAYERS_AR: {
+    readonly approvedBuyer: () => {
+        email: string;
+        identification: {
+            type: string;
+            number: string;
+        };
+    };
+};
+/**
+ * Resolve a `(card, scenario)` pair to a ready-to-use `CreatePaymentParams`-like
+ * object. Reduces boilerplate in test files.
+ *
+ * @example
+ * ```ts
+ * const card = buildTestCardScenario("VISA_CREDIT", "APRO", 1500);
+ * await client.createPayment({ ...card, externalReference: "test-1" });
+ * ```
+ */
+declare function buildTestCardScenario(cardKey: keyof typeof TEST_CARDS_AR, scenario: string, amountArs: number): {
+    transactionAmount: number;
+    paymentMethodId: string;
+    payerEmail: string;
+    description: string;
+    installments: number;
+    /**
+     * Magic holder name — pass to MP frontend's CardForm `cardholderName`
+     * field. (For server-side create_payment, pass via additional_info.)
+     */
+    holderName: string;
+};
+
+/**
+ * 3DS (Strong Customer Authentication) analyzer for Mercado Pago Payments.
+ *
+ * # Background
+ *
+ * 3DS (3-D Secure / "verified by Visa", "Mastercard SecureCode") is the
+ * issuer-side 2FA layer for card payments. MP triggers it automatically when:
+ * - The card's issuer requires it (driven by MCC + amount + risk).
+ * - The buyer's country mandates it (MX, BR, several EU countries).
+ *
+ * In Argentina (MLA), 3DS is OPTIONAL but strongly recommended for
+ * high-value transactions and is required for some FCE MiPyMEs flows.
+ *
+ * # What this module does
+ *
+ * Given a `Payment` returned by `getPayment()` or `createPayment()`, derive
+ * a normalized `ThreeDSInfo` telling you:
+ * - Whether 3DS was triggered at all
+ * - Whether it was frictionless (no buyer interaction) or required a challenge
+ * - The challenge URL (if any) you must redirect the buyer to
+ * - A human-readable description suitable for surfacing to the user
+ *
+ * # When to use
+ *
+ * Call `analyze3DS(payment)` after EVERY `createPayment()` for credit cards.
+ * If `info.challengeUrl !== null`, you MUST redirect the buyer there before
+ * the payment can complete — otherwise it stays in `pending` forever.
+ */
+
+/**
+ * Analyze a Payment's 3DS state. Pure function, no I/O.
+ */
+declare function analyze3DS(payment: Payment): ThreeDSInfo;
+
+export { type AccountBalance, type AccountInfo, type AccountMovement, type AutoRecurring, type CardToken, type CreateCardTokenParams, type CreateCustomerParams, type CreateOrderParams, type CreatePaymentParams, type CreatePosParams, type CreatePreapprovalParams, type CreatePreferenceParams, type CreateQrPaymentParams, type CreateRefundParams, type CreateStoreParams, type CreateSubscriptionPlanParams, type CreateWebhookParams, type CurrencyId, type Customer, type CustomerCard, type Dispute, type FrequencyType, type IdentificationType, InMemoryStateAdapter, type InstallmentOffer, type Issuer, type MarketplaceParams, MercadoPagoAccountTypeMismatchError, MercadoPagoAuthError, MercadoPagoAuthorizeForbiddenError, MercadoPagoBackUrlInvalidError, MercadoPagoClient, type MercadoPagoClientOptions, MercadoPagoError, MercadoPagoOverloadedError, MercadoPagoPaymentRejectedError, MercadoPagoRateLimitError, MercadoPagoSelfPaymentError, MercadoPagoTimeoutError, type MercadoPagoToolsOptions, type OAuthToken, type Order, type OrderItem, type OrderStatus, type ParsedWebhookEvent, type Payment, type PaymentMethod, type PaymentStatus, type PaymentsSearchResult, type Pos, type Preapproval, type PreapprovalStatus, type Preference, type PreferenceItem, type QrOrder, type Refund, type SearchPaymentsParams, type Settlement, type SiteId, type Store, type SubscriptionPayment, type SubscriptionPlan, type SubscriptionStateAdapter, type SubscriptionStateRecord, TEST_CARDS_AR, TEST_PAYERS_AR, type TestCard, type ThreeDSInfo, type ThreeDSStatus, type WebhookBody, type WebhookConfig, type WebhookTopic, analyze3DS, buildAuthorizeUrl, buildTestCardScenario, classifyError, exchangeCodeForToken, expirationTimeMs, isExpiringSoon, mercadoPagoTools, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };