@waffo/waffo-node 2.0.3 → 2.0.4

package/README.md

@@ -1,588 +1,1261 @@
 # Waffo Node.js SDK
 
-[![npm version](https://img.shields.io/npm/v/@waffo/waffo-node.svg)](https://www.npmjs.com/package/@waffo/waffo-node)
-[![npm downloads](https://img.shields.io/npm/dm/@waffo/waffo-node.svg)](https://www.npmjs.com/package/@waffo/waffo-node)
-[![license](https://img.shields.io/npm/l/@waffo/waffo-node.svg)](https://github.com/AcquireNow/waffo-node/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+<!-- Synced with waffo-sdk/README.md @ commit 9971ef7 -->
+
+**English** | [中文](README_CN.md)
 
-Official Node.js SDK for Waffo acquiring services. This SDK provides secure API communication with RSA signing and comprehensive type definitions for payment acquiring operations.
+[![npm version](https://img.shields.io/npm/v/@waffo/waffo-node.svg)](https://www.npmjs.com/package/@waffo/waffo-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/node/v/@waffo/waffo-node.svg)](https://nodejs.org)
+
+Official Node.js/TypeScript SDK for [Waffo Payment Platform](https://www.waffo.com), providing one-stop global payment solutions for AI products, SaaS services, and more.
+
+## Introduction
+
+### Core Features
+
+- **Global Payments**: Support for credit cards, debit cards, e-wallets, virtual accounts, and more payment methods covering mainstream global payment channels
+- **Subscription Management**: Complete subscription lifecycle management with trial periods, recurring billing, and subscription upgrades/downgrades
+- **Refund Processing**: Flexible full/partial refund capabilities with refund status tracking
+- **Webhook Notifications**: Real-time payment result push notifications for payments, refunds, subscription status changes, and more
+- **Security & Reliability**: PCI DSS certified, RSA signature verification, enforced TLS 1.2+ encryption
+
+### Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **AI Products** | ChatGPT-like applications, AI writing tools, AI image generation with usage-based billing or subscriptions |
+| **SaaS Services** | Enterprise software subscriptions, online collaboration tools, cloud services with periodic payments |
+| **Content Platforms** | Membership subscriptions, paid content, tipping scenarios |
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Framework Integration](#framework-integration)
+- [API Usage](#api-usage)
+  - [Order Management](#order-management)
+  - [Subscription Management](#subscription-management)
+  - [Refund Query](#refund-query)
+  - [Merchant Configuration](#merchant-configuration)
+- [Webhook Handling](#webhook-handling)
+- [Payment Method Types](#payment-method-types)
+- [Advanced Configuration](#advanced-configuration)
+  - [Custom HTTP Transport](#custom-http-transport-axios)
+  - [TLS Security Configuration](#tls-security-configuration)
+  - [Debug Logging](#debug-logging)
+- [Error Handling](#error-handling)
+- [TypeScript Support](#typescript-support)
+- [Development & Testing](#development--testing)
+- [Support](#support)
+- [License](#license)
+
+## Requirements
+
+- Node.js >= 18.0.0
+- npm, yarn, or pnpm
+
+### Version Compatibility
+
+| Node.js Version | Support Status |
+|-----------------|----------------|
+| 22.x | ✅ Fully Supported |
+| 20.x LTS | ✅ Fully Supported (Recommended) |
+| 18.x LTS | ✅ Fully Supported |
+| < 18.x | ❌ Not Supported |
 
-**npm**: https://www.npmjs.com/package/@waffo/waffo-node
+## Installation
 
-**Language**: [English](./README.md) | [中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+```bash
+npm install @waffo/waffo-node
+# or
+yarn add @waffo/waffo-node
+# or
+pnpm add @waffo/waffo-node
+```
 
 ## Quick Start
 
+### 1. Initialize the SDK
+
 ```typescript
-import {
-  Waffo,
-  Environment,
-  CurrencyCode,
-  ProductName,
-} from '@waffo/waffo-node';
+import { Waffo, Environment } from '@waffo/waffo-node';
 
-// 1. Initialize SDK
 const waffo = new Waffo({
   apiKey: 'your-api-key',
   privateKey: 'your-base64-encoded-private-key',
-  environment: Environment.SANDBOX,
+  waffoPublicKey: 'waffo-public-key',  // From Waffo Dashboard
+  merchantId: 'your-merchant-id',       // Auto-injected into requests
+  environment: Environment.SANDBOX,     // SANDBOX or PRODUCTION
 });
+```
+
+### 2. Create a Payment Order
 
-// 2. Create an order
-const result = await waffo.order.create({
-  paymentRequestId: 'REQ_001',
-  merchantOrderId: 'ORDER_001',
-  orderCurrency: CurrencyCode.IDR,
-  orderAmount: '100000',
-  orderDescription: 'Product purchase',
-  notifyUrl: 'https://merchant.com/notify',
-  merchantInfo: { merchantId: 'your-merchant-id' },
+```typescript
+import { randomUUID } from 'crypto';
+
+// Generate idempotency key (max 32 chars)
+const paymentRequestId = randomUUID().replace(/-/g, '');
+// Important: Persist this ID to database for retry and query
+
+const response = await waffo.order().create({
+  paymentRequestId,
+  merchantOrderId: `ORDER_${Date.now()}`,
+  orderCurrency: 'HKD',
+  orderAmount: '100.00',
+  orderDescription: 'Test Product',
+  notifyUrl: 'https://your-site.com/webhook',
   userInfo: {
-    userId: 'user_001',
+    userId: 'user_123',
     userEmail: 'user@example.com',
+    userTerminal: 'WEB',
   },
   paymentInfo: {
-    productName: ProductName.ONE_TIME_PAYMENT,
-    payMethodType: 'EWALLET',
-    payMethodName: 'DANA',
+    productName: 'ONE_TIME_PAYMENT',
+  },
+  goodsInfo: {
+    goodsUrl: 'https://your-site.com/product/001',
   },
 });
 
-// 3. Handle response
-if (result.success) {
-  console.log('Order created:', result.data);
-  // Redirect user to payment page
-  if (result.data?.orderAction) {
-    const action = JSON.parse(result.data.orderAction);
-    window.location.href = action.webUrl;
-  }
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Redirect URL:', data.orderAction);
+  console.log('Acquiring Order ID:', data.acquiringOrderId);
+  console.log('Order Status:', data.orderStatus);
+} else {
+  console.log('Error:', response.getMessage());
 }
 ```
 
-> **Tip**: Need to generate a new RSA key pair? Use `Waffo.generateKeyPair()` to create one:
-> ```typescript
-> const keyPair = Waffo.generateKeyPair();
-> console.log(keyPair.privateKey); // Keep this secure, use for SDK initialization
-> console.log(keyPair.publicKey);  // Share this with Waffo
-> ```
-
-## Features
-
-- RSA-2048 request signing and response verification
-- Full TypeScript support with comprehensive type definitions
-- Zero production dependencies (uses only Node.js built-in `crypto` module)
-- Support for Sandbox and Production environments
-- Dual ESM/CommonJS module support
-- Order management (create, query, cancel, refund, capture)
-- Subscription management (create, query, cancel, manage)
-- Refund status inquiry
-- Merchant configuration inquiry (transaction limits, daily limits)
-- Payment method configuration inquiry (availability, maintenance schedules)
-- Webhook handler with automatic signature verification and event routing
-- Webhook signature verification utilities
-- Direct HTTP client access for custom API requests
-- Automatic timestamp defaults for request parameters
-
-## Automatic Timestamp Defaults
-
-All timestamp parameters (`orderRequestedAt`, `requestedAt`, `captureRequestedAt`) are **optional** and will automatically default to the current time (`new Date().toISOString()`) if not provided:
-
-```typescript
-// Timestamp is automatically set to current time
-await waffo.order.create({
-  paymentRequestId: 'REQ_001',
-  merchantOrderId: 'ORDER_001',
-  // ... other required fields
-  // orderRequestedAt is automatically set
-});
+### 3. Query Order Status
 
-// Or explicitly provide a custom timestamp
-await waffo.order.create({
-  paymentRequestId: 'REQ_001',
-  merchantOrderId: 'ORDER_001',
-  orderRequestedAt: '2025-01-01T00:00:00.000Z', // Custom timestamp
-  // ... other required fields
+```typescript
+const response = await waffo.order().inquiry({
+  acquiringOrderId: 'acquiring_order_id',
 });
+
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Order Status:', data.orderStatus);
+  console.log('Merchant Order ID:', data.merchantOrderId);
+  console.log('Order Amount:', data.orderAmount);
+  console.log('Order Currency:', data.orderCurrency);
+  // Tip: Verify amount and currency match your records
+}
 ```
 
-This applies to:
-- `CreateOrderParams.orderRequestedAt`
-- `CancelOrderParams.orderRequestedAt`
-- `RefundOrderParams.requestedAt`
-- `CaptureOrderParams.captureRequestedAt`
-- `CreateSubscriptionParams.requestedAt`
-- `CancelSubscriptionParams.requestedAt`
+## Configuration
 
-## Installation
+### Full Configuration Options
+
+```typescript
+import { Waffo, Environment } from '@waffo/waffo-node';
+
+const waffo = new Waffo({
+  // Required
+  apiKey: 'your-api-key',                    // API Key
+  privateKey: 'your-base64-private-key',     // Base64 encoded merchant private key
+  waffoPublicKey: 'waffo-public-key',        // Waffo public key (from Dashboard)
+  environment: Environment.SANDBOX,           // SANDBOX or PRODUCTION (required)
+
+  // Optional
+  merchantId: 'your-merchant-id',            // Default merchant ID (auto-injected)
+  connectTimeout: 10000,                     // Connection timeout in ms (default: 10000)
+  readTimeout: 30000,                        // Read timeout in ms (default: 30000)
+  logger: console,                           // Custom logger
+  httpTransport: customTransport,            // Custom HTTP transport
+});
+```
+
+### Environment Variables
 
 ```bash
-npm install @waffo/waffo-node
+# Set environment variables
+export WAFFO_API_KEY=your-api-key
+export WAFFO_PRIVATE_KEY=your-private-key
+export WAFFO_PUBLIC_KEY=waffo-public-key       # Waffo public key
+export WAFFO_ENVIRONMENT=SANDBOX               # Required: SANDBOX or PRODUCTION
+export WAFFO_MERCHANT_ID=your-merchant-id      # Optional
+```
+
+```typescript
+import { Waffo } from '@waffo/waffo-node';
+
+const waffo = Waffo.fromEnv();
 ```
 
-## Usage
+### Environment URLs
+
+| Environment | Base URL | Description |
+|-------------|----------|-------------|
+| `SANDBOX` | `https://api-sandbox.waffo.com` | Test environment |
+| `PRODUCTION` | `https://api.waffo.com` | Production environment |
+
+> **Important**: Environment must be explicitly specified. SDKs do not default to any environment to prevent accidental requests to wrong environments.
 
-### Initialize the SDK
+### Request-Level Configuration
 
 ```typescript
+const response = await waffo.order().create(params, {
+  connectTimeout: 10000,
+  readTimeout: 30000,
+});
+```
+
+### Framework Integration
+
+#### Express Integration
+
+```typescript
+import express from 'express';
 import { Waffo, Environment } from '@waffo/waffo-node';
 
+const app = express();
 const waffo = new Waffo({
-  apiKey: 'your-api-key',
-  privateKey: 'your-base64-encoded-private-key',
-  environment: Environment.SANDBOX, // or Environment.PRODUCTION
+  apiKey: process.env.WAFFO_API_KEY!,
+  privateKey: process.env.WAFFO_PRIVATE_KEY!,
+  waffoPublicKey: process.env.WAFFO_PUBLIC_KEY!,
+  environment: Environment.SANDBOX,
+});
+
+// Webhook endpoint
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  const body = req.body.toString();
+  const signature = req.headers['x-signature'] as string;
+
+  const webhookHandler = waffo.webhook()
+    .onPayment((notification) => {
+      console.log('Payment received:', notification.acquiringOrderId);
+    });
+
+  const result = await webhookHandler.handleWebhook(body, signature);
+  res.setHeader('X-SIGNATURE', result.responseSignature);
+  res.status(200).json(result.responseBody);
 });
+
+app.listen(3000);
 ```
 
-### Generate RSA Key Pair
+#### NestJS Integration
 
 ```typescript
+// waffo.module.ts
+import { Module, Global } from '@nestjs/common';
+import { Waffo, Environment } from '@waffo/waffo-node';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: 'WAFFO',
+      useFactory: () => {
+        return new Waffo({
+          apiKey: process.env.WAFFO_API_KEY!,
+          privateKey: process.env.WAFFO_PRIVATE_KEY!,
+          waffoPublicKey: process.env.WAFFO_PUBLIC_KEY!,
+          environment: Environment.SANDBOX,
+        });
+      },
+    },
+  ],
+  exports: ['WAFFO'],
+})
+export class WaffoModule {}
+
+// payment.controller.ts
+import { Controller, Post, Body, Headers, Inject, Res } from '@nestjs/common';
 import { Waffo } from '@waffo/waffo-node';
+import { Response } from 'express';
+
+@Controller('payment')
+export class PaymentController {
+  constructor(@Inject('WAFFO') private readonly waffo: Waffo) {}
+
+  @Post('webhook')
+  async handleWebhook(
+    @Body() body: string,
+    @Headers('x-signature') signature: string,
+    @Res() res: Response,
+  ) {
+    const webhookHandler = this.waffo.webhook()
+      .onPayment((notification) => {
+        console.log('Payment received:', notification.acquiringOrderId);
+      });
+
+    const result = await webhookHandler.handleWebhook(body, signature);
+    res.setHeader('X-SIGNATURE', result.responseSignature);
+    res.status(200).json(result.responseBody);
+  }
+}
+```
+
+#### Fastify Integration
+
+```typescript
+import Fastify from 'fastify';
+import { Waffo, Environment } from '@waffo/waffo-node';
+
+const fastify = Fastify();
+const waffo = new Waffo({
+  apiKey: process.env.WAFFO_API_KEY!,
+  privateKey: process.env.WAFFO_PRIVATE_KEY!,
+  waffoPublicKey: process.env.WAFFO_PUBLIC_KEY!,
+  environment: Environment.SANDBOX,
+});
+
+// Register raw body parser for webhooks
+fastify.addContentTypeParser('application/json', { parseAs: 'string' }, (req, body, done) => {
+  done(null, body);
+});
+
+fastify.post('/webhook', async (request, reply) => {
+  const body = request.body as string;
+  const signature = request.headers['x-signature'] as string;
+
+  const webhookHandler = waffo.webhook()
+    .onPayment((notification) => {
+      console.log('Payment received:', notification.acquiringOrderId);
+    });
+
+  const result = await webhookHandler.handleWebhook(body, signature);
+  reply.header('X-SIGNATURE', result.responseSignature);
+  return result.responseBody;
+});
 
-const keyPair = Waffo.generateKeyPair();
-console.log(keyPair.privateKey); // Base64 encoded PKCS8 private key
-console.log(keyPair.publicKey);  // Base64 encoded X509 public key
+fastify.listen({ port: 3000 });
 ```
 
-### Create an Order
+## API Usage
+
+### Order Management
+
+#### Create Order
 
 ```typescript
-const result = await waffo.order.create({
-  paymentRequestId: 'REQ_001',
-  merchantOrderId: 'ORDER_001',
-  orderCurrency: CurrencyCode.IDR,
-  orderAmount: '100000',
-  orderDescription: 'Product purchase',
-  notifyUrl: 'https://merchant.com/notify',
+import { randomUUID } from 'crypto';
+
+const response = await waffo.order().create({
+  paymentRequestId: randomUUID().replace(/-/g, ''),  // Idempotency key, persist it
+  merchantOrderId: `ORDER_${Date.now()}`,
+  orderCurrency: 'BRL',  // Brazilian Real
+  orderAmount: '100.00',
+  orderDescription: 'Product Name',
+  orderRequestedAt: new Date().toISOString(),
   merchantInfo: {
     merchantId: 'your-merchant-id',
   },
   userInfo: {
-    userId: 'user_001',
+    userId: 'user_123',
     userEmail: 'user@example.com',
-    userPhone: '+62-81234567890',
-    userTerminal: UserTerminalType.WEB,
+    userTerminal: 'WEB',
   },
   paymentInfo: {
-    productName: ProductName.ONE_TIME_PAYMENT,
-    payMethodType: 'EWALLET',
-    payMethodName: 'DANA',
+    productName: 'ONE_TIME_PAYMENT',
+    payMethodType: 'CREDITCARD',  // CREDITCARD, DEBITCARD, EWALLET, VA, etc.
+    // payMethodName: 'CC_VISA',  // Optional: specify exact payment method
+  },
+  goodsInfo: {
+    goodsUrl: 'https://your-site.com/product/001',
   },
+  notifyUrl: 'https://your-site.com/webhook',
+  successRedirectUrl: 'https://your-site.com/success',
+  failedRedirectUrl: 'https://your-site.com/failed',
+  cancelRedirectUrl: 'https://your-site.com/cancel',
 });
 
-if (result.success) {
-  console.log('Order created:', result.data);
-} else {
-  console.error('Error:', result.error);
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Checkout URL:', data.orderAction);
 }
 ```
 
-### Query Order Status
+#### Combine Multiple Payment Methods
 
 ```typescript
-const result = await waffo.order.inquiry({
-  acquiringOrderId: 'A202512230000001',
-  // or use paymentRequestId: 'REQ_001'
-});
-
-if (result.success) {
-  console.log('Order status:', result.data?.orderStatus);
+// Allow user to choose between credit card or debit card
+paymentInfo: {
+  productName: 'ONE_TIME_PAYMENT',
+  payMethodType: 'CREDITCARD,DEBITCARD',  // Comma-separated for multiple types
 }
 ```
 
-### Cancel an Order
+#### Query Order
 
 ```typescript
-const result = await waffo.order.cancel({
-  acquiringOrderId: 'A202512230000001',
-  merchantId: 'your-merchant-id',
-  // orderRequestedAt is optional, defaults to current time
+const response = await waffo.order().inquiry({
+  acquiringOrderId: 'acquiring_order_id',
 });
 ```
 
-### Refund an Order
+#### Cancel Order
 
 ```typescript
-const result = await waffo.order.refund({
-  refundRequestId: 'REFUND_001',
-  acquiringOrderId: 'A202512230000001',
-  merchantId: 'your-merchant-id',
-  refundAmount: '50000',
-  refundReason: 'Customer requested refund',
-  refundNotifyUrl: 'https://merchant.com/refund-notify',
-  // requestedAt is optional, defaults to current time
+const response = await waffo.order().cancel({
+  acquiringOrderId: 'acquiring_order_id',
+  orderRequestedAt: new Date().toISOString(),
 });
 ```
 
-### Query Refund Status
+#### Refund Order
 
 ```typescript
-const result = await waffo.refund.inquiry({
-  refundRequestId: 'REFUND_001',
-  // or use acquiringRefundOrderId: 'R202512230000001'
-});
+import { randomUUID } from 'crypto';
 
-if (result.success) {
-  console.log('Refund status:', result.data?.refundStatus);
-}
+// Generate idempotency key (max 32 chars)
+const refundRequestId = randomUUID().replace(/-/g, '');
+// Important: Persist this ID for retry and query
+
+const response = await waffo.order().refund({
+  refundRequestId,
+  acquiringOrderId: 'acquiring_order_id',
+  refundAmount: '50.00',
+  refundReason: 'Customer requested refund',
+});
 ```
 
-### Capture a Pre-authorized Payment
+#### Capture Order
 
 ```typescript
-const result = await waffo.order.capture({
-  acquiringOrderId: 'A202512230000001',
-  merchantId: 'your-merchant-id',
-  captureAmount: '100000',
-  // captureRequestedAt is optional, defaults to current time
+// For pre-authorized payments
+const response = await waffo.order().capture({
+  paymentRequestId: 'unique-request-id',
+  merchantId: 'merchant-123',
+  captureAmount: '10.00',
 });
 ```
 
-### Create a Subscription
+### Subscription Management
+
+#### Create Subscription
 
 ```typescript
-const result = await waffo.subscription.create({
-  subscriptionRequest: 'SUB_REQ_001',
-  merchantSubscriptionId: 'MERCHANT_SUB_001',
-  currency: CurrencyCode.PHP,
-  amount: '100',
+import { randomUUID } from 'crypto';
+
+const subscriptionRequest = randomUUID().replace(/-/g, '');
+
+const response = await waffo.subscription().create({
+  subscriptionRequest,
+  merchantSubscriptionId: `MSUB_${Date.now()}`,
+  currency: 'HKD',
+  amount: '99.00',
+  payMethodType: 'CREDITCARD,DEBITCARD,APPLEPAY,GOOGLEPAY',
   productInfo: {
-    periodType: PeriodType.MONTHLY,
+    description: 'Monthly Subscription',
+    periodType: 'MONTHLY',
     periodInterval: '1',
-    numberOfPeriod: '12',
-    description: 'Monthly subscription',
-  },
-  paymentInfo: {
-    productName: ProductName.SUBSCRIPTION,
-    payMethodType: 'EWALLET',
-    payMethodName: 'GCASH',
   },
-  merchantInfo: { merchantId: 'your-merchant-id' },
   userInfo: {
-    userId: 'user_001',
+    userId: 'user_123',
     userEmail: 'user@example.com',
   },
-  goodsInfo: {
-    goodsId: 'GOODS_001',
-    goodsName: 'Premium Plan',
-  },
-  notifyUrl: 'https://merchant.com/subscription/notify',
-  // requestedAt is optional, defaults to current time
+  requestedAt: new Date().toISOString(),
+  successRedirectUrl: 'https://your-site.com/subscription/success',
+  failedRedirectUrl: 'https://your-site.com/subscription/failed',
+  cancelRedirectUrl: 'https://your-site.com/subscription/cancel',
+  notifyUrl: 'https://your-site.com/webhook/subscription',
+  subscriptionManagementUrl: 'https://your-site.com/subscription/manage',
 });
 
-if (result.success) {
-  console.log('Subscription created:', result.data);
-  // Redirect user to complete subscription signing
-  if (result.data?.subscriptionAction?.webUrl) {
-    window.location.href = result.data.subscriptionAction.webUrl;
-  }
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Waffo Subscription ID:', data.subscriptionId);
+  console.log('Status:', data.subscriptionStatus);
+  console.log('Action:', data.subscriptionAction);
 }
 ```
 
-### Query Subscription Status
+#### Subscription with Trial Period
 
 ```typescript
-const result = await waffo.subscription.inquiry({
-  merchantId: 'your-merchant-id',
-  subscriptionId: 'SUB_202512230000001',
-  paymentDetails: '1', // Include payment history
+productInfo: {
+  description: 'Monthly subscription with 7-day free trial',
+  periodType: 'MONTHLY',
+  periodInterval: '1',
+  numberOfPeriod: '12',
+  // Trial period configuration
+  trialPeriodType: 'DAILY',
+  trialPeriodInterval: '7',
+  trialPeriodAmount: '0',  // Free trial
+  numberOfTrialPeriod: '1',
+}
+```
+
+#### Query Subscription
+
+```typescript
+// Query by subscriptionId
+const response = await waffo.subscription().inquiry({
+  subscriptionId: 'subscription_id',
+  paymentDetails: 1,  // 1: include payment details, 0: exclude
 });
 
-if (result.success) {
-  console.log('Subscription status:', result.data?.subscriptionStatus);
-}
+// Or query by subscriptionRequest
+const response = await waffo.subscription().inquiry({
+  subscriptionRequest: 'subscription_request',
+});
 ```
 
-### Cancel a Subscription
+#### Cancel Subscription
 
 ```typescript
-const result = await waffo.subscription.cancel({
-  merchantId: 'your-merchant-id',
-  subscriptionId: 'SUB_202512230000001',
-  // requestedAt is optional, defaults to current time
+const response = await waffo.subscription().cancel({
+  subscriptionId: 'subscription_id',
 });
 ```
 
-### Get Subscription Management URL
+#### Get Subscription Management URL
 
 ```typescript
-const result = await waffo.subscription.manage({
-  subscriptionId: 'SUB_202512230000001',
-  // or use subscriptionRequest: 'SUB_REQ_001'
+const response = await waffo.subscription().manage({
+  subscriptionId: 'subscription_id',
 });
 
-if (result.success) {
-  console.log('Management URL:', result.data?.managementUrl);
-  console.log('Expires at:', result.data?.expiresAt);
-  // Redirect user to manage their subscription
-  window.location.href = result.data?.managementUrl;
+if (response.isSuccess()) {
+  const managementUrl = response.getData().managementUrl;
+  // Redirect user to this URL to manage subscription
+}
+```
+
+### Subscription Change (Upgrade/Downgrade)
+
+Change an existing subscription to a new plan (upgrade or downgrade).
+
+#### Change Subscription
+
+```typescript
+import { randomUUID } from 'crypto';
+import { WaffoUnknownStatusError } from '@waffo/waffo-node';
+
+// New subscription request ID for the change
+const subscriptionRequest = randomUUID().replace(/-/g, '');
+const originSubscriptionRequest = 'original-subscription-request-id';
+
+try {
+  const response = await waffo.subscription().change({
+    subscriptionRequest,
+    originSubscriptionRequest,
+    remainingAmount: '50.00',  // Remaining value from original subscription
+    currency: 'HKD',
+    requestedAt: new Date().toISOString(),
+    notifyUrl: 'https://your-site.com/webhook/subscription',
+    productInfoList: [
+      {
+        description: 'Yearly Premium Subscription',
+        periodType: 'YEAR',
+        periodInterval: '1',
+        amount: '999.00',
+      },
+    ],
+    userInfo: {
+      userId: 'user_123',
+      userEmail: 'user@example.com',
+    },
+    goodsInfo: {
+      goodsId: 'GOODS_PREMIUM',
+      goodsName: 'Premium Plan',
+    },
+    paymentInfo: {
+      productName: 'SUBSCRIPTION',
+    },
+    // Optional fields
+    merchantSubscriptionId: `MSUB_UPGRADE_${Date.now()}`,
+    successRedirectUrl: 'https://your-site.com/subscription/upgrade/success',
+    failedRedirectUrl: 'https://your-site.com/subscription/upgrade/failed',
+    cancelRedirectUrl: 'https://your-site.com/subscription/upgrade/cancel',
+    subscriptionManagementUrl: 'https://your-site.com/subscription/manage',
+  });
+
+  if (response.isSuccess()) {
+    const data = response.getData();
+    console.log('Change Status:', data.subscriptionChangeStatus);
+    console.log('New Subscription ID:', data.subscriptionId);
+
+    // Handle different statuses
+    if (data.subscriptionChangeStatus === 'AUTHORIZATION_REQUIRED') {
+      // User needs to authorize the change
+      const action = JSON.parse(data.subscriptionAction);
+      console.log('Redirect user to:', action.webUrl);
+    } else if (data.subscriptionChangeStatus === 'SUCCESS') {
+      // Change completed successfully
+      console.log('Subscription upgraded successfully');
+    }
+  }
+} catch (error) {
+  if (error instanceof WaffoUnknownStatusError) {
+    // Status unknown - DO NOT assume failure! User may have completed payment
+    console.error('Unknown status, need to query:', error.message);
+
+    // Correct handling: Call inquiry API to confirm actual status
+    const inquiryResponse = await waffo.subscription().changeInquiry({
+      subscriptionRequest,
+      originSubscriptionRequest,
+    });
+    // Or wait for Webhook callback
+  } else {
+    throw error;
+  }
 }
 ```
 
-### Query Merchant Configuration
+#### Subscription Change Status Values
+
+| Status | Description |
+|--------|-------------|
+| `IN_PROGRESS` | Change is being processed |
+| `AUTHORIZATION_REQUIRED` | User needs to authorize the change (redirect to webUrl) |
+| `SUCCESS` | Change completed successfully |
+| `CLOSED` | Change was closed (timeout or failed) |
+
+#### Query Subscription Change Status
 
 ```typescript
-const result = await waffo.merchantConfig.inquiry({
-  merchantId: 'your-merchant-id',
+const response = await waffo.subscription().changeInquiry({
+  subscriptionRequest: 'new-subscription-request-id',
+  originSubscriptionRequest: 'original-subscription-request-id',
 });
 
-if (result.success) {
-  console.log('Daily Limit:', result.data?.totalDailyLimit);
-  console.log('Remaining Daily Limit:', result.data?.remainingDailyLimit);
-  console.log('Transaction Limit:', result.data?.transactionLimit);
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Change Status:', data.subscriptionChangeStatus);
+  console.log('New Subscription ID:', data.subscriptionId);
+  console.log('Remaining Amount:', data.remainingAmount);
+  console.log('Currency:', data.currency);
 }
 ```
 
-### Query Payment Method Configuration
+### Refund Query
 
 ```typescript
-const result = await waffo.payMethodConfig.inquiry({
-  merchantId: 'your-merchant-id',
+// Query by refundRequestId (merchant-generated idempotency key)
+const response = await waffo.refund().inquiry({
+  refundRequestId: 'refund_request_id',
 });
 
-if (result.success) {
-  result.data?.payMethodDetails.forEach(method => {
-    console.log(`${method.payMethodName}: ${method.currentStatus === '1' ? 'Available' : 'Unavailable'}`);
-    if (method.fixedMaintenanceRules) {
-      console.log('Maintenance periods:', method.fixedMaintenanceRules);
-    }
-  });
+// Or query by acquiringRefundOrderId (Waffo refund order ID)
+const response = await waffo.refund().inquiry({
+  acquiringRefundOrderId: 'acquiring_refund_order_id',
+});
+```
+
+### Merchant Configuration
+
+#### Query Merchant Configuration
+
+```typescript
+// merchantId is auto-injected from config if not provided
+const response = await waffo.merchantConfig().inquiry({});
+
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Daily Limit:', data.totalDailyLimit);
+  console.log('Remaining Daily Limit:', data.remainingDailyLimit);
+  console.log('Transaction Limit:', data.transactionLimit);
+}
+```
+
+#### Query Available Payment Methods
+
+```typescript
+// merchantId is auto-injected from config if not provided
+const response = await waffo.payMethodConfig().inquiry({});
+
+if (response.isSuccess()) {
+  const data = response.getData();
+  for (const detail of data.payMethodDetails) {
+    console.log(`Payment Method: ${detail.payMethodName}, Country: ${detail.country}, Status: ${detail.currentStatus}`);
+  }
 }
 ```
 
-### Webhook Handler
+## Webhook Handling
 
-The SDK provides a built-in webhook handler that automatically handles signature verification, event routing, and response signing:
+Waffo pushes payment results, refund results, subscription status changes, and more via webhooks.
+
+### Webhook Handler Example
 
 ```typescript
-// In your webhook handler
-app.post('/webhook', async (req, res) => {
-  const signature = req.headers['x-signature'] as string;
-  const body = JSON.stringify(req.body);
+import { Waffo, Environment } from '@waffo/waffo-node';
+import express from 'express';
 
-  const result = await waffo.webhook.handle(body, signature, {
-    onPayment: async ({ notification }) => {
-      console.log('Payment status:', notification.result.orderStatus);
-      // Process payment notification
-    },
-    onRefund: async ({ notification }) => {
-      console.log('Refund status:', notification.result.refundStatus);
-      // Process refund notification
-    },
-    onSubscriptionStatus: async ({ notification }) => {
-      console.log('Subscription status:', notification.result.subscriptionStatus);
-      // Process subscription status change
-    },
-    onSubscriptionPayment: async ({ notification }) => {
-      console.log('Subscription payment:', notification.result.orderStatus);
-      // Process subscription recurring payment
-    },
-    onError: async (error) => {
-      console.error('Webhook error:', error.message);
-    },
+const app = express();
+const waffo = new Waffo({ /* config */ });
+
+// Create webhook handler
+const webhookHandler = waffo.webhook()
+  .onPayment((notification) => {
+    console.log('Payment notification received:');
+    console.log('  Acquiring Order ID:', notification.acquiringOrderId);
+    console.log('  Order Status:', notification.orderStatus);
+    console.log('  Payment Amount:', notification.orderAmount);
+    console.log('  Payment Currency:', notification.orderCurrency);
+
+    // Tip: First verify amount and currency match your records
+    // Then handle based on orderStatus
+
+    if (notification.orderStatus === 'PAY_SUCCESS') {
+      // Payment successful - update order status, deliver goods, etc.
+    }
+  })
+  .onRefund((notification) => {
+    console.log('Refund notification:', notification.acquiringRefundOrderId);
+    // Handle refund notification
+  })
+  .onSubscriptionStatus((notification) => {
+    console.log('Subscription status notification:');
+    console.log('  Subscription ID:', notification.subscriptionId);
+    console.log('  Subscription Status:', notification.subscriptionStatus);
+
+    switch (notification.subscriptionStatus) {
+      case 'ACTIVE':
+        // Subscription activated - grant membership privileges
+        break;
+      case 'CLOSE':
+        // Subscription closed (timeout or failed)
+        break;
+      case 'MERCHANT_CANCELLED':
+        // Merchant cancelled subscription
+        break;
+      case 'USER_CANCELLED':
+        // User cancelled subscription
+        break;
+      case 'CHANNEL_CANCELLED':
+        // Channel cancelled subscription
+        break;
+      case 'EXPIRED':
+        // Subscription expired
+        break;
+    }
+  })
+  .onSubscriptionPeriodChanged((notification) => {
+    console.log('Subscription period changed:', notification.subscriptionId);
+    // Key fields to track:
+    // - notification.period: Current period number
+    // - notification.nextChargeAt: Next billing time
+    // - notification.subscriptionStatus: Subscription status
+    // - notification.orderStatus: Current billing order status (SUCCESS/FAILED)
+    // - notification.orderAmount: Billing amount
+    // - notification.orderCurrency: Billing currency
+  })
+  .onSubscriptionChange((notification) => {
+    console.log('Subscription change notification:');
+    console.log('  Change Request ID:', notification.subscriptionRequest);
+    console.log('  Change Status:', notification.subscriptionChangeStatus);
+    console.log('  Origin Subscription:', notification.originSubscriptionId);
+    console.log('  New Subscription:', notification.subscriptionId);
+
+    if (notification.subscriptionChangeStatus === 'SUCCESS') {
+      // Subscription change successful
+      // - Original subscription is now MERCHANT_CANCELLED
+      // - New subscription is now ACTIVE
+      // Update user's subscription level accordingly
+    } else if (notification.subscriptionChangeStatus === 'CLOSED') {
+      // Subscription change failed/closed
+      // Original subscription remains unchanged
+    }
   });
 
-  return res.json(result.response);
+// Express route
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  const body = req.body.toString();
+  const signature = req.headers['x-signature'] as string;
+
+  const result = await webhookHandler.handleWebhook(body, signature);
+
+  res.setHeader('X-SIGNATURE', result.responseSignature);
+  res.status(200).json(result.responseBody);
 });
 ```
 
-### Manual Webhook Signature Verification
+### Webhook Notification Types
+
+| Event Type | Handler Method | Description |
+|------------|----------------|-------------|
+| `PAYMENT_NOTIFICATION` | `onPayment()` | Payment result notification (triggered on every payment attempt, including retries) |
+| `REFUND_NOTIFICATION` | `onRefund()` | Refund result notification |
+| `SUBSCRIPTION_STATUS_NOTIFICATION` | `onSubscriptionStatus()` | Subscription status change notification (triggered when subscription main record status changes) |
+| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | `onSubscriptionPeriodChanged()` | Subscription period change notification (final result of each period) |
+| `SUBSCRIPTION_CHANGE_NOTIFICATION` | `onSubscriptionChange()` | Subscription change (upgrade/downgrade) result notification |
+
+### Subscription Notification Types Explained
+
+| Notification Type | Trigger Condition | Scope | Includes Retry Events | Typical Use Case |
+|-------------------|-------------------|-------|----------------------|------------------|
+| `SUBSCRIPTION_STATUS_NOTIFICATION` | Subscription main record status changes | Subscription level | No | Track subscription lifecycle: first payment success activation (ACTIVE), cancellation (MERCHANT_CANCELLED, CHANNEL_CANCELLED), first payment failure close (CLOSE), etc. |
+| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | Subscription period reaches final state | Period level | No (only final result) | Only need final result of each period, no intermediate retry events |
+| `SUBSCRIPTION_CHANGE_NOTIFICATION` | Subscription change (upgrade/downgrade) completes | Change request level | No (only final result) | Track subscription change results: SUCCESS or CLOSED |
+| `PAYMENT_NOTIFICATION` | Every payment order | Payment order level | Yes (includes all retries) | Need complete details of every payment attempt, including failure reasons, timestamps, retry details |
 
-For more control, you can use the low-level webhook utilities:
+> **Selection Guide**:
+> - If you only care about subscription activation/cancellation, use `SUBSCRIPTION_STATUS_NOTIFICATION`
+> - If you only care about final renewal result of each period, use `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`
+> - If you only care about subscription change (upgrade/downgrade) final result, use `SUBSCRIPTION_CHANGE_NOTIFICATION`
+> - If you need to track every payment attempt (including retries), use `PAYMENT_NOTIFICATION`
+
+> **Subscription Payment Note**: Each period's payment (including first payment and renewals) triggers `PAYMENT_NOTIFICATION` events. You can get subscription-related info (subscriptionId, period, etc.) from `subscriptionInfo`.
+
+> **Subscription Change (Upgrade/Downgrade) Webhook Note**:
+> When a subscription change is processed, the following notifications are triggered:
+> - `SUBSCRIPTION_CHANGE_NOTIFICATION`: When subscription change completes (SUCCESS or CLOSED)
+> - `SUBSCRIPTION_STATUS_NOTIFICATION`: When original subscription status changes to `MERCHANT_CANCELLED`
+> - `SUBSCRIPTION_STATUS_NOTIFICATION`: When new subscription status changes to `ACTIVE`
+> - `PAYMENT_NOTIFICATION`: If upgrade requires additional payment (price difference)
+
+## Payment Method Types
+
+### payMethodType Reference
+
+| Type | Description | Example payMethodName |
+|------|-------------|----------------------|
+| `CREDITCARD` | Credit Card | CC_VISA, CC_MASTERCARD, CC_AMEX, CC_JCB, etc. |
+| `DEBITCARD` | Debit Card | DC_VISA, DC_MASTERCARD, DC_ELO, etc. |
+| `EWALLET` | E-Wallet | GCASH, DANA, PROMPTPAY, GRABPAY, etc. |
+| `VA` | Virtual Account | BCA, BNI, BRI, MANDIRI, etc. |
+| `APPLEPAY` | Apple Pay | APPLEPAY |
+| `GOOGLEPAY` | Google Pay | GOOGLEPAY |
+
+### Usage Examples
 
 ```typescript
-import {
-  verifyWebhookSignature,
-  buildSuccessResponse,
-  buildFailedResponse,
-  isPaymentNotification,
-  isRefundNotification,
-} from '@waffo/waffo-node';
+// Specify type only, let user choose on checkout page
+paymentInfo: {
+  payMethodType: 'CREDITCARD',
+}
 
-// In your webhook handler
-app.post('/webhook', (req, res) => {
-  const signature = req.headers['x-signature'];
-  const body = JSON.stringify(req.body);
+// Specify exact payment method
+paymentInfo: {
+  payMethodType: 'CREDITCARD',
+  payMethodName: 'CC_VISA',
+}
 
-  // Verify signature
-  const verifyResult = verifyWebhookSignature(body, signature, waffoPublicKey);
+// Combine multiple types
+paymentInfo: {
+  payMethodType: 'CREDITCARD,DEBITCARD',
+}
 
-  if (!verifyResult.valid) {
-    return res.json(buildFailedResponse('Signature verification failed', merchantPrivateKey));
-  }
+// E-wallet with specific channel
+paymentInfo: {
+  payMethodType: 'EWALLET',
+  payMethodName: 'GCASH',
+}
+```
 
-  // Handle notification based on type
-  const notification = verifyResult.notification;
+> **Note**: For available `ProductName`, `PayMethodType`, `PayMethodName` values, merchants can log in to [Waffo Portal](https://dashboard.waffo.com) to view contracted payment methods (Home → Service → Pay-in).
 
-  if (isPaymentNotification(notification)) {
-    // Handle payment notification
-    console.log('Payment status:', notification.result.orderStatus);
-  } else if (isRefundNotification(notification)) {
-    // Handle refund notification
-    console.log('Refund status:', notification.result.refundStatus);
+## Advanced Configuration
+
+### Custom HTTP Transport (axios)
+
+The SDK uses native `fetch` by default. For connection pooling or advanced features, implement custom transport:
+
+```typescript
+import { Waffo, Environment } from '@waffo/waffo-node';
+import type { HttpTransport, HttpRequest, HttpResponse } from '@waffo/waffo-node';
+import axios, { AxiosInstance } from 'axios';
+import https from 'https';
+
+// Create custom HTTP transport using axios
+class AxiosHttpTransport implements HttpTransport {
+  private client: AxiosInstance;
+
+  constructor() {
+    this.client = axios.create({
+      timeout: 30000,
+      httpsAgent: new https.Agent({
+        minVersion: 'TLSv1.2',
+        maxVersion: 'TLSv1.3',
+      }),
+    });
   }
 
-  // Return success response
-  return res.json(buildSuccessResponse(merchantPrivateKey));
+  async send(request: HttpRequest): Promise<HttpResponse> {
+    try {
+      const response = await this.client.request({
+        method: request.method as 'POST' | 'GET',
+        url: request.url,
+        headers: request.headers,
+        data: request.body,
+        timeout: request.timeout,
+        validateStatus: () => true, // Don't throw on non-2xx
+      });
+
+      // Convert headers to Record<string, string>
+      const headers: Record<string, string> = {};
+      Object.entries(response.headers).forEach(([key, value]) => {
+        if (typeof value === 'string') {
+          headers[key] = value;
+        }
+      });
+
+      return {
+        statusCode: response.status,
+        headers,
+        body: typeof response.data === 'string'
+          ? response.data
+          : JSON.stringify(response.data),
+      };
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.code === 'ECONNABORTED') {
+        throw new Error('Request timeout');
+      }
+      throw error;
+    }
+  }
+}
+
+const waffo = new Waffo({
+  apiKey: 'your-api-key',
+  privateKey: 'your-private-key',
+  waffoPublicKey: 'waffo-public-key',
+  environment: Environment.SANDBOX,
+  httpTransport: new AxiosHttpTransport(),
 });
 ```
 
-### Direct HTTP Client Access
+### TLS Security Configuration
 
-For custom API requests not covered by the SDK methods:
+The SDK enforces **TLS 1.2 or higher** by default for all HTTPS communication.
+
+When implementing custom HTTP transport, ensure TLS 1.2+ is configured:
 
 ```typescript
-const response = await waffo.httpClient.post<CustomResponseType>('/custom/endpoint', {
-  body: { key: 'value' }
+import https from 'https';
+
+const httpsAgent = new https.Agent({
+  minVersion: 'TLSv1.2',
+  maxVersion: 'TLSv1.3',
+  // Optional: reject unauthorized certificates (default: true)
+  rejectUnauthorized: true,
 });
 
-if (response.success) {
-  console.log(response.data);
-}
+// Use with axios or other HTTP clients
+import axios from 'axios';
+const client = axios.create({
+  httpsAgent,
+});
 ```
 
-## Configuration Options
+### Debug Logging
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `apiKey` | string | Yes | - | API key provided by Waffo |
-| `privateKey` | string | Yes | - | Base64 encoded PKCS8 private key |
-| `waffoPublicKey` | string | No | Built-in | Custom Waffo public key for response verification |
-| `environment` | Environment | No | PRODUCTION | API environment (SANDBOX or PRODUCTION) |
-| `timeout` | number | No | 30000 | Request timeout in milliseconds |
-| `logger` | Logger | No | - | Logger instance for debugging (can use `console`) |
+Enable debug logging to troubleshoot issues during development:
 
-## API Response Format
+```bash
+# Enable all Waffo SDK debug logs
+DEBUG=waffo:* npm start
+
+# Enable only HTTP request/response logs
+DEBUG=waffo:http npm start
+
+# Enable only signing logs
+DEBUG=waffo:sign npm start
+```
 
-All API methods return an `ApiResponse<T>` object:
+Or configure programmatically:
 
 ```typescript
-interface ApiResponse<T> {
-  success: boolean;      // Whether the request was successful
-  statusCode: number;    // HTTP status code
-  data?: T;              // Response data (on success)
-  error?: string;        // Error message (on failure)
-}
+const waffo = new Waffo({
+  // ... other config
+  logger: {
+    debug: (msg: string) => console.debug('[WAFFO]', msg),
+    info: (msg: string) => console.info('[WAFFO]', msg),
+    warn: (msg: string) => console.warn('[WAFFO]', msg),
+    error: (msg: string) => console.error('[WAFFO]', msg),
+  },
+});
+```
+
+### Timeout Configuration Recommendations
+
+| Operation Type | Connect Timeout | Read Timeout | Notes |
+|----------------|-----------------|--------------|-------|
+| Create Order | 5s | 30s | Recommended |
+| Create Subscription | 5s | 30s | Recommended |
+| Refund Operation | 5s | 30s | Recommended |
+| Query Operations | 5s | 15s | Can be shorter |
+
+### Connection Pool Recommendations
+
+| Scenario | Max Connections | Max Per Route | Notes |
+|----------|-----------------|---------------|-------|
+| Low Traffic (< 10 QPS) | 20 | 10 | Default config sufficient |
+| Medium Traffic (10-100 QPS) | 50 | 20 | Consider using OkHttp |
+| High Traffic (> 100 QPS) | 100-200 | 50 | Consider Apache HttpClient |
+
+### Instance Reuse
+
+SDK instances are **thread-safe**. Recommended to use as singleton in your application:
+
+```typescript
+// Create once, reuse everywhere
+const waffo = new Waffo({ /* config */ });
+
+export { waffo };
+```
+
+### RSA Utilities
+
+```typescript
+import { RsaUtils } from '@waffo/waffo-node';
+
+// Generate key pair (for testing)
+const keyPair = RsaUtils.generateKeyPair();
+console.log('Public Key (submit to Waffo):', keyPair.publicKey);
+console.log('Private Key (keep on your server):', keyPair.privateKey);
+
+// Sign data
+const signature = RsaUtils.sign(data, privateKey);
+
+// Verify signature
+const isValid = RsaUtils.verify(data, signature, publicKey);
 ```
 
-## Type Definitions
+## Error Handling
+
+### Error Handling Pattern
+
+SDKs use a hybrid error handling approach:
+- **Business errors**: Returned via `ApiResponse`, check with `response.isSuccess()`
+- **Unknown status exceptions**: Only for **write operations** (may affect funds or status), network timeout or server returning E0001 error code throws `WaffoUnknownStatusError`
+
+### Methods That Throw Unknown Status Exception
+
+Only these methods that may affect funds or status throw `WaffoUnknownStatusError`:
 
-The SDK exports comprehensive TypeScript types including:
+| Method | Description |
+|--------|-------------|
+| `order().create()` | Create order, may initiate payment |
+| `order().refund()` | Refund, may cause fund changes |
+| `order().cancel()` | Cancel order, affects order status |
+| `subscription().create()` | Create subscription, may cause initial charge |
+| `subscription().cancel()` | Cancel subscription, affects subscription status |
 
-- `Environment` - SDK environment enum
-- `CountryCode` - ISO 3166-1 alpha-3 country codes
-- `CurrencyCode` - ISO 4217 currency codes
-- `ProductName` - Payment product type enum (ONE_TIME_PAYMENT, SUBSCRIPTION)
-- `payMethodType` - Payment method category (string: "EWALLET", "CREDITCARD", "BANKTRANSFER", "ONLINE_BANKING", "DIGITAL_BANKING", "OTC", "DEBITCARD")
-- `payMethodName` - Specific payment method (string: "OVO", "DANA", "GOPAY", "GCASH", "CC_VISA", "CC_MASTERCARD", "VA_BCA", "VA_BNI", etc.)
-- `OrderStatus` - Order status enum (PAY_IN_PROGRESS, AUTHORIZATION_REQUIRED, PAY_SUCCESS, ORDER_CLOSE, etc.)
-- `RefundStatus` - Refund status enum (REFUND_IN_PROGRESS, ORDER_PARTIALLY_REFUNDED, ORDER_FULLY_REFUNDED, ORDER_REFUND_FAILED)
-- `SubscriptionStatus` - Subscription status enum (AUTHORIZATION_REQUIRED, ACTIVE, PAUSED, MERCHANT_CANCELLED, etc.)
-- `PeriodType` - Subscription period type enum (DAILY, WEEKLY, MONTHLY, YEARLY)
-- `UserTerminalType` - User terminal type enum (WEB, APP, IN_WALLET_APP, IN_MINI_PROGRAM)
-- Request/Response interfaces for all API operations
+**Query methods do not throw this exception** (e.g., `inquiry()`), because query operations can be safely retried without affecting funds or status.
 
-## Development
+### WaffoUnknownStatusError Handling
+
+> ⚠️ **IMPORTANT WARNING**
+>
+> When `WaffoUnknownStatusError` is caught, it means **the operation result is uncertain**.
+>
+> **DO NOT directly close the order or assume payment failed!** The user may have already completed payment.
+>
+> **Correct handling:**
+> 1. Call `waffo.order().inquiry()` to query actual order status
+> 2. Or wait for Waffo webhook callback notification
+> 3. Use Waffo's returned order status as the final authority
+
+```typescript
+import { Waffo, WaffoUnknownStatusError } from '@waffo/waffo-node';
+
+try {
+  const response = await waffo.order().create(params);
+
+  if (response.isSuccess()) {
+    // Handle success
+    const data = response.getData();
+    console.log('Redirect URL:', data.orderAction);
+  } else {
+    // Handle business error (non-E0001 error code)
+    console.log('Error:', response.getMessage());
+  }
+} catch (error) {
+  if (error instanceof WaffoUnknownStatusError) {
+    // ⚠️ IMPORTANT: Payment status unknown
+    //
+    // [WRONG] Do not close order directly! User may have paid
+    // [CORRECT]
+    //   1. Call inquiry API to query actual order status
+    //   2. Or wait for Waffo webhook callback
+    //   3. Use Waffo's returned status as authority
+
+    console.warn('Status unknown, need to query:', error.message);
+
+    // Query order status (inquiry doesn't throw, can call directly)
+    const inquiryResponse = await waffo.order().inquiry({
+      paymentRequestId: params.paymentRequestId,
+    });
+
+    if (inquiryResponse.isSuccess()) {
+      const status = inquiryResponse.getData().orderStatus;
+      console.log('Actual order status:', status);
+    } else {
+      // Query failed, wait for webhook callback
+      console.error('Query failed, waiting for webhook callback');
+    }
+  } else {
+    throw error;
+  }
+}
+```
+
+### WaffoUnknownStatusError Trigger Scenarios
+
+| Scenario | Description |
+|----------|-------------|
+| Network Timeout | Request timeout, cannot determine if server received request |
+| Connection Failed | Network connection failed, cannot determine server status |
+| E0001 Error Code | Server returned E0001, indicating processing status unknown |
+
+### Error Code Classification
+
+Error codes are classified by first letter:
+
+| Prefix | Category | Description |
+|--------|----------|-------------|
+| **S** | SDK Internal Error | SDK client internal error such as network timeout, signing failure, etc. |
+| **A** | Merchant Related | Parameter, signature, permission, contract issues on merchant side |
+| **B** | User Related | User status, balance, authorization issues |
+| **C** | System Related | Waffo system or payment channel issues |
+| **D** | Risk Related | Risk control rejection |
+| **E** | Unknown Status | Server returned unknown status |
+
+### Complete Error Code Table
+
+#### SDK Internal Errors (Sxxxx)
+
+| Code | Description | Exception Type | Handling Suggestion |
+|------|-------------|----------------|---------------------|
+| `S0001` | Network Error | `WaffoUnknownStatusError` | **Status unknown**, need to query order to confirm |
+| `S0002` | Invalid Public Key | `WaffoError` | Check if public key is valid Base64 encoded X509 format |
+| `S0003` | RSA Signing Failed | `WaffoError` | Check if private key format is correct |
+| `S0004` | Response Signature Verification Failed | `ApiResponse.error()` | Check Waffo public key config, contact Waffo |
+| `S0005` | Request Serialization Failed | `ApiResponse.error()` | Check request parameter format |
+| `S0006` | SDK Unknown Error | `ApiResponse.error()` | Check logs, contact technical support |
+| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 encoded PKCS8 format |
+
+> **Important**: `S0001` and `E0001` (returned by server) indicate **unknown status**. Do not close order directly! Should call query API or wait for webhook to confirm actual status.
+
+#### Merchant Related Errors (Axxxxx)
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| `0` | Success | 200 |
+| `A0001` | Invalid API Key | 401 |
+| `A0002` | Invalid Signature | 401 |
+| `A0003` | Parameter Validation Failed | 400 |
+| `A0004` | Insufficient Permission | 401 |
+| `A0005` | Merchant Limit Exceeded | 400 |
+| `A0006` | Merchant Status Abnormal | 400 |
+| `A0007` | Unsupported Transaction Currency | 400 |
+| `A0008` | Transaction Amount Exceeded | 400 |
+| `A0009` | Order Not Found | 400 |
+| `A0010` | Merchant Contract Does Not Allow This Operation | 400 |
+| `A0011` | Idempotent Parameter Mismatch | 400 |
+| `A0012` | Merchant Account Insufficient Balance | 400 |
+| `A0013` | Order Already Paid, Cannot Cancel | 400 |
+| `A0014` | Refund Rules Do Not Allow Refund | 400 |
+| `A0015` | Payment Channel Does Not Support Cancel | 400 |
+| `A0016` | Payment Channel Rejected Cancel | 400 |
+| `A0017` | Payment Channel Does Not Support Refund | 400 |
+| `A0018` | Payment Method Does Not Match Merchant Contract | 400 |
+| `A0019` | Cannot Refund Due to Chargeback Dispute | 400 |
+| `A0020` | Payment Amount Exceeds Single Transaction Limit | 400 |
+| `A0021` | Cumulative Payment Amount Exceeds Daily Limit | 400 |
+| `A0022` | Multiple Products Exist, Need to Specify Product Name | 400 |
+| `A0023` | Token Expired, Cannot Create Order | 400 |
+| `A0024` | Exchange Rate Expired, Cannot Process Order | 400 |
+| `A0026` | Unsupported Checkout Language | 400 |
+| `A0027` | Refund Count Reached Limit (50 times) | 400 |
+| `A0029` | Invalid Card Data Provided by Merchant | 400 |
+| `A0030` | Card BIN Not Found | 400 |
+| `A0031` | Unsupported Card Scheme or Card Type | 400 |
+| `A0032` | Invalid Payment Token Data | 400 |
+| `A0033` | Multiple Payment Methods with Same Name, Need to Specify Country | 400 |
+| `A0034` | Order Expiry Time Provided by Merchant Has Passed | 400 |
+| `A0035` | Current Order Does Not Support Capture Operation | 400 |
+| `A0036` | Current Order Status Does Not Allow Capture Operation | 400 |
+| `A0037` | User Payment Token Invalid or Expired | 400 |
+| `A0038` | MIT Transaction Requires Verified User Payment Token | 400 |
+| `A0039` | Order Already Refunded by Chargeback Prevention Service | 400 |
+| `A0040` | Order Cannot Be Created Concurrently | 400 |
+| `A0045` | MIT Transaction Cannot Process, tokenId Status Unverified | 400 |
+
+#### User Related Errors (Bxxxxx)
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| `B0001` | User Status Abnormal | 400 |
+| `B0002` | User Limit Exceeded | 400 |
+| `B0003` | User Insufficient Balance | 400 |
+| `B0004` | User Did Not Pay Within Timeout | 400 |
+| `B0005` | User Authorization Failed | 400 |
+| `B0006` | Invalid Phone Number | 400 |
+| `B0007` | Invalid Email Format | 400 |
+
+#### System Related Errors (Cxxxxx)
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| `C0001` | System Error | 500 |
+| `C0002` | Merchant Contract Invalid | 500 |
+| `C0003` | Order Status Invalid, Cannot Continue Processing | 500 |
+| `C0004` | Order Information Mismatch | 500 |
+| `C0005` | Payment Channel Rejected | 503 |
+| `C0006` | Payment Channel Error | 503 |
+| `C0007` | Payment Channel Under Maintenance | 503 |
+
+#### Risk Related Errors (Dxxxxx)
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| `D0001` | Risk Control Rejected | 406 |
+
+#### Unknown Status Errors (Exxxxx)
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| `E0001` | Unknown Status (Need to query or wait for callback) | 500 |
+
+> **Note**: When receiving `E0001` error code, it indicates transaction status is unknown. **Do not close order directly**, should call query API to confirm actual status, or wait for webhook callback notification.
+
+## Development & Testing
+
+### Build Commands
 
 ```bash
 # Install dependencies
 npm install
 
-# Build (generates both ESM and CJS)
+# Build the SDK
 npm run build
 
 # Run tests
 npm test
 
-# Run tests with coverage
-npm run test:coverage
+# Type check
+npm run typecheck
 
-# Run tests in watch mode
-npm run test:watch
-
-# Lint code
+# Lint
 npm run lint
 
-# Lint and auto-fix
-npm run lint:fix
-
 # Format code
 npm run format
-
-# Check formatting
-npm run format:check
 ```
 
-### Code Quality
-
-This project uses:
-- **ESLint** - Code linting with TypeScript support
-- **Prettier** - Code formatting
-- **Husky** - Git hooks
-- **lint-staged** - Run linters on staged files
-
-Pre-commit hooks automatically run ESLint and Prettier on staged `.ts` files.
-
-### Running E2E Tests
-
-E2E tests require Waffo sandbox credentials. The SDK supports multiple merchant configurations for different test scenarios and provides comprehensive test coverage based on the official Waffo test cases document.
+### Generate Types from OpenAPI
 
 ```bash
-# Copy the template and fill in your credentials
-cp .env.template .env
-# Edit .env with your credentials
-```
-
-Environment variables:
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `WAFFO_PUBLIC_KEY` | No | Waffo public key for signature verification (shared) |
-| `ACQUIRING_MERCHANT_ID` | Yes* | Merchant ID for payment/order tests |
-| `ACQUIRING_API_KEY` | Yes* | API key for payment/order tests |
-| `ACQUIRING_MERCHANT_PRIVATE_KEY` | Yes* | Private key for payment/order tests |
-| `SUBSCRIPTION_MERCHANT_ID` | Yes** | Merchant ID for subscription tests |
-| `SUBSCRIPTION_API_KEY` | Yes** | API key for subscription tests |
-| `SUBSCRIPTION_MERCHANT_PRIVATE_KEY` | Yes** | Private key for subscription tests |
-
-\* Required for running acquiring/payment E2E tests
-\** Required for running subscription E2E tests
-
-**E2E Test Coverage:**
-
-| Module | Test Cases |
-|--------|------------|
-| Create Order | Payment success/failure, channel rejection (C0005), idempotency error (A0011), system error (C0001), unknown status (E0001) |
-| Inquiry Order | Query before/after payment |
-| Cancel Order | Cancel before payment, channel not supported (A0015), already paid (A0013) |
-| Refund Order | Full/partial refund, parameter validation (A0003), refund rules (A0014) |
-| Create Subscription | Subscription success/failure, next period payment simulation |
-| Cancel Subscription | Merchant-initiated cancellation |
-| Webhook Notifications | Signature verification for payment, refund, and subscription notifications |
-
-**Sandbox Amount Triggers:**
-
-| Amount Pattern | Error Code | Description |
-|----------------|------------|-------------|
-| 9, 90, 990, 1990, 19990 | C0005 | Channel rejection |
-| 9.1, 91, 991, 1991, 19991 | C0001 | System error |
-| 9.2, 92, 992, 1992, 19992 | E0001 | Unknown status |
-| 9.3, 93, 993, 1993, 19993 | C0001 | Cancel system error |
-| 9.4, 94, 994, 1994, 19994 | E0001 | Cancel unknown status |
-| 9.5, 95, 995, 1995, 19995 | C0001 | Refund system error |
-| 9.6, 96, 996, 1996, 199996 | E0001 | Refund unknown status |
+# From monorepo root
+./scripts/generate-types.sh node
+```
+
+### Run Test Vectors
 
 ```bash
-# Run all tests
-npm test
+# Run cross-language test vectors
+npm run test:vectors
 ```
 
-## Build Output
+## Support
+
+- Documentation: [Waffo Developer Docs](https://dashboard-sandbox.waffo.com/docs/)
+- Issues: [GitHub Issues](https://github.com/waffo-com/waffo-sdk/issues)
+- Technical Support: merchant.support@waffo.com
+
+## License
 
-The SDK is built using [tsup](https://tsup.egoist.dev/) and outputs:
+MIT License - See [LICENSE](LICENSE) file for details.
 
-| File | Format | Description |
-|------|--------|-------------|
-| `dist/index.js` | CommonJS | For `require()` imports |
-| `dist/index.mjs` | ESM | For `import` statements |
-| `dist/index.d.ts` | TypeScript | Type declarations |