@waffo/waffo-node 2.5.1 → 2.6.0

package/dist/index.d.ts

@@ -187,6 +187,7 @@ interface CreateSubscriptionParams {
     merchantSubscriptionId: string;
     currency: string;
     amount: string;
+    promotionInfo?: SubscriptionPromotionInfo;
     userCurrency?: string;
     notifyUrl: string;
     productInfo: ProductInfo;
@@ -206,6 +207,10 @@ interface CreateSubscriptionParams {
     cancelRedirectUrl?: string;
     subscriptionManagementUrl?: string;
     requestedAt?: string;
+    /**
+     * Subscription start time (ISO 8601 format).
+     */
+    startTime?: string;
     extendInfo?: string;
     /**
      * Order expiry time (ISO 8601 format, max 24 characters).
@@ -214,12 +219,24 @@ interface CreateSubscriptionParams {
     addressInfo?: SubscriptionAddressInfo;
     riskData?: SubscriptionRiskData;
     brandInfo?: SubscriptionBrandInfo;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
     subscriptionMode?: string;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
     acqMerchant?: Record<string, unknown>;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
     acqProduct?: Record<string, unknown>;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
     acqAgreements?: Record<string, unknown>[];
     [key: string]: unknown;
 }
+/**
+ * Promotion information for a subscription.
+ */
+interface SubscriptionPromotionInfo {
+    promotionCode?: string;
+    couponId?: string;
+    [key: string]: unknown;
+}
 /**
  * Create subscription response data.
  */
@@ -263,6 +280,7 @@ interface InquirySubscriptionData {
     payMethodSubscriptionId?: string;
     subscriptionStatus?: SubscriptionStatus;
     subscriptionAction?: string;
+    cancelReason?: string;
     currency?: string;
     userCurrency?: string;
     amount?: string;
@@ -679,6 +697,10 @@ interface SubscriptionChangeParams {
      * New merchant subscription plan ID (max 64 characters).
      */
     merchantSubscriptionId?: string;
+    /**
+     * Promotion information.
+     */
+    promotionInfo?: SubscriptionPromotionInfo;
     /**
      * Original subscription request ID to be changed (max 32 characters).
      */
@@ -699,6 +721,10 @@ interface SubscriptionChangeParams {
      * Request time (ISO 8601 format). Auto-injected if not provided.
      */
     requestedAt?: string;
+    /**
+     * Subscription start time (ISO 8601 format).
+     */
+    startTime?: string;
     /**
      * Redirect URL after successful subscription change.
      */
@@ -934,67 +960,106 @@ interface SubscriptionChangeInquiryData {
 }
 
 /**
- * Webhook event types sent by Waffo.
+ * Order-related type definitions.
+ *
+ * Note: Full type definitions should be generated from openapi.json.
+ * These are placeholder interfaces for the SDK structure.
  */
-declare enum WebhookEventType {
-    PAYMENT_NOTIFICATION = "PAYMENT_NOTIFICATION",
-    REFUND_NOTIFICATION = "REFUND_NOTIFICATION",
-    SUBSCRIPTION_STATUS_NOTIFICATION = "SUBSCRIPTION_STATUS_NOTIFICATION",
-    SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION",
-    SUBSCRIPTION_CHANGE_NOTIFICATION = "SUBSCRIPTION_CHANGE_NOTIFICATION"
+
+/**
+ * Create order request parameters.
+ */
+interface CreateOrderParams {
+    paymentRequestId: string;
+    merchantOrderId: string;
+    orderCurrency: string;
+    orderAmount: string;
+    orderDescription: string;
+    notifyUrl: string;
+    userInfo: UserInfo;
+    paymentInfo: PaymentInfo;
+    merchantInfo?: MerchantInfo;
+    goodsInfo?: GoodsInfo;
+    addressInfo?: AddressInfo;
+    cardInfo?: CardInfo;
+    riskData?: RiskData;
+    paymentTokenData?: PaymentTokenData;
+    brandInfo?: BrandInfo;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
+    productDetail?: ProductDetail;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
+    acqOrderExtSubscriptionInfo?: AcqOrderExtSubscriptionInfo;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
+    channelId?: string;
+    /** @deprecated Legacy field retained for source compatibility; not in the current OpenAPI contract. */
+    innerCardData?: WaffoTokenCardData;
+    promotionInfo?: PromotionInfo;
+    x402Info?: X402Info;
+    userCurrency?: string;
+    successRedirectUrl?: string;
+    failedRedirectUrl?: string;
+    cancelRedirectUrl?: string;
+    orderRequestedAt?: string;
+    orderExpiredAt?: string;
+    extendInfo?: string;
+    [key: string]: unknown;
 }
 /**
- * Result of webhook handling.
+ * Create order response data.
  */
-interface WebhookResult {
-    /** Whether the webhook was processed successfully */
-    success: boolean;
-    /** Response body to send back to Waffo */
-    responseBody: string;
-    /** Signature for the response body */
-    responseSignature: string;
-    /** Error message if processing failed */
-    error?: string;
+interface CreateOrderData {
+    paymentRequestId?: string;
+    merchantOrderId?: string;
+    acquiringOrderId?: string;
+    orderStatus?: OrderStatus;
+    orderAction?: string;
+    x402Info?: X402Info;
+    [key: string]: unknown;
 }
 /**
- * Base notification interface.
+ * Inquiry order request parameters.
+ * Provide paymentRequestId or acquiringOrderId.
  */
-interface BaseNotification {
-    eventType: string;
+interface InquiryOrderParams {
+    paymentRequestId?: string;
+    acquiringOrderId?: string;
+    [key: string]: unknown;
 }
 /**
- * Payment notification result payload (21 fields).
+ * Inquiry order response data.
  */
-interface PaymentNotificationResult {
+interface InquiryOrderData {
     paymentRequestId?: string;
     merchantOrderId?: string;
     acquiringOrderId?: string;
-    orderStatus?: string;
+    orderStatus?: OrderStatus;
     orderAction?: string;
     orderCurrency?: string;
     orderAmount?: string;
-    userCurrency?: string;
+    originalAmount?: string;
     finalDealAmount?: string;
     orderDescription?: string;
-    merchantInfo?: Record<string, unknown>;
-    userInfo?: Record<string, unknown>;
-    goodsInfo?: Record<string, unknown>;
-    addressInfo?: Record<string, unknown>;
-    paymentInfo?: Record<string, unknown>;
+    merchantInfo?: MerchantInfo;
+    userInfo?: UserInfo;
+    goodsInfo?: GoodsInfo;
+    paymentInfo?: PaymentInfo;
+    addressInfo?: AddressInfo;
     orderRequestedAt?: string;
     orderExpiredAt?: string;
     orderUpdatedAt?: string;
     orderCompletedAt?: string;
-    orderFailedReason?: Record<string, unknown>;
+    /**
+     * Refund expiry time (ISO 8601 format).
+     */
+    refundExpiryAt?: string;
+    orderFailedReason?: string;
     extendInfo?: string;
+    userCurrency?: string;
+    x402Info?: X402Info;
     /**
      * The associated subscription info.
      */
     subscriptionInfo?: SubscriptionInfo;
-    /**
-     * Refund expiry time (ISO 8601 format).
-     */
-    refundExpiryAt?: string;
     /**
      * The address of the merchant page to redirect to when user cancels the payment.
      */
@@ -1002,708 +1067,700 @@ interface PaymentNotificationResult {
     [key: string]: unknown;
 }
 /**
- * Refund notification result payload (17 fields).
+ * Cancel order request parameters.
  */
-interface RefundNotificationResult {
-    refundRequestId?: string;
-    merchantRefundOrderId?: string;
+interface CancelOrderParams {
+    paymentRequestId?: string;
     acquiringOrderId?: string;
-    acquiringRefundOrderId?: string;
-    origPaymentRequestId?: string;
-    refundAmount?: string;
-    refundStatus?: string;
-    remainingRefundAmount?: string;
-    userCurrency?: string;
-    finalDealAmount?: string;
-    refundReason?: string;
-    refundRequestedAt?: string;
-    refundUpdatedAt?: string;
-    refundCompletedAt?: string;
-    refundFailedReason?: Record<string, unknown>;
-    userInfo?: Record<string, unknown>;
-    extendInfo?: string;
-    /**
-     * Refund source. Possible values: MERCHANT, RDR, ETHOCA.
-     */
-    refundSource?: string;
+    merchantId?: string;
+    orderRequestedAt?: string;
     [key: string]: unknown;
 }
 /**
- * Subscription notification result payload (20 fields).
- * Shared by SubscriptionStatusNotification and SubscriptionPeriodChangedNotification.
+ * Cancel order response data.
  */
-interface SubscriptionNotificationResult {
-    subscriptionRequest?: string;
-    merchantSubscriptionId?: string;
-    subscriptionId?: string;
-    /**
-     * Payment method's subscription id.
-     */
-    payMethodSubscriptionId?: string;
-    subscriptionStatus?: string;
-    subscriptionAction?: string;
-    currency?: string;
-    amount?: string;
-    userCurrency?: string;
-    productInfo?: Record<string, unknown>;
-    merchantInfo?: Record<string, unknown>;
-    userInfo?: Record<string, unknown>;
-    goodsInfo?: Record<string, unknown>;
-    addressInfo?: Record<string, unknown>;
-    paymentInfo?: Record<string, unknown>;
-    requestedAt?: string;
-    updatedAt?: string;
-    failedReason?: Record<string, unknown>;
-    extendInfo?: string;
-    subscriptionManagementUrl?: string;
-    paymentDetails?: Record<string, unknown>[];
+interface CancelOrderData {
+    paymentRequestId?: string;
+    merchantOrderId?: string;
+    acquiringOrderId?: string;
+    orderStatus?: OrderStatus;
     [key: string]: unknown;
 }
 /**
- * Subscription change notification result payload.
- * Triggered when a subscription change (upgrade/downgrade) reaches final status (SUCCESS or CLOSED).
+ * Refund order request parameters.
  */
-interface SubscriptionChangeNotificationResult {
-    subscriptionRequest?: string;
-    originSubscriptionRequest?: string;
-    merchantSubscriptionId?: string;
-    subscriptionId?: string;
-    /** Final status: SUCCESS or CLOSED */
-    subscriptionChangeStatus?: string;
-    subscriptionAction?: string;
-    remainingAmount?: string;
-    currency?: string;
-    userCurrency?: string;
+interface RefundOrderParams {
+    refundRequestId: string;
+    acquiringOrderId: string;
+    merchantId?: string;
+    merchantRefundOrderId?: string;
+    refundAmount: string;
+    refundReason: string;
     requestedAt?: string;
-    subscriptionManagementUrl?: string;
+    refundNotifyUrl?: string;
+    userInfo?: RefundUserInfo;
     extendInfo?: string;
-    orderExpiredAt?: string;
-    productInfoList?: Record<string, unknown>[];
-    merchantInfo?: Record<string, unknown>;
-    userInfo?: Record<string, unknown>;
-    goodsInfo?: Record<string, unknown>;
-    addressInfo?: Record<string, unknown>;
-    paymentInfo?: Record<string, unknown>;
+    refundSource?: string;
     [key: string]: unknown;
 }
 /**
- * Payment notification from Waffo.
+ * Refund order response data.
  */
-interface PaymentNotification extends BaseNotification {
-    eventType: 'PAYMENT_NOTIFICATION';
-    result?: PaymentNotificationResult;
+interface RefundOrderData {
+    refundRequestId?: string;
+    merchantRefundOrderId?: string;
+    acquiringOrderId?: string;
+    acquiringRefundOrderId?: string;
+    refundAmount?: string;
+    refundStatus?: RefundStatus$1;
+    remainingRefundAmount?: string;
+    refundSource?: string;
     [key: string]: unknown;
 }
 /**
- * Refund notification from Waffo.
+ * Capture order request parameters.
  */
-interface RefundNotification extends BaseNotification {
-    eventType: 'REFUND_NOTIFICATION';
-    result?: RefundNotificationResult;
+interface CaptureOrderParams {
+    paymentRequestId?: string;
+    acquiringOrderId?: string;
+    merchantId?: string;
+    captureRequestedAt?: string;
+    captureAmount: string;
     [key: string]: unknown;
 }
 /**
- * Subscription status notification from Waffo.
+ * Capture order response data.
  */
-interface SubscriptionStatusNotification extends BaseNotification {
-    eventType: 'SUBSCRIPTION_STATUS_NOTIFICATION';
-    result?: SubscriptionNotificationResult;
+interface CaptureOrderData {
+    paymentRequestId?: string;
+    merchantOrderId?: string;
+    acquiringOrderId?: string;
+    orderStatus?: OrderStatus;
+    compensateSuccess?: boolean;
     [key: string]: unknown;
 }
 /**
- * Subscription period changed notification from Waffo.
+ * Order status enum.
  */
-interface SubscriptionPeriodChangedNotification extends BaseNotification {
-    eventType: 'SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION';
-    result?: SubscriptionNotificationResult;
-    [key: string]: unknown;
-}
+type OrderStatus = 'PAY_IN_PROGRESS' | 'AUTHORIZATION_REQUIRED' | 'AUTHED_WAITING_CAPTURE' | 'PAY_SUCCESS' | 'ORDER_CLOSE' | 'CAPTURE_IN_PROGRESS';
 /**
- * Subscription change notification from Waffo.
+ * Refund status enum.
  */
-interface SubscriptionChangeNotification extends BaseNotification {
-    eventType: 'SUBSCRIPTION_CHANGE_NOTIFICATION';
-    result?: SubscriptionChangeNotificationResult;
-    [key: string]: unknown;
-}
-type PaymentHandler = (notification: PaymentNotification) => void | Promise<void>;
-type RefundHandler = (notification: RefundNotification) => void | Promise<void>;
-type SubscriptionStatusHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
-type SubscriptionPaymentHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
-type SubscriptionPeriodChangedHandler = (notification: SubscriptionPeriodChangedNotification) => void | Promise<void>;
-type SubscriptionChangeHandler = (notification: SubscriptionChangeNotification) => void | Promise<void>;
+type RefundStatus$1 = 'REFUND_IN_PROGRESS' | 'ORDER_PARTIALLY_REFUNDED' | 'ORDER_FULLY_REFUNDED' | 'ORDER_REFUND_FAILED';
 /**
- * Webhook handler for processing Waffo webhook notifications.
- *
- * @example
- * ```typescript
- * // Setup handler
- * const handler = waffo.webhook()
- *   .onPayment((notification) => {
- *     console.log('Payment:', notification.result?.orderStatus);
- *   })
- *   .onRefund((notification) => {
- *     console.log('Refund:', notification.result?.refundStatus);
- *   });
- *
- * // Process webhook (e.g., in Express.js)
- * app.post('/webhook', async (req, res) => {
- *   const body = req.body.toString();
- *   const signature = req.headers['x-signature'];
- *   const result = await handler.handleWebhook(body, signature);
- *
- *   res.setHeader('X-SIGNATURE', result.responseSignature);
- *   res.status(200).send(result.responseBody);
- * });
- * ```
+ * User information.
  */
-declare class WebhookHandler {
-    private readonly waffoPublicKey;
-    private readonly privateKey;
-    private readonly logger?;
-    private paymentHandler?;
-    private refundHandler?;
-    private subscriptionStatusHandler?;
-    private subscriptionPaymentHandler?;
-    private subscriptionPeriodChangedHandler?;
-    private subscriptionChangeHandler?;
-    constructor(config: WaffoConfig);
-    /**
-     * Registers a handler for payment notifications.
-     */
-    onPayment(handler: PaymentHandler): this;
-    /**
-     * Registers a handler for refund notifications.
-     */
-    onRefund(handler: RefundHandler): this;
-    /**
-     * Registers a handler for subscription status notifications.
-     */
-    onSubscriptionStatus(handler: SubscriptionStatusHandler): this;
-    /**
-     * Registers a fallback handler for SUBSCRIPTION_STATUS_NOTIFICATION events.
-     * Only called when onSubscriptionStatus handler is not registered.
-     */
-    onSubscriptionPayment(handler: SubscriptionPaymentHandler): this;
-    /**
-     * Registers a handler for subscription period changed notifications.
-     */
-    onSubscriptionPeriodChanged(handler: SubscriptionPeriodChangedHandler): this;
-    /**
-     * Registers a handler for subscription change notifications.
-     */
-    onSubscriptionChange(handler: SubscriptionChangeHandler): this;
-    /**
-     * Processes a webhook notification.
-     *
-     * @param body - The raw webhook body
-     * @param signature - The X-SIGNATURE header value
-     * @returns Result with response body and signature
-     */
-    handleWebhook(body: string, signature: string): Promise<WebhookResult>;
-    /**
-     * Verifies a webhook signature.
-     *
-     * @param body - The raw webhook body
-     * @param signature - The X-SIGNATURE header value
-     * @returns true if signature is valid
-     */
-    verifySignature(body: string, signature: string): boolean;
-    /**
-     * Builds a success response with signature.
-     */
-    buildSuccessResponse(): {
-        body: string;
-        signature: string;
-    };
+interface UserInfo {
+    userId: string;
+    userEmail: string;
+    userPhone?: string;
+    userFirstName?: string;
+    userLastName?: string;
+    userCreatedAt?: string;
+    userTerminal?: string;
+    userCountryCode?: string;
+    userBrowserIp?: string;
+    userAgent?: string;
     /**
-     * Builds a failed response with signature.
+     * User receipt URL (max 256 characters).
      */
-    buildFailedResponse(_message: string): {
-        body: string;
-        signature: string;
-    };
-    private createSuccessResult;
-    private createFailedResult;
+    userReceiptUrl?: string;
+    [key: string]: unknown;
 }
-
 /**
- * Generic API response wrapper.
- *
- * All API responses are wrapped in this class for consistent handling.
- *
- * @example
- * ```typescript
- * const response = await waffo.order().create(params);
- *
- * if (response.isSuccess()) {
- *   const data = response.getData();
- *   console.log('Order ID:', data?.acquiringOrderId);
- * } else {
- *   console.error(`Error [${response.code}]: ${response.getMessage()}`);
- * }
- * ```
+ * Payment information.
  */
-declare class ApiResponse<T> {
-    /** Response code. "0" indicates success, other values indicate errors. */
-    readonly code: string;
-    /** Response data (present when code is "0") */
-    readonly data?: T;
-    /** Error message (present when code is not "0") */
-    readonly message?: string;
-    private constructor();
-    /**
-     * Creates a successful response.
-     *
-     * @param data - The response data
-     */
-    static success<T>(data?: T): ApiResponse<T>;
-    /**
-     * Creates an error response.
-     *
-     * @param code - The error code
-     * @param message - The error message
-     */
-    static error<T>(code: string, message?: string): ApiResponse<T>;
-    /**
-     * Checks if the response indicates success.
-     *
-     * @returns true if the response code is "0"
-     */
-    isSuccess(): boolean;
-    /**
-     * Gets the response data.
-     *
-     * @returns The response data, or undefined if the response is an error
-     */
-    getData(): T | undefined;
-    /**
-     * Gets the error message.
-     *
-     * @returns The error message, or undefined if the response is successful
-     */
-    getMessage(): string | undefined;
-    /**
-     * Gets the response code.
-     *
-     * @returns The response code
-     */
-    getCode(): string;
-    /**
-     * Gets the response data or throws an error.
-     *
-     * @returns The response data
-     * @throws Error if the response is not successful or data is undefined
-     */
-    getDataOrThrow(): T;
+interface PaymentInfo {
+    productName: string;
+    payMethodType?: string;
+    payMethodName?: string;
+    payMethodProperties?: string;
+    payMethodResponse?: string;
+    userPaymentAccessToken?: string;
+    payMethodUserAccountNo?: string;
+    payMethodUserAccountType?: string;
+    payOption?: string;
+    cashierLanguage?: string;
+    cashierAppearance?: string;
+    payMethodCountry?: string;
+    captureMode?: string;
+    merchantInitiatedMode?: string;
+    [key: string]: unknown;
 }
-
 /**
- * HTTP client for making requests to the Waffo API.
- *
- * Handles:
- * - Request signing with merchant's private key
- * - Response signature verification with Waffo's public key
- * - MerchantId auto-injection
- * - Error handling and timeout management
+ * Merchant information.
  */
-declare class WaffoHttpClient {
-    private readonly baseUrl;
-    private readonly apiKey;
-    private readonly privateKey;
-    private readonly waffoPublicKey;
-    private readonly merchantId;
-    private readonly connectTimeout;
-    private readonly readTimeout;
-    private readonly logger?;
-    private readonly httpTransport;
-    constructor(config: WaffoConfig);
-    /**
-     * Sends a POST request to the Waffo API.
-     *
-     * @param path - API endpoint path (e.g., "/order/create")
-     * @param request - Request body
-     * @param options - Per-request options
-     * @returns API response
-     * @throws WaffoUnknownStatusError for network errors or unknown status
-     */
-    post<T extends object, R>(path: string, request: T, options?: RequestOptions): Promise<ApiResponse<R>>;
-    /**
-     * Parses the API response body.
-     */
-    private parseResponse;
-    /**
-     * Auto-injects merchantId into the request if configured.
-     */
-    private injectMerchantIdIfNeeded;
-    /**
-     * Checks if the error is a network-related error.
-     */
-    private isNetworkError;
+interface MerchantInfo {
+    merchantId: string;
+    subMerchantId?: string;
+    [key: string]: unknown;
 }
-
 /**
- * Base class for API resources.
+ * Goods information.
  */
-declare abstract class BaseResource {
-    protected readonly httpClient: WaffoHttpClient;
-    protected readonly basePath: string;
-    constructor(httpClient: WaffoHttpClient, basePath: string);
-    /**
-     * Gets the full path for an endpoint.
-     *
-     * @param endpoint - The endpoint (e.g., "/create")
-     * @returns Full path (e.g., "/order/create")
-     */
-    protected getPath(endpoint: string): string;
+interface GoodsInfo {
+    goodsId?: string;
+    goodsName?: string;
+    goodsCategory?: string;
+    goodsUrl?: string;
+    appName?: string;
+    skuName?: string;
+    goodsUniquePrice?: string;
+    goodsQuantity?: number;
+    [key: string]: unknown;
 }
-
 /**
- * Order-related type definitions.
- *
- * Note: Full type definitions should be generated from openapi.json.
- * These are placeholder interfaces for the SDK structure.
+ * Address information.
  */
-
+interface AddressInfo {
+    address?: string;
+    city?: string;
+    region?: string;
+    postcode?: string;
+    addressCountryCode?: string;
+    [key: string]: unknown;
+}
 /**
- * Create order request parameters.
+ * Card information.
  */
-interface CreateOrderParams {
-    paymentRequestId: string;
-    merchantOrderId: string;
-    orderCurrency: string;
-    orderAmount: string;
-    orderDescription: string;
-    notifyUrl: string;
-    userInfo: UserInfo;
-    paymentInfo: PaymentInfo;
-    merchantInfo?: MerchantInfo;
-    goodsInfo?: GoodsInfo;
-    addressInfo?: AddressInfo;
-    cardInfo?: CardInfo;
-    riskData?: RiskData;
-    paymentTokenData?: PaymentTokenData;
-    brandInfo?: BrandInfo;
-    productDetail?: ProductDetail;
-    acqOrderExtSubscriptionInfo?: AcqOrderExtSubscriptionInfo;
-    channelId?: string;
-    innerCardData?: WaffoTokenCardData;
-    userCurrency?: string;
-    successRedirectUrl?: string;
-    failedRedirectUrl?: string;
-    cancelRedirectUrl?: string;
-    orderRequestedAt?: string;
-    orderExpiredAt?: string;
-    extendInfo?: string;
+interface CardInfo {
+    cardNumber?: string;
+    cardExpiryYear?: number;
+    cardExpiryMonth?: number;
+    cardCvv?: string;
+    cardHolderName?: string;
+    threeDsDecision?: string;
     [key: string]: unknown;
 }
 /**
- * Create order response data.
+ * Risk data.
  */
-interface CreateOrderData {
-    paymentRequestId?: string;
-    merchantOrderId?: string;
-    acquiringOrderId?: string;
-    orderStatus?: OrderStatus;
-    orderAction?: string;
+interface RiskData {
+    userType?: string;
+    userCategory?: string;
+    userLegalName?: string;
+    userDisplayName?: string;
+    userRegistrationIp?: string;
+    userLastSeenIp?: string;
+    userIsNew?: string;
+    userIsFirstPurchase?: string;
     [key: string]: unknown;
 }
 /**
- * Inquiry order request parameters.
- * Provide paymentRequestId or acquiringOrderId.
+ * Payment token data.
  */
-interface InquiryOrderParams {
-    paymentRequestId?: string;
-    acquiringOrderId?: string;
+interface PaymentTokenData {
+    tokenId?: string;
     [key: string]: unknown;
 }
 /**
- * Inquiry order response data.
+ * Brand display information for cashier.
  */
-interface InquiryOrderData {
+interface BrandInfo {
+    cashierLogoUrl?: string;
+    cashierDisplayName?: string;
+    cashierProductImageUrl?: string;
+    [key: string]: unknown;
+}
+/**
+ * @deprecated Legacy order extension retained for source compatibility.
+ */
+interface ProductDetail {
+    subscriptionInfo?: SubscriptionInfo;
+    [key: string]: unknown;
+}
+/**
+ * @deprecated Legacy subscription extension retained for source compatibility.
+ */
+interface AcqOrderExtSubscriptionInfo {
+    subscriptionId?: string;
+    periodNo?: number;
+    merchantRequest?: string;
+    subscriptionEvent?: string;
+    [key: string]: unknown;
+}
+/**
+ * @deprecated Legacy tokenized card data retained for source compatibility.
+ */
+interface WaffoTokenCardData {
+    cardBinDataList?: Record<string, unknown>[];
+    maskedCardInfo?: string;
+    cardBin?: string;
+    cardExpiry?: string;
+    [key: string]: unknown;
+}
+/**
+ * x402 stablecoin payment information.
+ */
+interface X402Info {
+    x402Request?: boolean;
+    paymentSignatureHeader?: string;
+    x402Response?: string;
+    [key: string]: unknown;
+}
+/**
+ * Promotion information for an order.
+ */
+interface PromotionInfo {
+    promotionCode?: string;
+    couponId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Refund user information.
+ */
+interface RefundUserInfo {
+    userType?: string;
+    userFirstName?: string;
+    userMiddleName?: string;
+    userLastName?: string;
+    nationality?: string;
+    userEmail?: string;
+    userPhone?: string;
+    userBirthDay?: string;
+    userIDType?: string;
+    userIDNumber?: string;
+    userIDIssueDate?: string;
+    userIDExpiryDate?: string;
+    userBankInfo?: RefundUserBankInfo;
+    [key: string]: unknown;
+}
+interface RefundUserBankInfo {
+    bankAccountNo?: string;
+    bankCode?: string;
+    bankName?: string;
+    bankCity?: string;
+    bankBranch?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Webhook event types sent by Waffo.
+ */
+declare enum WebhookEventType {
+    PAYMENT_NOTIFICATION = "PAYMENT_NOTIFICATION",
+    REFUND_NOTIFICATION = "REFUND_NOTIFICATION",
+    SUBSCRIPTION_STATUS_NOTIFICATION = "SUBSCRIPTION_STATUS_NOTIFICATION",
+    SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION = "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION",
+    SUBSCRIPTION_CHANGE_NOTIFICATION = "SUBSCRIPTION_CHANGE_NOTIFICATION"
+}
+/**
+ * Result of webhook handling.
+ */
+interface WebhookResult {
+    /** Whether the webhook was processed successfully */
+    success: boolean;
+    /** Response body to send back to Waffo */
+    responseBody: string;
+    /** Signature for the response body */
+    responseSignature: string;
+    /** Error message if processing failed */
+    error?: string;
+}
+/**
+ * Base notification interface.
+ */
+interface BaseNotification {
+    eventType: string;
+}
+/**
+ * Payment notification result payload (21 fields).
+ */
+interface PaymentNotificationResult {
     paymentRequestId?: string;
     merchantOrderId?: string;
     acquiringOrderId?: string;
-    orderStatus?: OrderStatus;
+    orderStatus?: string;
     orderAction?: string;
     orderCurrency?: string;
     orderAmount?: string;
+    userCurrency?: string;
     finalDealAmount?: string;
     orderDescription?: string;
-    merchantInfo?: MerchantInfo;
-    userInfo?: UserInfo;
-    goodsInfo?: GoodsInfo;
-    paymentInfo?: PaymentInfo;
-    addressInfo?: AddressInfo;
+    merchantInfo?: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    goodsInfo?: Record<string, unknown>;
+    addressInfo?: Record<string, unknown>;
+    paymentInfo?: Record<string, unknown>;
     orderRequestedAt?: string;
     orderExpiredAt?: string;
     orderUpdatedAt?: string;
     orderCompletedAt?: string;
-    /**
-     * Refund expiry time (ISO 8601 format).
-     */
-    refundExpiryAt?: string;
-    orderFailedReason?: string;
+    orderFailedReason?: Record<string, unknown>;
     extendInfo?: string;
-    userCurrency?: string;
     /**
      * The associated subscription info.
      */
-    subscriptionInfo?: SubscriptionInfo;
-    /**
-     * The address of the merchant page to redirect to when user cancels the payment.
-     */
-    cancelRedirectUrl?: string;
-    [key: string]: unknown;
-}
-/**
- * Cancel order request parameters.
- */
-interface CancelOrderParams {
-    paymentRequestId?: string;
-    acquiringOrderId?: string;
-    merchantId?: string;
-    orderRequestedAt?: string;
-    [key: string]: unknown;
-}
-/**
- * Cancel order response data.
- */
-interface CancelOrderData {
-    paymentRequestId?: string;
-    merchantOrderId?: string;
-    acquiringOrderId?: string;
-    orderStatus?: OrderStatus;
-    [key: string]: unknown;
-}
-/**
- * Refund order request parameters.
- */
-interface RefundOrderParams {
-    refundRequestId: string;
-    acquiringOrderId: string;
-    merchantId?: string;
-    merchantRefundOrderId?: string;
-    refundAmount: string;
-    refundReason: string;
-    requestedAt?: string;
-    refundNotifyUrl?: string;
-    userInfo?: RefundUserInfo;
-    extendInfo?: string;
-    refundSource?: string;
+    subscriptionInfo?: SubscriptionInfo;
+    /**
+     * Refund expiry time (ISO 8601 format).
+     */
+    refundExpiryAt?: string;
+    /**
+     * The address of the merchant page to redirect to when user cancels the payment.
+     */
+    cancelRedirectUrl?: string;
+    /**
+     * x402 stablecoin payment information.
+     */
+    x402Info?: X402Info;
     [key: string]: unknown;
 }
 /**
- * Refund order response data.
+ * Refund notification result payload (17 fields).
  */
-interface RefundOrderData {
+interface RefundNotificationResult {
     refundRequestId?: string;
     merchantRefundOrderId?: string;
     acquiringOrderId?: string;
     acquiringRefundOrderId?: string;
+    origPaymentRequestId?: string;
     refundAmount?: string;
-    refundStatus?: RefundStatus$1;
+    refundStatus?: string;
     remainingRefundAmount?: string;
+    userCurrency?: string;
+    finalDealAmount?: string;
+    refundReason?: string;
+    refundRequestedAt?: string;
+    refundUpdatedAt?: string;
+    refundCompletedAt?: string;
+    refundFailedReason?: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    extendInfo?: string;
+    /**
+     * Refund source. Possible values: MERCHANT, RDR, ETHOCA.
+     */
     refundSource?: string;
     [key: string]: unknown;
 }
 /**
- * Capture order request parameters.
- */
-interface CaptureOrderParams {
-    paymentRequestId?: string;
-    acquiringOrderId?: string;
-    merchantId?: string;
-    captureRequestedAt?: string;
-    captureAmount: string;
-    [key: string]: unknown;
-}
-/**
- * Capture order response data.
- */
-interface CaptureOrderData {
-    paymentRequestId?: string;
-    merchantOrderId?: string;
-    acquiringOrderId?: string;
-    orderStatus?: OrderStatus;
-    [key: string]: unknown;
-}
-/**
- * Order status enum.
- */
-type OrderStatus = 'PAY_IN_PROGRESS' | 'AUTHORIZATION_REQUIRED' | 'AUTHED_WAITING_CAPTURE' | 'PAY_SUCCESS' | 'ORDER_CLOSE' | 'CAPTURE_IN_PROGRESS';
-/**
- * Refund status enum.
- */
-type RefundStatus$1 = 'REFUND_IN_PROGRESS' | 'ORDER_PARTIALLY_REFUNDED' | 'ORDER_FULLY_REFUNDED' | 'ORDER_REFUND_FAILED';
-/**
- * User information.
+ * Subscription notification result payload (20 fields).
+ * Shared by SubscriptionStatusNotification and SubscriptionPeriodChangedNotification.
  */
-interface UserInfo {
-    userId: string;
-    userEmail: string;
-    userPhone?: string;
-    userFirstName?: string;
-    userLastName?: string;
-    userCreatedAt?: string;
-    userTerminal?: string;
-    userCountryCode?: string;
-    userBrowserIp?: string;
-    userAgent?: string;
+interface SubscriptionNotificationResult {
+    subscriptionRequest?: string;
+    merchantSubscriptionId?: string;
+    subscriptionId?: string;
     /**
-     * User receipt URL (max 256 characters).
+     * Payment method's subscription id.
      */
-    userReceiptUrl?: string;
-    [key: string]: unknown;
-}
-/**
- * Payment information.
- */
-interface PaymentInfo {
-    productName: string;
-    payMethodType?: string;
-    payMethodName?: string;
-    payMethodProperties?: string;
-    payMethodResponse?: string;
-    userPaymentAccessToken?: string;
-    payMethodUserAccountNo?: string;
-    payMethodUserAccountType?: string;
-    payOption?: string;
-    cashierLanguage?: string;
-    cashierAppearance?: string;
-    payMethodCountry?: string;
-    captureMode?: string;
-    merchantInitiatedMode?: string;
-    [key: string]: unknown;
-}
-/**
- * Merchant information.
- */
-interface MerchantInfo {
-    merchantId: string;
-    subMerchantId?: string;
+    payMethodSubscriptionId?: string;
+    subscriptionStatus?: string;
+    subscriptionAction?: string;
+    currency?: string;
+    amount?: string;
+    userCurrency?: string;
+    productInfo?: Record<string, unknown>;
+    merchantInfo?: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    goodsInfo?: Record<string, unknown>;
+    addressInfo?: Record<string, unknown>;
+    paymentInfo?: Record<string, unknown>;
+    requestedAt?: string;
+    updatedAt?: string;
+    failedReason?: Record<string, unknown>;
+    extendInfo?: string;
+    subscriptionManagementUrl?: string;
+    paymentDetails?: Record<string, unknown>[];
     [key: string]: unknown;
 }
 /**
- * Goods information.
+ * Subscription change notification result payload.
+ * Triggered when a subscription change (upgrade/downgrade) reaches final status (SUCCESS or CLOSED).
  */
-interface GoodsInfo {
-    goodsId?: string;
-    goodsName?: string;
-    goodsCategory?: string;
-    goodsUrl?: string;
-    appName?: string;
-    skuName?: string;
-    goodsUniquePrice?: string;
-    goodsQuantity?: number;
+interface SubscriptionChangeNotificationResult {
+    subscriptionRequest?: string;
+    originSubscriptionRequest?: string;
+    merchantSubscriptionId?: string;
+    subscriptionId?: string;
+    /** Final status: SUCCESS or CLOSED */
+    subscriptionChangeStatus?: string;
+    subscriptionAction?: string;
+    remainingAmount?: string;
+    currency?: string;
+    userCurrency?: string;
+    requestedAt?: string;
+    subscriptionManagementUrl?: string;
+    extendInfo?: string;
+    orderExpiredAt?: string;
+    productInfoList?: Record<string, unknown>[];
+    merchantInfo?: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    goodsInfo?: Record<string, unknown>;
+    addressInfo?: Record<string, unknown>;
+    paymentInfo?: Record<string, unknown>;
     [key: string]: unknown;
 }
 /**
- * Address information.
+ * Payment notification from Waffo.
  */
-interface AddressInfo {
-    address?: string;
-    city?: string;
-    region?: string;
-    postcode?: string;
-    addressCountryCode?: string;
+interface PaymentNotification extends BaseNotification {
+    eventType: 'PAYMENT_NOTIFICATION';
+    result?: PaymentNotificationResult;
     [key: string]: unknown;
 }
 /**
- * Card information.
+ * Refund notification from Waffo.
  */
-interface CardInfo {
-    cardNumber?: string;
-    cardExpiryYear?: number;
-    cardExpiryMonth?: number;
-    cardCvv?: string;
-    cardHolderName?: string;
-    threeDsDecision?: string;
+interface RefundNotification extends BaseNotification {
+    eventType: 'REFUND_NOTIFICATION';
+    result?: RefundNotificationResult;
     [key: string]: unknown;
 }
 /**
- * Risk data.
+ * Subscription status notification from Waffo.
  */
-interface RiskData {
-    userType?: string;
-    userCategory?: string;
-    userLegalName?: string;
-    userDisplayName?: string;
-    userRegistrationIp?: string;
-    userLastSeenIp?: string;
-    userIsNew?: string;
-    userIsFirstPurchase?: string;
+interface SubscriptionStatusNotification extends BaseNotification {
+    eventType: 'SUBSCRIPTION_STATUS_NOTIFICATION';
+    result?: SubscriptionNotificationResult;
     [key: string]: unknown;
 }
 /**
- * Payment token data.
+ * Subscription period changed notification from Waffo.
  */
-interface PaymentTokenData {
-    tokenId?: string;
+interface SubscriptionPeriodChangedNotification extends BaseNotification {
+    eventType: 'SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION';
+    result?: SubscriptionNotificationResult;
     [key: string]: unknown;
 }
 /**
- * Brand display information for cashier.
+ * Subscription change notification from Waffo.
  */
-interface BrandInfo {
-    cashierLogoUrl?: string;
-    cashierDisplayName?: string;
-    cashierProductImageUrl?: string;
+interface SubscriptionChangeNotification extends BaseNotification {
+    eventType: 'SUBSCRIPTION_CHANGE_NOTIFICATION';
+    result?: SubscriptionChangeNotificationResult;
     [key: string]: unknown;
 }
+type PaymentHandler = (notification: PaymentNotification) => void | Promise<void>;
+type RefundHandler = (notification: RefundNotification) => void | Promise<void>;
+type SubscriptionStatusHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
+type SubscriptionPaymentHandler = (notification: SubscriptionStatusNotification) => void | Promise<void>;
+type SubscriptionPeriodChangedHandler = (notification: SubscriptionPeriodChangedNotification) => void | Promise<void>;
+type SubscriptionChangeHandler = (notification: SubscriptionChangeNotification) => void | Promise<void>;
 /**
- * Product detail extension payload.
+ * Webhook handler for processing Waffo webhook notifications.
+ *
+ * @example
+ * ```typescript
+ * // Setup handler
+ * const handler = waffo.webhook()
+ *   .onPayment((notification) => {
+ *     console.log('Payment:', notification.result?.orderStatus);
+ *   })
+ *   .onRefund((notification) => {
+ *     console.log('Refund:', notification.result?.refundStatus);
+ *   });
+ *
+ * // Process webhook (e.g., in Express.js)
+ * app.post('/webhook', async (req, res) => {
+ *   const body = req.body.toString();
+ *   const signature = req.headers['x-signature'];
+ *   const result = await handler.handleWebhook(body, signature);
+ *
+ *   res.setHeader('X-SIGNATURE', result.responseSignature);
+ *   res.status(200).send(result.responseBody);
+ * });
+ * ```
  */
-interface ProductDetail {
-    subscriptionInfo?: SubscriptionInfo;
-    [key: string]: unknown;
+declare class WebhookHandler {
+    private readonly waffoPublicKey;
+    private readonly privateKey;
+    private readonly logger?;
+    private paymentHandler?;
+    private refundHandler?;
+    private subscriptionStatusHandler?;
+    private subscriptionPaymentHandler?;
+    private subscriptionPeriodChangedHandler?;
+    private subscriptionChangeHandler?;
+    constructor(config: WaffoConfig);
+    /**
+     * Registers a handler for payment notifications.
+     */
+    onPayment(handler: PaymentHandler): this;
+    /**
+     * Registers a handler for refund notifications.
+     */
+    onRefund(handler: RefundHandler): this;
+    /**
+     * Registers a handler for subscription status notifications.
+     */
+    onSubscriptionStatus(handler: SubscriptionStatusHandler): this;
+    /**
+     * Registers a fallback handler for SUBSCRIPTION_STATUS_NOTIFICATION events.
+     * Only called when onSubscriptionStatus handler is not registered.
+     */
+    onSubscriptionPayment(handler: SubscriptionPaymentHandler): this;
+    /**
+     * Registers a handler for subscription period changed notifications.
+     */
+    onSubscriptionPeriodChanged(handler: SubscriptionPeriodChangedHandler): this;
+    /**
+     * Registers a handler for subscription change notifications.
+     */
+    onSubscriptionChange(handler: SubscriptionChangeHandler): this;
+    /**
+     * Processes a webhook notification.
+     *
+     * @param body - The raw webhook body
+     * @param signature - The X-SIGNATURE header value
+     * @returns Result with response body and signature
+     */
+    handleWebhook(body: string, signature: string): Promise<WebhookResult>;
+    /**
+     * Verifies a webhook signature.
+     *
+     * @param body - The raw webhook body
+     * @param signature - The X-SIGNATURE header value
+     * @returns true if signature is valid
+     */
+    verifySignature(body: string, signature: string): boolean;
+    /**
+     * Builds a success response with signature.
+     */
+    buildSuccessResponse(): {
+        body: string;
+        signature: string;
+    };
+    /**
+     * Builds a failed response with signature.
+     */
+    buildFailedResponse(_message: string): {
+        body: string;
+        signature: string;
+    };
+    private createSuccessResult;
+    private createFailedResult;
 }
+
 /**
- * Subscription extension information for an acquiring order.
+ * Generic API response wrapper.
+ *
+ * All API responses are wrapped in this class for consistent handling.
+ *
+ * @example
+ * ```typescript
+ * const response = await waffo.order().create(params);
+ *
+ * if (response.isSuccess()) {
+ *   const data = response.getData();
+ *   console.log('Order ID:', data?.acquiringOrderId);
+ * } else {
+ *   console.error(`Error [${response.code}]: ${response.getMessage()}`);
+ * }
+ * ```
  */
-interface AcqOrderExtSubscriptionInfo {
-    subscriptionId?: string;
-    periodNo?: number;
-    merchantRequest?: string;
-    subscriptionEvent?: string;
-    [key: string]: unknown;
+declare class ApiResponse<T> {
+    /** Response code. "0" indicates success, other values indicate errors. */
+    readonly code: string;
+    /** Response data (present when code is "0") */
+    readonly data?: T;
+    /** Error message (present when code is not "0") */
+    readonly message?: string;
+    private constructor();
+    /**
+     * Creates a successful response.
+     *
+     * @param data - The response data
+     */
+    static success<T>(data?: T): ApiResponse<T>;
+    /**
+     * Creates an error response.
+     *
+     * @param code - The error code
+     * @param message - The error message
+     */
+    static error<T>(code: string, message?: string): ApiResponse<T>;
+    /**
+     * Checks if the response indicates success.
+     *
+     * @returns true if the response code is "0"
+     */
+    isSuccess(): boolean;
+    /**
+     * Gets the response data.
+     *
+     * @returns The response data, or undefined if the response is an error
+     */
+    getData(): T | undefined;
+    /**
+     * Gets the error message.
+     *
+     * @returns The error message, or undefined if the response is successful
+     */
+    getMessage(): string | undefined;
+    /**
+     * Gets the response code.
+     *
+     * @returns The response code
+     */
+    getCode(): string;
+    /**
+     * Gets the response data or throws an error.
+     *
+     * @returns The response data
+     * @throws Error if the response is not successful or data is undefined
+     */
+    getDataOrThrow(): T;
 }
+
 /**
- * Tokenized card data used for direct card payment flows.
+ * HTTP client for making requests to the Waffo API.
+ *
+ * Handles:
+ * - Request signing with merchant's private key
+ * - Response signature verification with Waffo's public key
+ * - MerchantId auto-injection
+ * - Error handling and timeout management
  */
-interface WaffoTokenCardData {
-    cardBinDataList?: Record<string, unknown>[];
-    maskedCardInfo?: string;
-    cardBin?: string;
-    cardExpiry?: string;
-    [key: string]: unknown;
+declare class WaffoHttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly privateKey;
+    private readonly waffoPublicKey;
+    private readonly merchantId;
+    private readonly connectTimeout;
+    private readonly readTimeout;
+    private readonly logger?;
+    private readonly httpTransport;
+    constructor(config: WaffoConfig);
+    /**
+     * Sends a POST request to the Waffo API.
+     *
+     * @param path - API endpoint path (e.g., "/order/create")
+     * @param request - Request body
+     * @param options - Per-request options
+     * @returns API response
+     * @throws WaffoUnknownStatusError for network errors or unknown status
+     */
+    post<T extends object, R>(path: string, request: T, options?: RequestOptions): Promise<ApiResponse<R>>;
+    /**
+     * Parses the API response body.
+     */
+    private parseResponse;
+    /**
+     * Auto-injects merchantId into the request if configured.
+     */
+    private injectMerchantIdIfNeeded;
+    /**
+     * Checks if the error is a network-related error.
+     */
+    private isNetworkError;
 }
+
 /**
- * Refund user information.
+ * Base class for API resources.
  */
-interface RefundUserInfo {
-    userType?: string;
-    userFirstName?: string;
-    userMiddleName?: string;
-    userLastName?: string;
-    nationality?: string;
-    userEmail?: string;
-    userPhone?: string;
-    userBirthDay?: string;
-    userIDType?: string;
-    userIDNumber?: string;
-    userIDIssueDate?: string;
-    userIDExpiryDate?: string;
-    userBankInfo?: RefundUserBankInfo;
-    [key: string]: unknown;
-}
-interface RefundUserBankInfo {
-    bankAccountNo?: string;
-    bankCode?: string;
-    bankName?: string;
-    bankCity?: string;
-    bankBranch?: string;
-    [key: string]: unknown;
+declare abstract class BaseResource {
+    protected readonly httpClient: WaffoHttpClient;
+    protected readonly basePath: string;
+    constructor(httpClient: WaffoHttpClient, basePath: string);
+    /**
+     * Gets the full path for an endpoint.
+     *
+     * @param endpoint - The endpoint (e.g., "/create")
+     * @returns Full path (e.g., "/order/create")
+     */
+    protected getPath(endpoint: string): string;
 }
 
 /**
@@ -2145,6 +2202,69 @@ declare class PayMethodConfigResource extends BaseResource {
     inquiry(params: InquiryPayMethodConfigParams, options?: RequestOptions): Promise<ApiResponse<InquiryPayMethodConfigData>>;
 }
 
+/**
+ * Wallet-related type definitions.
+ *
+ * Note: Full type definitions should be generated from openapi.json.
+ * These are placeholder interfaces for the SDK structure.
+ */
+
+/**
+ * Wallet inquiry request parameters (x402 stablecoin receiving-address inquiry).
+ * Based on openapi.json WalletInquiryReq schema.
+ *
+ * Note: `merchantInfo` is auto-injected by the HTTP client before signing,
+ * so it is optional in the public surface.
+ */
+interface WalletInquiryParams {
+    paymentRequestId: string;
+    merchantInfo?: MerchantInfo;
+    orderCurrency: string;
+    [key: string]: unknown;
+}
+/**
+ * Wallet inquiry response data.
+ * Based on openapi.json WalletInquiryResponse schema.
+ */
+interface WalletInquiryData {
+    network?: string;
+    asset?: string;
+    payTo?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Wallet resource for x402 stablecoin receiving-address inquiry.
+ *
+ * @example
+ * ```typescript
+ * // Inquire the stablecoin receiving address
+ * const response = await waffo.wallet().inquiry({
+ *   paymentRequestId: 'unique-request-id',
+ *   orderCurrency: 'USDC',
+ * });
+ *
+ * if (response.isSuccess()) {
+ *   const data = response.getData();
+ *   console.log('Network:', data?.network);
+ *   console.log('Asset:', data?.asset);
+ *   console.log('Pay to:', data?.payTo);
+ * }
+ * ```
+ */
+declare class WalletResource extends BaseResource {
+    private static readonly PATH_INQUIRY;
+    /**
+     * Inquires the stablecoin receiving address for an x402 payment.
+     *
+     * @param params - Wallet inquiry parameters
+     * @param options - Optional request options
+     * @returns API response with wallet data
+     * @throws WaffoUnknownStatusError for network errors
+     */
+    inquiry(params: WalletInquiryParams, options?: RequestOptions): Promise<ApiResponse<WalletInquiryData>>;
+}
+
 /**
  * Main entry point for the Waffo SDK.
  *
@@ -2193,6 +2313,7 @@ declare class Waffo {
     private _refund?;
     private _merchantConfig?;
     private _payMethodConfig?;
+    private _wallet?;
     /**
      * Creates a new Waffo SDK instance.
      *
@@ -2246,6 +2367,12 @@ declare class Waffo {
      * @returns Pay method config resource
      */
     payMethodConfig(): PayMethodConfigResource;
+    /**
+     * Returns the wallet resource for x402 stablecoin receiving-address inquiry.
+     *
+     * @returns Wallet resource
+     */
+    wallet(): WalletResource;
     /**
      * Creates a webhook handler for processing Waffo webhook notifications.
      *
@@ -2481,4 +2608,4 @@ declare const RsaUtils: {
     generateKeyPair: typeof generateKeyPair;
 };
 
-export { type AddressInfo, ApiResponse, type BaseNotification, type CancelOrderData, type CancelOrderParams, type CancelSubscriptionData, type CancelSubscriptionParams, type CaptureOrderData, type CaptureOrderParams, type CardInfo, type CreateOrderData, type CreateOrderParams, type CreateSubscriptionData, type CreateSubscriptionParams, Environment, EnvironmentBaseUrl, type FixedMaintenanceRule, type GoodsInfo, type HttpRequest, type HttpResponse, type HttpTransport, type InquiryMerchantConfigData, type InquiryMerchantConfigParams, type InquiryOrderData, type InquiryOrderParams, type InquiryPayMethodConfigData, type InquiryPayMethodConfigParams, type InquiryRefundData, type InquiryRefundParams, type InquirySubscriptionData, type InquirySubscriptionParams, type ManageSubscriptionData, type ManageSubscriptionParams, MerchantConfigResource, type MerchantInfo, OrderResource, type OrderStatus, PayMethodConfigResource, type PayMethodDetail, type PayMethodInfo, type PaymentInfo, type PaymentNotification, type PaymentNotificationResult, type PeriodType, type ProductInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionChangeData, type SubscriptionChangeInquiryData, type SubscriptionChangeInquiryParams, type SubscriptionChangeParams, type SubscriptionChangeProductInfo, type SubscriptionChangeStatus, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentDetail, type SubscriptionPaymentInfo, type SubscriptionPeriodChangedNotification, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, WebhookEventType, WebhookHandler, type WebhookResult };
+export { type AddressInfo, ApiResponse, type BaseNotification, type CancelOrderData, type CancelOrderParams, type CancelSubscriptionData, type CancelSubscriptionParams, type CaptureOrderData, type CaptureOrderParams, type CardInfo, type CreateOrderData, type CreateOrderParams, type CreateSubscriptionData, type CreateSubscriptionParams, Environment, EnvironmentBaseUrl, type FixedMaintenanceRule, type GoodsInfo, type HttpRequest, type HttpResponse, type HttpTransport, type InquiryMerchantConfigData, type InquiryMerchantConfigParams, type InquiryOrderData, type InquiryOrderParams, type InquiryPayMethodConfigData, type InquiryPayMethodConfigParams, type InquiryRefundData, type InquiryRefundParams, type InquirySubscriptionData, type InquirySubscriptionParams, type ManageSubscriptionData, type ManageSubscriptionParams, MerchantConfigResource, type MerchantInfo, OrderResource, type OrderStatus, PayMethodConfigResource, type PayMethodDetail, type PayMethodInfo, type PaymentInfo, type PaymentNotification, type PaymentNotificationResult, type PeriodType, type ProductInfo, type PromotionInfo, type RefundNotification, type RefundNotificationResult, type RefundOrderData, type RefundOrderParams, RefundResource, type RefundStatus$1 as RefundStatus, type RefundUserInfo, type RequestOptions, type RiskData, RsaUtils, type SubscriptionChangeData, type SubscriptionChangeInquiryData, type SubscriptionChangeInquiryParams, type SubscriptionChangeParams, type SubscriptionChangeProductInfo, type SubscriptionChangeStatus, type SubscriptionInfo, type SubscriptionManageAction, type SubscriptionMerchantInfo, type SubscriptionNotificationResult, type SubscriptionPaymentDetail, type SubscriptionPaymentInfo, type SubscriptionPeriodChangedNotification, type SubscriptionPromotionInfo, SubscriptionResource, type SubscriptionScheduledAmount, type SubscriptionStatus, type SubscriptionStatusNotification, type SubscriptionUpdateProductInfo, type SubscriptionUserInfo, type UpdateSubscriptionData, type UpdateSubscriptionParams, type UserInfo, Waffo, type WaffoConfig, WaffoConfigDefaults, WaffoError, WaffoErrorCode, WaffoHttpClient, type WaffoLogger, WaffoUnknownStatusError, type WalletInquiryData, type WalletInquiryParams, WalletResource, WebhookEventType, WebhookHandler, type WebhookResult, type X402Info };