@waffo/waffo-node 2.5.0 → 2.6.0

package/dist/index.d.ts

@@ -119,7 +119,7 @@ interface WaffoLogger {
 interface WaffoConfig {
     /** API key provided by Waffo */
     apiKey: string;
-    /** Merchant's private key for signing requests (Base64 encoded PKCS8) */
+    /** Merchant's private key for signing requests (Base64 PKCS8 DER or unencrypted PKCS8 PEM) */
     privateKey: string;
     /** Waffo's public key for verifying responses (Base64 encoded X509) */
     waffoPublicKey: string;
@@ -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;
@@ -504,9 +522,11 @@ interface ProductInfo {
 interface SubscriptionUserInfo {
     userId: string;
     userEmail: string;
+    userTerminal?: string;
     userPhone?: string;
     userFirstName?: string;
     userLastName?: string;
+    userCreatedAt?: string;
     userCountryCode?: string;
     userBrowserIp?: string;
     userAgent?: string;
@@ -519,12 +539,23 @@ interface SubscriptionPaymentInfo {
     productName: string;
     payMethodType?: string;
     payMethodName?: string;
+    payMethodProperties?: string;
+    payMethodUserAccountType?: string;
+    payMethodUserAccountNo?: string;
+    payMethodUserAccessToken?: string;
+    cashierLanguage?: string;
+    cashierAppearance?: string;
     [key: string]: unknown;
 }
 /**
  * Address information for subscription.
  */
 interface SubscriptionAddressInfo {
+    address?: string;
+    city?: string;
+    region?: string;
+    postcode?: string;
+    addressCountryCode?: string;
     shippingAddress?: {
         country?: string;
         state?: string;
@@ -549,6 +580,14 @@ interface SubscriptionAddressInfo {
  * Risk data for subscription.
  */
 interface SubscriptionRiskData {
+    userType?: string;
+    userCategory?: string;
+    userLegalName?: string;
+    userDisplayName?: string;
+    userRegistrationIp?: string;
+    userLastSeenIp?: string;
+    userIsNew?: string;
+    userIsFirstPurchase?: string;
     deviceType?: string;
     deviceId?: string;
     deviceTokenId?: string;
@@ -658,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).
      */
@@ -678,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.
      */
@@ -913,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.
      */
@@ -981,699 +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;
+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.
+ */
+interface UserInfo {
+    userId: string;
+    userEmail: string;
+    userPhone?: string;
+    userFirstName?: string;
+    userLastName?: string;
+    userCreatedAt?: string;
+    userTerminal?: string;
+    userCountryCode?: string;
+    userBrowserIp?: string;
+    userAgent?: string;
+    /**
+     * User receipt URL (max 256 characters).
+     */
+    userReceiptUrl?: string;
     [key: string]: unknown;
 }
 /**
- * Subscription change notification from Waffo.
+ * Payment information.
  */
-interface SubscriptionChangeNotification extends BaseNotification {
-    eventType: 'SUBSCRIPTION_CHANGE_NOTIFICATION';
-    result?: SubscriptionChangeNotificationResult;
+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;
 }
-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>;
 /**
- * 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);
- * });
- * ```
+ * Merchant 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;
-    };
-    /**
-     * Builds a failed response with signature.
-     */
-    buildFailedResponse(_message: string): {
-        body: string;
-        signature: string;
-    };
-    private createSuccessResult;
-    private createFailedResult;
+interface MerchantInfo {
+    merchantId: string;
+    subMerchantId?: 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()}`);
- * }
- * ```
+ * Goods 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 GoodsInfo {
+    goodsId?: string;
+    goodsName?: string;
+    goodsCategory?: string;
+    goodsUrl?: string;
+    appName?: string;
+    skuName?: string;
+    goodsUniquePrice?: string;
+    goodsQuantity?: number;
+    [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
+ * Address 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 AddressInfo {
+    address?: string;
+    city?: string;
+    region?: string;
+    postcode?: string;
+    addressCountryCode?: string;
+    [key: string]: unknown;
 }
-
 /**
- * Base class for API resources.
+ * Card 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 CardInfo {
+    cardNumber?: string;
+    cardExpiryYear?: number;
+    cardExpiryMonth?: number;
+    cardCvv?: string;
+    cardHolderName?: string;
+    threeDsDecision?: string;
+    [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.
+ * Risk data.
  */
-
+interface RiskData {
+    userType?: string;
+    userCategory?: string;
+    userLegalName?: string;
+    userDisplayName?: string;
+    userRegistrationIp?: string;
+    userLastSeenIp?: string;
+    userIsNew?: string;
+    userIsFirstPurchase?: string;
+    [key: string]: unknown;
+}
 /**
- * Create order request parameters.
+ * Payment token data.
  */
-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 PaymentTokenData {
+    tokenId?: string;
     [key: string]: unknown;
 }
 /**
- * Create order response data.
+ * Brand display information for cashier.
  */
-interface CreateOrderData {
-    paymentRequestId?: string;
-    merchantOrderId?: string;
-    acquiringOrderId?: string;
-    orderStatus?: OrderStatus;
-    orderAction?: string;
+interface BrandInfo {
+    cashierLogoUrl?: string;
+    cashierDisplayName?: string;
+    cashierProductImageUrl?: string;
     [key: string]: unknown;
 }
 /**
- * Inquiry order request parameters.
- * Provide paymentRequestId or acquiringOrderId.
+ * @deprecated Legacy order extension retained for source compatibility.
  */
-interface InquiryOrderParams {
-    paymentRequestId?: string;
-    acquiringOrderId?: string;
+interface ProductDetail {
+    subscriptionInfo?: SubscriptionInfo;
     [key: string]: unknown;
 }
 /**
- * Inquiry order response data.
+ * @deprecated Legacy subscription extension retained for source compatibility.
  */
-interface InquiryOrderData {
+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;
-    captureMode?: 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;
 }
 
 /**
@@ -2019,7 +2106,6 @@ interface InquiryMerchantConfigData {
  */
 interface InquiryPayMethodConfigParams {
     merchantId: string;
-    payMethodType?: string;
     [key: string]: unknown;
 }
 /**
@@ -2027,21 +2113,33 @@ interface InquiryPayMethodConfigParams {
  */
 interface InquiryPayMethodConfigData {
     merchantId?: string;
-    payMethods?: PayMethodInfo[];
+    payMethodDetails?: PayMethodDetail[];
     [key: string]: unknown;
 }
 /**
- * Pay method information.
+ * Pay method detail.
  */
-interface PayMethodInfo {
-    payMethodType?: string;
+interface PayMethodDetail {
+    productName?: string;
     payMethodName?: string;
-    payMethodStatus?: string;
-    supportedCurrencies?: string[];
-    minAmount?: string;
-    maxAmount?: string;
+    country?: string;
+    currentStatus?: string;
+    fixedMaintenanceRules?: FixedMaintenanceRule[];
+    fixedMaintenanceTimezone?: string;
     [key: string]: unknown;
 }
+/**
+ * Fixed maintenance rule for a payment method.
+ */
+interface FixedMaintenanceRule {
+    startRule?: string;
+    endRule?: string;
+    [key: string]: unknown;
+}
+/**
+ * @deprecated Use PayMethodDetail.
+ */
+type PayMethodInfo = PayMethodDetail;
 
 /**
  * Merchant config resource for querying merchant configuration.
@@ -2085,8 +2183,8 @@ declare class MerchantConfigResource extends BaseResource {
  *
  * if (response.isSuccess()) {
  *   const data = response.getData();
- *   data?.payMethods?.forEach(method => {
- *     console.log(`${method.payMethodName}: ${method.payMethodStatus}`);
+ *   data?.payMethodDetails?.forEach(method => {
+ *     console.log(`${method.payMethodName}: ${method.currentStatus}`);
  *   });
  * }
  * ```
@@ -2104,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.
  *
@@ -2152,6 +2313,7 @@ declare class Waffo {
     private _refund?;
     private _merchantConfig?;
     private _payMethodConfig?;
+    private _wallet?;
     /**
      * Creates a new Waffo SDK instance.
      *
@@ -2205,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.
      *
@@ -2347,7 +2515,7 @@ declare class WaffoUnknownStatusError extends Error {
  * Result of key pair generation.
  */
 interface KeyPairResult {
-    /** Base64 encoded PKCS8 private key */
+    /** Base64 encoded PKCS8 DER private key */
     privateKey: string;
     /** Base64 encoded X509 public key */
     publicKey: string;
@@ -2356,16 +2524,16 @@ interface KeyPairResult {
  * Signs data using RSA-SHA256.
  *
  * @param data - The data to sign (UTF-8 string)
- * @param base64PrivateKey - Base64 encoded PKCS8 private key
+ * @param privateKeyInput - Base64 encoded PKCS8 DER private key or unencrypted PKCS8 PEM private key
  * @returns Base64 encoded signature
- * @throws WaffoError if signing fails (S0003)
+ * @throws WaffoError if the private key is invalid (S0007) or signing fails (S0003)
  *
  * @example
  * ```typescript
  * const signature = sign('{"amount":"100.00"}', privateKey);
  * ```
  */
-declare function sign(data: string, base64PrivateKey: string): string;
+declare function sign(data: string, privateKeyInput: string): string;
 /**
  * Verifies a signature using RSA-SHA256.
  *
@@ -2384,12 +2552,12 @@ declare function sign(data: string, base64PrivateKey: string): string;
  */
 declare function verify(data: string, base64Signature: string, base64PublicKey: string): boolean;
 /**
- * Validates a Base64 encoded PKCS8 private key.
+ * Validates a Base64 encoded PKCS8 DER private key or unencrypted PKCS8 PEM private key.
  *
  * This method attempts to parse the key to ensure it's a valid RSA private key.
  * Use this at startup to fail fast if the private key is invalid.
  *
- * @param base64PrivateKey - Base64 encoded PKCS8 private key
+ * @param base64PrivateKey - Base64 encoded PKCS8 DER private key or unencrypted PKCS8 PEM private key
  * @throws WaffoError if the key is invalid (S0007)
  *
  * @example
@@ -2440,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 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 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 };