@alipay/ams-checkout 2.0.27 → 2.0.28

package/esm/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.0"
+      "packageVersion": "7.59.1"
     }
   ]
 }

package/esm/util/logger.js

@@ -296,6 +296,6 @@ export var LogConfig = {
   version: 'iteration/20231021',
   mdata: {
     firstLogTime: Date.now(),
-    sdkVersion: "2.0.27"
+    sdkVersion: "2.0.28"
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alipay/ams-checkout",
-  "version": "2.0.27",
+  "version": "2.0.28",
   "description": "",
   "author": "",
   "exports": {

package/types.d.ts

@@ -221,7 +221,7 @@ export declare class AntomSDK extends BaseElementsFactory {
     elements(): Elements;
     createElement(elementType: 'payment', options?: PaymentAppConfig): PaymentElement;
     createElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
-    createElement(elementType: 'CVV', options?: CVVAppConfig): CVVElement;
+    createElement(elementType: 'CVV', options: CVVAppConfig): CVVElement;
     createElement(elementType: 'express', options?: ExpressAppConfig): ExpressElement;
     getElement(elementType: 'payment', options?: PaymentAppConfig): PaymentElement;
     getElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
@@ -293,9 +293,29 @@ export declare const AntomSDKErrorCodes: {
      */
     readonly AMOUNT_VALUE_EMPTY: "AMOUNT_VALUE_EMPTY";
     /**
-     * @description 金额格式非法（仅允许整数和小数）
+     * @description 金额格式非法（仅允许 ASCII 数字字符串）
      */
     readonly AMOUNT_VALUE_INVALID: "AMOUNT_VALUE_INVALID";
+    /**
+     * @description Amount currency does not match the payment session currency
+     */
+    readonly AMOUNT_CURRENCY_MISMATCH: "AMOUNT_CURRENCY_MISMATCH";
+    /**
+     * @description Amount currency is not supported
+     */
+    readonly AMOUNT_CURRENCY_UNSUPPORTED: "AMOUNT_CURRENCY_UNSUPPORTED";
+    /**
+     * @description Amount currency precision is not supported
+     */
+    readonly AMOUNT_PRECISION_UNSUPPORTED: "AMOUNT_PRECISION_UNSUPPORTED";
+    /**
+     * @description Amount conversion timed out
+     */
+    readonly AMOUNT_RESOLVE_TIMEOUT: "AMOUNT_RESOLVE_TIMEOUT";
+    /**
+     * @description Amount conversion failed
+     */
+    readonly AMOUNT_RESOLVE_FAILED: "AMOUNT_RESOLVE_FAILED";
     readonly GENERATE_ELEMENT_KEY_FAILED: "GENERATE_ELEMENT_KEY_FAILED";
     readonly ELEMENT_INIT_FAILED: "ELEMENT_INIT_FAILED";
     readonly MOUNT_TIMEOUT: "MOUNT_TIMEOUT";
@@ -308,8 +328,8 @@ export declare const AntomSDKErrorCodes: {
     readonly ELEMENT_DEFINE_ERROR: "ELEMENT_DEFINE_ERROR";
     readonly ELEMENT_ALREADY_REGISTERED: "ELEMENT_ALREADY_REGISTERED";
     readonly CANNOT_CREATE_SAME_ELEMENT_TWICE: "CANNOT_CREATE_SAME_ELEMENT_TWICE";
-    readonly GROUPS_ONLY_ONE_MAIN_ELEMENT: "GROUPS_ONLY_ONE_MAIN_ELEMENT";
-    readonly GROUPS_NOT_FOUND_MAIN_ELEMENT: "GROUPS_NOT_FOUND_MAIN_ELEMENT";
+    readonly GROUPS_ONLY_ONE_MAIN_ELEMENT: "GROUPS_ONLY_ONE_MAIN_ELEMENT"; /** @deprecated 传入 elements 时无需重复传递，且不会覆盖 Element 的会话。 */
+    readonly GROUPS_NOT_FOUND_MAIN_ELEMENT: "GROUPS_NOT_FOUND_MAIN_ELEMENT"; /** 无 UI 模式必填，仅用于创建内部 CVVElement。 */
     readonly NOT_SUPPORT_ELEMENT: "NOT_SUPPORT_ELEMENT";
     readonly NOT_SUPPORT_SUBMIT: "NOT_SUPPORT_SUBMIT";
     readonly UPDATE_CONFIG_TIMEOUT: "UPDATE_CONFIG_TIMEOUT";
@@ -2129,18 +2149,22 @@ export declare interface ConfirmCardSetupOptions {
     redirect?: 'always' | 'if_required';
 }
 
-export declare interface ConfirmPaymentOptions extends Omit<ConfirmCardSetupOptions, 'elements'>, PaymentSubmitParams {
-    sessionData: string;
-    /**
-     * @description 传入已挂载的 CVVElement / PaymentElement / Elements 实例，不传则使用无 UI 自动提交模式
-     */
-    elements?: BaseMainElement | BaseElements;
+export declare type ConfirmPaymentOptions = PaymentSubmitParams & {
     appearance?: CVVAppearance;
     /**
      * @description 集成用户自定义信息（如 cardHolderName）
      */
     params?: Record<string, unknown>;
-}
+} & ({
+    /** 已挂载的 Element；确认时使用其创建时绑定的会话。 */
+    elements: BaseMainElement | BaseElements;
+    /** @deprecated 传入 elements 时无需重复传递，且不会覆盖 Element 的会话。 */
+    sessionData?: string;
+} | {
+    elements?: undefined;
+    /** 无 UI 模式必填，仅用于创建内部 CVVElement。 */
+    sessionData: string;
+});
 
 /**
  * @description Connect流程参数
@@ -2281,9 +2305,9 @@ export declare interface CVVAppConfig extends BaseElementAppConfig {
     /** CVV appearance configuration including optional alias-only Rules. */
     appearance?: CVVAppearance;
     /**
-     * @description sessionData
+     * @description 创建时必填的支付会话；不可通过 updateConfig 或 submit 替换
      */
-    sessionData?: string;
+    sessionData: string;
     /* Excluded from this release type: paymentSessionConfig */
     /* Excluded from this release type: renderData */
     /* Excluded from this release type: sdkVersion */
@@ -2309,14 +2333,10 @@ export declare type CVVAppearanceProps = {
  */
 export declare class CVVElement extends BaseMainElement<CVVElementConfig, CVVElementEvents> {
     static elementType: string;
+    private readonly sessionData;
     constructor(name: string, config: CVVElementConfig);
     /* Excluded from this release type: setup */
-    /**
-     * Updates CVV configuration while preserving the public Rules clear semantics.
-     * @param newConfig Partial CVV configuration patch.
-     * @returns The WebApp update acknowledgement.
-     */
-    updateConfig(newConfig: Partial<CVVAppConfig>): Promise<CVVElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    /* Excluded from this release type: updateConfig */
     /* Excluded from this release type: submit */
     protected focus(): void;
     protected blur(): void;
@@ -2328,20 +2348,10 @@ export declare class CVVElement extends BaseMainElement<CVVElementConfig, CVVEle
  * @description CVV element config type
  */
 export declare interface CVVElementConfig extends BaseElementConfig<CVVAppConfig> {
+    appConfig: CVVAppConfig;
 }
 
-export declare interface CVVElementEvents extends AntomBridgeEventMap<CVVAppConfig, CVVSubmitParams> {
-    /**
-     * @description Emitted event about form
-     */
-    form: {
-        errors?: Array<{
-            field: string | number;
-            message: string;
-            currentValue: any;
-        }>;
-        message: string;
-    };
+export declare interface CVVElementEvents extends AntomBridgeEventMap<CVVAppConfig, CVVSubmitParams & Pick<CVVAppConfig, 'sessionData'>> {
     /**
      * @description Emitted when the element is destroy
      */
@@ -2385,10 +2395,6 @@ export declare type CVVSubmitErrorCodes = 'NOT_FIND_MAINELEMENT' | 'SESSION_DATA
  * @description CVV 支付提交参数
  */
 export declare interface CVVSubmitParams {
-    /**
-     * 支付会话数据
-     */
-    sessionData?: string;
     /**
      * 重定向策略
      */
@@ -3209,12 +3215,13 @@ export declare interface ExpressAppConfig extends BaseElementAppConfig {
     /**
      * Amount & Currency
      *
-     * Only effective via `updateConfig({ amount })` at runtime.
-     * Passing amount at creation time is ignored; the initial amount
-     * comes from the server-side sdkQuery result (renderData.paymentAmount).
+     * For Apple Pay and Google Pay, `value` is a positive ASCII digit string in
+     * the payment session currency's minor unit; `currency` may be omitted.
+     * For example, USD 10.99 is passed as `{ value: '1099' }`.
+     * PayPal keeps its existing major-unit amount semantics and requires `currency`.
      */
     amount?: {
-        currency: string;
+        currency?: string;
         value: string;
     };
     /** PayPal 配置 */
@@ -3345,7 +3352,17 @@ export declare class ExpressElement extends BaseMainElement<ExpressElementConfig
     private _localHandlers;
     /** 支付流程进行中标志（click → confirm/error/cancel 之间） */
     private _paymentInProgress;
+    /**
+     * 是否已收到 iframe 业务层 ready 事件（app.tsx sendReady）。
+     * 注意：与 host `status='ready'`（由 HANDSHAKE_ACK 触发，bridge.js:450 同步回发，与 amount 解析无关）不同。
+     * 首屏 amount setupError 时 iframe 不发业务 ready → _readyReceived 保持 false，
+     * 据此判别"首屏失败"以阻断后续 updateConfig。
+     */
+    private _readyReceived;
+    /** 首屏 setupError 致命标志：置位后 updateConfig 被 CHECKOUT_NOT_READY 阻断，只能 destroy 重开。 */
+    private _setupFailed;
     private _paypalOverlay;
+    private _updateQueue;
     constructor(name: string, config: ExpressElementConfig);
     /**
      * 重写 on：对 confirm 事件拦截，在商户回调执行前注入 paymentFailed()
@@ -3357,6 +3374,16 @@ export declare class ExpressElement extends BaseMainElement<ExpressElementConfig
      */
     private _emit;
     updateConfig(newConfig: ExpressAppConfig): Promise<ExpressElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    private updateConfigTransaction;
+    private updateAmountConfigWithSanitizedDebug;
+    private getAmountValidationReason;
+    /** iframe 业务 ready 事件到达：置 _readyReceived，后续运行时 error 不再视为首屏失败。
+     *  ready 是"本次首屏成功"的确实信号（首屏 setupError 时 iframe 不发 ready），
+     *  故同时清掉 _setupFailed——unmount+remount 同实例二次首屏成功后可恢复 updateConfig。
+     */
+    private _handleReady;
+    /** iframe error 事件：若 business ready 未到达，视为首屏 setupError → 置 _setupFailed 阻断后续 updateConfig。 */
+    private _handleError;
     /**
      * 商户在 confirm 回调内调用，触发实际支付提交。
      * iframe 收到 OPENSDK@COMPLETE_PAYMENT 后执行 submitPay / polling 等，
@@ -3446,6 +3473,11 @@ export declare interface ExpressElementEvents extends AntomBridgeWithNativeEvent
     'OPENSDK@GET_APPLE_PAY_TOKEN': {
         requestId: string;
         expressPaymentType: string;
+        /** iframe 已转好的 major unit 金额（来自 resolvedAmount）；host 委托 Apple Pay 消费，不再做 minor→major 转换。 */
+        walletAmount?: {
+            value: string;
+            currency: string;
+        };
     };
     /** host 完成 Apple Pay token 获取后回包给 iframe，submit/3DS/polling 均由 webapp 完成 */
     'OPENSDK@GET_APPLE_PAY_TOKEN_REPLY': {
@@ -3556,6 +3588,57 @@ declare interface FrontSupportIppBank {
     logo?: Logo;
 }
 
+/** host 回传 webapp 的 OPENSDK@GET_APPLE_PAY_TOKEN_REPLY 形态(result 对齐老链路 {token,billingContact,shippingContact})。 */
+declare interface GetApplePayTokenReply {
+    success: boolean;
+    result?: {
+        token?: unknown;
+        billingContact?: unknown;
+        shippingContact?: unknown;
+    } | {
+        errorCode: string;
+    };
+}
+
+/** webapp 传来的 OPENSDK@GET_APPLE_PAY_TOKEN payload 形态。 */
+declare interface GetApplePayTokenRequest {
+    paymentMethod?: {
+        paymentMethodDetail?: {
+            applePayProps?: {
+                paymentRequest?: unknown;
+            };
+        };
+    };
+    shipping?: unknown;
+}
+
+/** host 回传 webapp 的 OPENSDK@GET_GOOGLE_PAY_TOKEN_REPLY 形态。 */
+declare interface GetGooglePayTokenReply {
+    success: boolean;
+    result?: unknown;
+    err?: {
+        statusCode?: string;
+        [key: string]: unknown;
+    };
+}
+
+/** webapp 传来的 OPENSDK@GET_GOOGLE_PAY_TOKEN payload 形态。 */
+declare interface GetGooglePayTokenRequest {
+    actionName?: string;
+    data?: {
+        environment?: string;
+        paymentRequest?: unknown;
+        paymentMethod?: unknown;
+        paymentMethodDetail?: {
+            googlePayProps?: {
+                environment?: string;
+                paymentRequest?: unknown;
+            };
+        };
+        [key: string]: unknown;
+    };
+}
+
 declare type GetI18nQueryParam = string | {
     /**
      * 多语言文案的 key
@@ -7095,6 +7178,7 @@ export declare type PaymentAppearanceProps = {
 export declare class PaymentElement extends BaseMainElement<PaymentElementConfig, PaymentElementEvents> {
     static elementType: string;
     private _paymentInProgress;
+    private readonly walletLogger;
     constructor(name: string, config: PaymentElementConfig);
     /* Excluded from this release type: setup */
     /**
@@ -7117,6 +7201,20 @@ declare interface PaymentElementConfig extends BaseElementConfig<PaymentAppConfi
  * @description Payment element events
  */
 export declare interface PaymentElementEvents extends AntomBridgeWithNativeEventMap<PaymentAppConfig, PaymentSubmitParams, PaymentSubmitResult> {
+    /**
+     * webapp 委托 host(父 frame)拉起 Apple Pay 拿 token。
+     * payload 结构对齐 ModernElementController.GetApplePayTokenRequest(放 paymentMethod/shipping)。
+     */
+    'OPENSDK@GET_APPLE_PAY_TOKEN': GetApplePayTokenRequest;
+    /** host 完成 Apple Pay token 获取后回包给 webapp */
+    'OPENSDK@GET_APPLE_PAY_TOKEN_REPLY': GetApplePayTokenReply;
+    /**
+     * webapp 委托 host(父 frame)拉起 Google Pay 拿 token。
+     * payload 结构对齐 ModernElementController.GetGooglePayTokenRequest(放 data.environment/paymentRequest)。
+     */
+    'OPENSDK@GET_GOOGLE_PAY_TOKEN': GetGooglePayTokenRequest;
+    /** host 完成 Google Pay token 获取后回包给 webapp */
+    'OPENSDK@GET_GOOGLE_PAY_TOKEN_REPLY': GetGooglePayTokenReply;
 }
 
 declare interface PaymentElementView {

package/types.untrimmed.d.ts

@@ -313,7 +313,7 @@ export declare class AntomSDK extends BaseElementsFactory {
     elements(): Elements;
     createElement(elementType: 'payment', options?: PaymentAppConfig): PaymentElement;
     createElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
-    createElement(elementType: 'CVV', options?: CVVAppConfig): CVVElement;
+    createElement(elementType: 'CVV', options: CVVAppConfig): CVVElement;
     createElement(elementType: 'express', options?: ExpressAppConfig): ExpressElement;
     getElement(elementType: 'payment', options?: PaymentAppConfig): PaymentElement;
     getElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
@@ -385,9 +385,29 @@ export declare const AntomSDKErrorCodes: {
      */
     readonly AMOUNT_VALUE_EMPTY: "AMOUNT_VALUE_EMPTY";
     /**
-     * @description 金额格式非法（仅允许整数和小数）
+     * @description 金额格式非法（仅允许 ASCII 数字字符串）
      */
     readonly AMOUNT_VALUE_INVALID: "AMOUNT_VALUE_INVALID";
+    /**
+     * @description Amount currency does not match the payment session currency
+     */
+    readonly AMOUNT_CURRENCY_MISMATCH: "AMOUNT_CURRENCY_MISMATCH";
+    /**
+     * @description Amount currency is not supported
+     */
+    readonly AMOUNT_CURRENCY_UNSUPPORTED: "AMOUNT_CURRENCY_UNSUPPORTED";
+    /**
+     * @description Amount currency precision is not supported
+     */
+    readonly AMOUNT_PRECISION_UNSUPPORTED: "AMOUNT_PRECISION_UNSUPPORTED";
+    /**
+     * @description Amount conversion timed out
+     */
+    readonly AMOUNT_RESOLVE_TIMEOUT: "AMOUNT_RESOLVE_TIMEOUT";
+    /**
+     * @description Amount conversion failed
+     */
+    readonly AMOUNT_RESOLVE_FAILED: "AMOUNT_RESOLVE_FAILED";
     readonly GENERATE_ELEMENT_KEY_FAILED: "GENERATE_ELEMENT_KEY_FAILED";
     readonly ELEMENT_INIT_FAILED: "ELEMENT_INIT_FAILED";
     readonly MOUNT_TIMEOUT: "MOUNT_TIMEOUT";
@@ -400,8 +420,8 @@ export declare const AntomSDKErrorCodes: {
     readonly ELEMENT_DEFINE_ERROR: "ELEMENT_DEFINE_ERROR";
     readonly ELEMENT_ALREADY_REGISTERED: "ELEMENT_ALREADY_REGISTERED";
     readonly CANNOT_CREATE_SAME_ELEMENT_TWICE: "CANNOT_CREATE_SAME_ELEMENT_TWICE";
-    readonly GROUPS_ONLY_ONE_MAIN_ELEMENT: "GROUPS_ONLY_ONE_MAIN_ELEMENT";
-    readonly GROUPS_NOT_FOUND_MAIN_ELEMENT: "GROUPS_NOT_FOUND_MAIN_ELEMENT";
+    readonly GROUPS_ONLY_ONE_MAIN_ELEMENT: "GROUPS_ONLY_ONE_MAIN_ELEMENT"; /** @deprecated 传入 elements 时无需重复传递，且不会覆盖 Element 的会话。 */
+    readonly GROUPS_NOT_FOUND_MAIN_ELEMENT: "GROUPS_NOT_FOUND_MAIN_ELEMENT"; /** 无 UI 模式必填，仅用于创建内部 CVVElement。 */
     readonly NOT_SUPPORT_ELEMENT: "NOT_SUPPORT_ELEMENT";
     readonly NOT_SUPPORT_SUBMIT: "NOT_SUPPORT_SUBMIT";
     readonly UPDATE_CONFIG_TIMEOUT: "UPDATE_CONFIG_TIMEOUT";
@@ -2524,18 +2544,22 @@ export declare interface ConfirmCardSetupOptions {
     redirect?: 'always' | 'if_required';
 }
 
-export declare interface ConfirmPaymentOptions extends Omit<ConfirmCardSetupOptions, 'elements'>, PaymentSubmitParams {
-    sessionData: string;
-    /**
-     * @description 传入已挂载的 CVVElement / PaymentElement / Elements 实例，不传则使用无 UI 自动提交模式
-     */
-    elements?: BaseMainElement | BaseElements;
+export declare type ConfirmPaymentOptions = PaymentSubmitParams & {
     appearance?: CVVAppearance;
     /**
      * @description 集成用户自定义信息（如 cardHolderName）
      */
     params?: Record<string, unknown>;
-}
+} & ({
+    /** 已挂载的 Element；确认时使用其创建时绑定的会话。 */
+    elements: BaseMainElement | BaseElements;
+    /** @deprecated 传入 elements 时无需重复传递，且不会覆盖 Element 的会话。 */
+    sessionData?: string;
+} | {
+    elements?: undefined;
+    /** 无 UI 模式必填，仅用于创建内部 CVVElement。 */
+    sessionData: string;
+});
 
 /**
  * @description Connect流程参数
@@ -2676,9 +2700,9 @@ export declare interface CVVAppConfig extends BaseElementAppConfig {
     /** CVV appearance configuration including optional alias-only Rules. */
     appearance?: CVVAppearance;
     /**
-     * @description sessionData
+     * @description 创建时必填的支付会话；不可通过 updateConfig 或 submit 替换
      */
-    sessionData?: string;
+    sessionData: string;
     /**
      * @internal sessionConfig 渲染数据，内部使用，无需用户传递
      */
@@ -2722,17 +2746,19 @@ export declare type CVVAppearanceProps = {
  */
 export declare class CVVElement extends BaseMainElement<CVVElementConfig, CVVElementEvents> {
     static elementType: string;
+    private readonly sessionData;
     constructor(name: string, config: CVVElementConfig);
     /**
      * @internal
      */
     setup(): Promise<Partial<CVVAppConfig> | undefined>;
     /**
-     * Updates CVV configuration while preserving the public Rules clear semantics.
-     * @param newConfig Partial CVV configuration patch.
+     * @internal Not supported by the public CVV integration API.
+     * Updates appearance only, preserving the Rules clear semantics.
+     * @param newConfig Appearance configuration patch.
      * @returns The WebApp update acknowledgement.
      */
-    updateConfig(newConfig: Partial<CVVAppConfig>): Promise<CVVElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    updateConfig(newConfig: Pick<CVVAppConfig, 'appearance'>): Promise<CVVElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
     /**
      * @internal
      */
@@ -2747,20 +2773,10 @@ export declare class CVVElement extends BaseMainElement<CVVElementConfig, CVVEle
  * @description CVV element config type
  */
 export declare interface CVVElementConfig extends BaseElementConfig<CVVAppConfig> {
+    appConfig: CVVAppConfig;
 }
 
-export declare interface CVVElementEvents extends AntomBridgeEventMap<CVVAppConfig, CVVSubmitParams> {
-    /**
-     * @description Emitted event about form
-     */
-    form: {
-        errors?: Array<{
-            field: string | number;
-            message: string;
-            currentValue: any;
-        }>;
-        message: string;
-    };
+export declare interface CVVElementEvents extends AntomBridgeEventMap<CVVAppConfig, CVVSubmitParams & Pick<CVVAppConfig, 'sessionData'>> {
     /**
      * @description Emitted when the element is destroy
      */
@@ -2804,10 +2820,6 @@ export declare type CVVSubmitErrorCodes = 'NOT_FIND_MAINELEMENT' | 'SESSION_DATA
  * @description CVV 支付提交参数
  */
 export declare interface CVVSubmitParams {
-    /**
-     * 支付会话数据
-     */
-    sessionData?: string;
     /**
      * 重定向策略
      */
@@ -3628,12 +3640,13 @@ export declare interface ExpressAppConfig extends BaseElementAppConfig {
     /**
      * Amount & Currency
      *
-     * Only effective via `updateConfig({ amount })` at runtime.
-     * Passing amount at creation time is ignored; the initial amount
-     * comes from the server-side sdkQuery result (renderData.paymentAmount).
+     * For Apple Pay and Google Pay, `value` is a positive ASCII digit string in
+     * the payment session currency's minor unit; `currency` may be omitted.
+     * For example, USD 10.99 is passed as `{ value: '1099' }`.
+     * PayPal keeps its existing major-unit amount semantics and requires `currency`.
      */
     amount?: {
-        currency: string;
+        currency?: string;
         value: string;
     };
     /** PayPal 配置 */
@@ -3773,7 +3786,17 @@ export declare class ExpressElement extends BaseMainElement<ExpressElementConfig
     private _localHandlers;
     /** 支付流程进行中标志（click → confirm/error/cancel 之间） */
     private _paymentInProgress;
+    /**
+     * 是否已收到 iframe 业务层 ready 事件（app.tsx sendReady）。
+     * 注意：与 host `status='ready'`（由 HANDSHAKE_ACK 触发，bridge.js:450 同步回发，与 amount 解析无关）不同。
+     * 首屏 amount setupError 时 iframe 不发业务 ready → _readyReceived 保持 false，
+     * 据此判别"首屏失败"以阻断后续 updateConfig。
+     */
+    private _readyReceived;
+    /** 首屏 setupError 致命标志：置位后 updateConfig 被 CHECKOUT_NOT_READY 阻断，只能 destroy 重开。 */
+    private _setupFailed;
     private _paypalOverlay;
+    private _updateQueue;
     constructor(name: string, config: ExpressElementConfig);
     /**
      * 重写 on：对 confirm 事件拦截，在商户回调执行前注入 paymentFailed()
@@ -3785,6 +3808,16 @@ export declare class ExpressElement extends BaseMainElement<ExpressElementConfig
      */
     private _emit;
     updateConfig(newConfig: ExpressAppConfig): Promise<ExpressElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    private updateConfigTransaction;
+    private updateAmountConfigWithSanitizedDebug;
+    private getAmountValidationReason;
+    /** iframe 业务 ready 事件到达：置 _readyReceived，后续运行时 error 不再视为首屏失败。
+     *  ready 是"本次首屏成功"的确实信号（首屏 setupError 时 iframe 不发 ready），
+     *  故同时清掉 _setupFailed——unmount+remount 同实例二次首屏成功后可恢复 updateConfig。
+     */
+    private _handleReady;
+    /** iframe error 事件：若 business ready 未到达，视为首屏 setupError → 置 _setupFailed 阻断后续 updateConfig。 */
+    private _handleError;
     /**
      * 商户在 confirm 回调内调用，触发实际支付提交。
      * iframe 收到 OPENSDK@COMPLETE_PAYMENT 后执行 submitPay / polling 等，
@@ -3874,6 +3907,11 @@ export declare interface ExpressElementEvents extends AntomBridgeWithNativeEvent
     'OPENSDK@GET_APPLE_PAY_TOKEN': {
         requestId: string;
         expressPaymentType: string;
+        /** iframe 已转好的 major unit 金额（来自 resolvedAmount）；host 委托 Apple Pay 消费，不再做 minor→major 转换。 */
+        walletAmount?: {
+            value: string;
+            currency: string;
+        };
     };
     /** host 完成 Apple Pay token 获取后回包给 iframe，submit/3DS/polling 均由 webapp 完成 */
     'OPENSDK@GET_APPLE_PAY_TOKEN_REPLY': {
@@ -3984,6 +4022,57 @@ declare interface FrontSupportIppBank {
     logo?: Logo;
 }
 
+/** host 回传 webapp 的 OPENSDK@GET_APPLE_PAY_TOKEN_REPLY 形态(result 对齐老链路 {token,billingContact,shippingContact})。 */
+declare interface GetApplePayTokenReply {
+    success: boolean;
+    result?: {
+        token?: unknown;
+        billingContact?: unknown;
+        shippingContact?: unknown;
+    } | {
+        errorCode: string;
+    };
+}
+
+/** webapp 传来的 OPENSDK@GET_APPLE_PAY_TOKEN payload 形态。 */
+declare interface GetApplePayTokenRequest {
+    paymentMethod?: {
+        paymentMethodDetail?: {
+            applePayProps?: {
+                paymentRequest?: unknown;
+            };
+        };
+    };
+    shipping?: unknown;
+}
+
+/** host 回传 webapp 的 OPENSDK@GET_GOOGLE_PAY_TOKEN_REPLY 形态。 */
+declare interface GetGooglePayTokenReply {
+    success: boolean;
+    result?: unknown;
+    err?: {
+        statusCode?: string;
+        [key: string]: unknown;
+    };
+}
+
+/** webapp 传来的 OPENSDK@GET_GOOGLE_PAY_TOKEN payload 形态。 */
+declare interface GetGooglePayTokenRequest {
+    actionName?: string;
+    data?: {
+        environment?: string;
+        paymentRequest?: unknown;
+        paymentMethod?: unknown;
+        paymentMethodDetail?: {
+            googlePayProps?: {
+                environment?: string;
+                paymentRequest?: unknown;
+            };
+        };
+        [key: string]: unknown;
+    };
+}
+
 declare type GetI18nQueryParam = string | {
     /**
      * 多语言文案的 key
@@ -7559,6 +7648,7 @@ export declare type PaymentAppearanceProps = {
 export declare class PaymentElement extends BaseMainElement<PaymentElementConfig, PaymentElementEvents> {
     static elementType: string;
     private _paymentInProgress;
+    private readonly walletLogger;
     constructor(name: string, config: PaymentElementConfig);
     /**
      * @internal
@@ -7587,6 +7677,20 @@ declare interface PaymentElementConfig extends BaseElementConfig<PaymentAppConfi
  * @description Payment element events
  */
 export declare interface PaymentElementEvents extends AntomBridgeWithNativeEventMap<PaymentAppConfig, PaymentSubmitParams, PaymentSubmitResult> {
+    /**
+     * webapp 委托 host(父 frame)拉起 Apple Pay 拿 token。
+     * payload 结构对齐 ModernElementController.GetApplePayTokenRequest(放 paymentMethod/shipping)。
+     */
+    'OPENSDK@GET_APPLE_PAY_TOKEN': GetApplePayTokenRequest;
+    /** host 完成 Apple Pay token 获取后回包给 webapp */
+    'OPENSDK@GET_APPLE_PAY_TOKEN_REPLY': GetApplePayTokenReply;
+    /**
+     * webapp 委托 host(父 frame)拉起 Google Pay 拿 token。
+     * payload 结构对齐 ModernElementController.GetGooglePayTokenRequest(放 data.environment/paymentRequest)。
+     */
+    'OPENSDK@GET_GOOGLE_PAY_TOKEN': GetGooglePayTokenRequest;
+    /** host 完成 Google Pay token 获取后回包给 webapp */
+    'OPENSDK@GET_GOOGLE_PAY_TOKEN_REPLY': GetGooglePayTokenReply;
 }
 
 declare interface PaymentElementView {