@bitpal/checkout 0.3.0 → 0.6.0

package/dist/index.d.ts

@@ -3,13 +3,17 @@
  */
 interface BitPalConfig {
     /**
-     * API 키. prefix 가 mode 를 결정합니다:
+     * API 키(서버 전용, secret). prefix 가 mode 를 결정합니다:
      *   - `bp_test_...` → TEST mode (testnet 또는 local anvil)
      *   - `bp_live_...` → LIVE mode (mainnet)
      *
      * BitPal 콘솔 → Developers → API Keys 에서 발급.
+     *
+     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. 그러나 buyer-facing 공개 메서드
+     * (getPublicSession/getStatus/issueDepositAddress)는 인증 불요(session_token 기반)이므로 브라우저에서
+     * apiKey 없이 쓸 수 있다 — 절대 secret 키를 브라우저에 노출하지 말 것.
      */
-    apiKey: string;
+    apiKey?: string;
     /**
      * BitPal API 기본 URL. 환경별로 다릅니다:
      *   - production: `https://api.bitpal.io` (기본값) — 실제 testnet/mainnet 컨트랙트
@@ -21,23 +25,48 @@ interface BitPalConfig {
     /** 요청 타임아웃 (ms, 기본값: 30000) */
     timeout?: number;
 }
+/** 응답/정규화된 line item — amount 는 항상 atomic μUSD 정수. */
 interface LineItem {
     name: string;
-    /**
-     * Atomic μUSDC 정수 문자열 (USDC/USDT 6 decimals).
-     * $1 = "1000000", $29 = "29000000".
-     * decimal 표기는 거부된다 — `toAtomicUSDC('29.00')` 헬퍼 사용 권장.
-     */
+    /** Atomic μUSD 정수 문자열($1="1000000", $29="29000000"). */
     amount: string;
     currency: string;
     quantity?: number;
 }
+/**
+ * 세션 생성 입력용 line item. 금액은 둘 중 **하나**:
+ *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
+ *     ※ 금액은 **USD 가격**이다(체인/토큰 decimal 무관). 토큰(USDC 6dp / BNB USDT 18dp)별 스케일은 발급 시 서버가 처리.
+ *   - `amount_atomic`: 이미 raw μUSD 정수 문자열($1="1000000")인 경우(고급/기존 코드).
+ * 둘 다 지정하거나 둘 다 생략하면 SDK 가 에러를 throw 한다.
+ */
+interface LineItemInput {
+    name: string;
+    currency: string;
+    quantity?: number;
+    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    amount?: string;
+    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    amount_atomic?: string;
+}
+interface PriceLineItem {
+    /** price_... — bitpal.checkout.prices.create()로 만든 가격 */
+    price_id: string;
+    quantity?: number;
+}
+type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
-    line_items: LineItem[];
+    line_items: CheckoutLineItemInput[];
     /** 고객 지갑 주소 (선택) */
     payer_wallet?: string;
-    /** 결제 체인 (예: eip155:8453) */
+    /** 결제 체인 (예: eip155:8453). 단일 고정 — allowed_pay_chains와 상호 배타. */
     pay_chain?: string;
+    /**
+     * 허용 결제 체인 목록 (CAIP-2). 구매자가 이 중에서 선택하며, 하나뿐이면 자동 선택된다.
+     * pay_chain(단일 고정)과 **상호 배타** — 동시 지정 시 SDK가 에러를 throw한다.
+     * 예: ['eip155:84532', 'eip155:11155420', 'eip155:80002', 'eip155:421614']
+     */
+    allowed_pay_chains?: string[];
     /** 결제 자산 (예: USDC) */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
@@ -67,12 +96,8 @@ interface CheckoutSession {
     settled_at: string | null;
     tx_hash: string | null;
     created_at: string;
-    /** 'hosted' | 'external' — 결제 경로 구분 */
+    /** 'hosted' — 결제 경로. 안2 는 hosted deposit-address 단일 경로. */
     payment_source?: string;
-    /** External on-chain 결제 검증 기록 목록 */
-    payment_observations?: PaymentObservation[];
-    /** External/gasless checkout payment config supplied by BitPal API. */
-    external_payment_config?: ExternalPaymentConfig;
     /** 호스티드 결제 페이지 URL (token 쿼리 포함). backend 응답 그대로 사용 — buyer를 이 URL로 redirect. */
     checkout_url?: string;
     /** 1회용 session token. `checkout_url`에 이미 query로 박혀 있어 별도 사용 불필요. */
@@ -80,119 +105,99 @@ interface CheckoutSession {
     /** `checkout_url`의 별칭 (backwards compat). buyer redirect 시 이 필드 또는 `checkout_url` 사용. */
     url: string;
 }
-interface ExternalPaymentConfig {
-    chain: string;
-    chain_id: string;
-    payment_id: string;
-    escrow_contract_address: string | null;
-    token_address: string | null;
-    merchant_wallet: string;
-    amount: string;
-    fee_amount: string;
-    reserve_amount: string;
-    asset: string;
+/**
+ * 안2 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
+ * `issueDepositAddress({ chain, token })` 로 입금주소를 발급받는다. 단일-자산 세션은 1개.
+ */
+interface PaymentOption {
+    /** CAIP-2 (예: eip155:8453, tron:0x2b6653dc, solana:5eykt4…). 체인 식별의 canonical. */
+    caip2: string;
+    /** EVM numeric chainId. 비-EVM(Tron/Solana)은 null — 식별은 caip2 사용. */
+    chain_id: number | null;
+    token_symbol: string;
+    /** 토큰 컨트랙트/mint 주소(EVM 0x / Tron base58 / Solana base58 mint). */
+    token_address: string;
+    /** 토큰 decimals(USDC/USDT=6, BSC-USD=18). atomic↔decimal 변환에 필수 — 6dp 가정 금지. */
     decimals: number;
-    supported_methods: Array<'authorization_relay'>;
 }
 /**
- * CheckoutEscrow.PaymentDeposited 이벤트 단위 검증 기록.
- * `GET /v1/checkout/sessions/:id` 응답의 `payment_observations` 배열 원소.
+ * `getPublicSession()` (`GET /v1/checkout/sessions/:id/public`) 응답 — 인증 불요(공개).
+ * buyer-facing 결제 페이지가 표시/폴링에 쓰는 서버 권위 뷰.
  */
-interface PaymentObservation {
+interface PublicSession {
     id: string;
-    tx_hash: string;
-    chain_id: string;
-    from_address: string | null;
-    to_address: string;
-    /** Atomic μUSDC 정수 문자열 */
-    amount: string;
-    /** 'pending' | 'valid' | 'invalid' | 'duplicate' | 'underpaid' | 'overpaid' */
-    validation_status: string;
-    /** 'detected' | 'soft_confirmed' | 'final_confirmed' | 'reorg_revoked' */
-    finality_status: string;
-    validation_error: string | null;
-    block_number: number | null;
-    confirmations: number;
+    /** created | awaiting_deposit | deposit_detected | paid_confirmed | swept | unresolved_* | wrong_token | expired ... */
+    status: string;
+    mode: string | null;
+    currency: string;
+    /** Atomic 정수 문자열(토큰 decimals 기준). */
+    amount_total: string;
+    amount_received?: string | null;
+    pay_chain: string | null;
+    pay_asset: string | null;
+    /** 발급된 주문별 forwarder 입금주소(미발급이면 null). */
+    deposit_address?: string | null;
+    /** 구매자 선택 가능한 결제 옵션(서버 권위). 단일-자산이면 1개. */
+    payment_options: PaymentOption[];
+    chain_id: number | null;
+    token_address: string | null;
+    /** 선택된 pay 토큰 decimals(발급 후). amount_total/amount_received atomic 해석에 사용 — 6dp 가정 금지. */
+    token_decimals?: number | null;
+    tx_hash: string | null;
+    release_tx_hash?: string | null;
+    expires_at: string | null;
+    success_url: string | null;
+    cancel_url: string | null;
+    fee_amount: string | null;
+    net_amount: string | null;
+    seller_wallet: string;
+    paid_at: string | null;
+    settled_at: string | null;
     created_at: string;
+    line_items: LineItem[];
 }
 /**
- * `submitExternalPayment` 요청 파라미터.
- * 검증에 필요한 값은 tx_hash + chain만으로 충분 — payer_wallet, asset 등은 on-chain 이벤트에서 도출.
- */
-interface SubmitExternalPaymentParams {
-    /** CheckoutEscrow 입금 tx hash (0x...) */
-    tx_hash: string;
-    /** 체인 식별자 (기본값: 'base'). 예: 'base', 'bnb', 'polygon' */
-    chain?: string;
-    /** Public session token — buyer 측 제출 시 사용. API key 인증 시 불필요. */
-    session_token?: string;
-}
-/**
- * `submitExternalPayment` 응답.
+ * `issueDepositAddress()` 요청 파라미터.
+ * chain/token 은 멀티옵션 세션에서만 필요(단일-자산 세션은 생략). refundAddress 는 필수 —
+ * 금액부족/잘못된토큰/만료 시 이 주소로 환불되며, 입금주소에 커밋되어 발급 후 변경 불가.
  */
-interface SubmitExternalPaymentResult {
-    observation_id: string;
-    /** 'valid' | 'invalid' | 'underpaid' | 'overpaid' | 'duplicate' */
-    validation_status: string;
-    /** 검증 후 세션 상태 */
-    session_status: string;
-    /** 입금한 지갑 주소 (on-chain 이벤트에서 도출) */
-    from_address: string | null;
-    /** Atomic μUSDC 정수 문자열 */
-    amount: string;
-    message: string;
-}
-interface PayWithAuthorizationParams {
-    chain?: string;
+interface IssueDepositAddressParams {
+    /** 결제 페이지 접근 증명(HMAC). createSession 응답의 session_token. */
     session_token: string;
-    /** EIP-3009 TransferWithAuthorization sig (USDC). */
-    authorization: {
-        from: string;
-        validAfter?: string;
-        validBefore: string;
-        authNonce: string;
-        v: number;
-        r: string;
-        s: string;
-    };
     /**
-     * Q5 C-01 옵션 2 (SDK v0.2.0): PaymentAuthorization typed-data sig.
-     * Buyer 가 결제 의도 전체 (paymentId, merchant, amount, fee, reserve, duration) 에 서명.
-     * gateway 키 탈취 시에도 buyer 의도 밖 결제 생성 차단.
-     *
-     * 서명 생성: `buildPaymentAuthTypedData()` helper 또는 viem `signTypedData` 직접 호출.
-     * Required for SDK v0.2.x+ — gasless lane 모든 호출에 필수. v0.1.x 는 미지원.
+     * 환불 주소. 필수. 선택한 체인의 VM 형식이어야 한다:
+     *   EVM=0x…, Tron=base58(T…), Solana=base58. 결제와 같은 네트워크의 본인 주소.
+     * 금액부족/잘못된토큰/만료 시 이 주소로 환불되며, 입금주소에 커밋되어 발급 후 변경 불가.
      */
-    payment_auth: {
-        deadline: string;
-        duration: string;
-        v: number;
-        r: string;
-        s: string;
-    };
+    refundAddress: string;
+    /** 선택 자산의 chain(CAIP-2 또는 short-name). 멀티옵션 세션 필수. */
+    chain?: string;
+    /** 선택 자산의 token symbol(예: USDC). 멀티옵션 세션 필수. */
+    token?: string;
 }
 /**
- * Q5 C-01 옵션 2: buyer 가 서명할 EIP-712 PaymentAuthorization typed-data 의 입력 인자.
- * `buildPaymentAuthTypedData()` 가 이를 받아 viem 호환 객체를 반환.
+ * `issueDepositAddress()` 응답 — 이 주소로 정확 금액을 송금하면 watcher 가 감지, keeper 가 정산한다.
  */
-interface PaymentAuthTypedDataArgs {
-    escrowAddress: string;
-    chainId: number;
-    paymentId: string;
-    payer: string;
-    merchant: string;
-    token: string;
-    amount: string;
+interface DepositAddress {
+    sessionId: string;
+    chain: string;
+    /** 주문별 결정적 입금주소(EVM/Tron=CREATE2 forwarder, Solana=order PDA 의 deposit ATA). */
+    depositAddress: string;
+    expectedToken: string;
+    /** Atomic 정수 문자열. */
+    expectedAmount: string;
     feeAmount: string;
-    reserveAmount: string;
-    duration: string;
+    refundAddress: string;
+    /** Unix seconds — on-chain deadline. */
     deadline: string;
-    nonce: string;
+    expiresAt: string | null;
 }
-interface CheckoutPaymentResult {
+/**
+ * `getStatus()` (`GET /v1/checkout/sessions/:id/status`) 응답 — 경량 폴링용(인증 불요).
+ */
+interface SessionStatus {
     status: string;
-    tx_hash: string;
-    message?: string;
+    paid_at: string | null;
 }
 /**
  * 수수료 미리보기 응답.
@@ -206,65 +211,16 @@ interface FeePreview {
     net_amount: string;
 }
 /**
- * Auto refund 파라미터 — escrow 보관 중(`escrow_status` pending|disputed)일 때 동작.
- * 컨트랙트가 buyer에게 직접 토큰 transfer.
- *
- * `amount` 미지정 시 backend가 잔액 전액(full refund)을 시도. 명시 시 atomic μUSDC.
- */
-interface RefundSessionParams {
-    /** Atomic μUSDC 정수 문자열. 미지정 시 전액. */
-    amount?: string;
-    /** 환불 사유 코드 (선택, 머천트 대시보드/audit log 분류용) */
-    reason?: string;
-    /** 환불 사유 상세 (선택, 자유 텍스트) */
-    reason_detail?: string;
-}
-interface RefundSessionResult {
-    refunded: boolean;
-    refundId: string;
-    /** Atomic μUSDC 정수 문자열 */
-    amount: string;
-    type: 'full' | 'partial';
-    /** on-chain transaction hash. simulation/escrow 미배포 환경에서는 sim_xxx */
-    txHash: string | null;
-}
-/**
- * Record refund 파라미터 — `status='settled'` 후 머천트가 외부 지갑에서 직접 송금하고
- * tx_hash를 입력해 환불을 DB-only로 기록한다. 컨트랙트 호출 없음.
+ * 환불은 온체인 자동 경로 — SDK 에 수동 환불 API 는 없다.
+ * 금액부족/잘못된토큰/만료 시 issueDepositAddress 에 지정한 refundAddress 로 자동 환불되고,
+ * 세션 status(expired/unresolved) + webhook 으로 통지된다.
  */
-interface RecordRefundParams {
-    /** Atomic μUSDC 정수 문자열 (필수) */
-    refund_amount: string;
-    /** 외부 송금 transaction hash (필수, 형식 검증 안 함) */
-    tx_hash: string;
-    /** 환불 사유 (선택) */
-    reason?: string;
-}
 /**
  * 멱등성 키 — 동일 키로 재시도 시 backend가 같은 결과 반환.
- * Phase 1 SDK는 사용자가 명시적으로 전달 (UUID 권장).
  */
 interface IdempotencyOptions {
     idempotencyKey?: string;
 }
-/**
- * `GET /v1/checkout/sessions/:id/refunds` 응답 row.
- * 필드는 backend `listSessionRefunds` 반환과 동일 — Phase 1에서는 통합 타입 미고정 (스냅샷 시점에 따라 컬럼 변동).
- */
-interface RefundEntry {
-    id: string;
-    session_id: string;
-    /** 'auto' | 'record' (escrow refund vs DB-only manual) */
-    refund_mode?: string;
-    amount: string;
-    /** 'pending' | 'completed' | 'failed' 등 */
-    status?: string;
-    tx_hash: string | null;
-    reason?: string | null;
-    reason_detail?: string | null;
-    created_at: string;
-    [key: string]: unknown;
-}
 interface ApiResponse<T> {
     data: T;
     error?: string;
@@ -273,6 +229,234 @@ interface ListResponse<T> {
     data: T[];
     total?: number;
 }
+interface CheckoutProduct {
+    /** prod_... */
+    id: string;
+    name: string;
+    description: string | null;
+    image_url: string | null;
+    /** 'active' | 'inactive' */
+    status: string;
+    metadata: Record<string, unknown>;
+    mode: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CheckoutPrice {
+    /** price_... */
+    id: string;
+    /** prod_... */
+    product_id: string;
+    /** 원자 단위 정수 문자열 ($1 = "1000000") — 불변 */
+    amount_atomic: string;
+    currency: string;
+    token_symbol: string;
+    /** v1: 'one_time' */
+    billing_type: string;
+    nickname: string | null;
+    lookup_key: string | null;
+    mode: string;
+    created_at: string;
+}
+interface CreateProductParams {
+    name: string;
+    description?: string;
+    image_url?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateProductParams {
+    name?: string;
+    description?: string | null;
+    image_url?: string | null;
+    metadata?: Record<string, unknown>;
+    status?: 'active' | 'inactive';
+}
+/**
+ * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
+ *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ */
+interface CreatePriceParams {
+    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    amount?: string;
+    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    amount_atomic?: string;
+    currency?: string;
+    token_symbol?: string;
+    billing_type?: 'one_time';
+    nickname?: string;
+    lookup_key?: string;
+}
+/**
+ * Price는 lifecycle 없는 immutable record — 변경 가능한 것은 nickname(표시 메타)뿐.
+ * 금액류 필드(amount_atomic 등)는 immutable, "그만 팔기"는 Price 가 아니라 그 Price 를 쓰는
+ * Payment Link 를 inactive 로 한다.
+ */
+interface UpdatePriceParams {
+    nickname?: string | null;
+}
+interface ListProductsParams {
+    status?: 'active' | 'inactive';
+    limit?: number;
+    offset?: number;
+}
+interface ListPricesParams {
+    limit?: number;
+    offset?: number;
+}
+interface CheckoutPaymentLink {
+    /** plink_... */
+    id: string;
+    /** 고엔트로피 공개 토큰 — 호스티드 URL `{checkoutBase}/plink/{share_token}` 에 사용 */
+    share_token: string;
+    /** price_... — 이 링크가 파는 가격(생성 후 고정) */
+    price_id: string;
+    title: string | null;
+    description: string | null;
+    collect_email: boolean;
+    email_required: boolean;
+    /** CAIP-2 목록 또는 null(legacy) */
+    allowed_pay_chains: string[] | null;
+    /** chain×token cell 목록 또는 null */
+    allowed_assets: Array<{
+        caip2: string;
+        token: string;
+    }> | null;
+    success_url: string | null;
+    cancel_url: string | null;
+    /** 'active' | 'inactive' */
+    status: string;
+    max_uses: number | null;
+    paid_use_count: number;
+    expires_at: string | null;
+    mode: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreatePaymentLinkParams {
+    /** price_... — bitpal.checkout.prices.create() 로 만든 가격. 필수. */
+    price_id: string;
+    title?: string;
+    description?: string;
+    /** buyer 이메일 수집(기본 true) */
+    collect_email?: boolean;
+    /** buyer 이메일 필수(기본 true). true 면 collect_email 도 true 여야 함. */
+    email_required?: boolean;
+    /** 허용 결제 체인(CAIP-2 또는 short-name). allowed_assets 가 있으면 그쪽 우선. */
+    allowed_pay_chains?: string[];
+    /** chain×token cell 허용 목록 — allowed_pay_chains 보다 우선. */
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }>;
+    success_url?: string;
+    cancel_url?: string;
+    max_uses?: number;
+    /** ISO-8601 datetime */
+    expires_at?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdatePaymentLinkParams {
+    title?: string | null;
+    description?: string | null;
+    collect_email?: boolean;
+    email_required?: boolean;
+    allowed_pay_chains?: string[] | null;
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }> | null;
+    success_url?: string | null;
+    cancel_url?: string | null;
+    status?: 'active' | 'inactive';
+    max_uses?: number | null;
+    expires_at?: string | null;
+    metadata?: Record<string, unknown>;
+}
+interface ListPaymentLinksParams {
+    status?: 'active' | 'inactive';
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * catalog.ts — Product / immutable Price 관리 리소스 (PROD-LINK-3a-SDK)
+ *
+ * server-side SDK 전용 (secret API key). 브라우저에서 사용 금지.
+ *
+ * 사용 예:
+ * ```ts
+ * const bitpal = new BitPal({ apiKey: 'bp_test_...' });
+ * const { data: product } = await bitpal.checkout.products.create({ name: 'Pro Plan' });
+ * const { data: price } = await bitpal.checkout.prices.create(product.id, {
+ *   amount_atomic: toAtomicUSDC('29.00'),
+ * });
+ * ```
+ *
+ * Price immutable 원칙: 가격 변경은 update가 아니라 "새 price 생성"이다.
+ * `prices.update`는 nickname(표시 메타)만 받는다 — 금액류 필드 변경 helper는 의도적으로 없다.
+ * "그만 팔기"는 Price 를 끄는 게 아니라 그 Price 를 쓰는 Payment Link 를 inactive 로 한다.
+ */
+
+/** client.ts의 private request를 리소스에 주입하기 위한 시그니처 */
+type CatalogRequester = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+declare class ProductsResource {
+    private readonly request;
+    constructor(request: CatalogRequester);
+    /** POST /v1/checkout/products */
+    create(params: CreateProductParams): Promise<ApiResponse<CheckoutProduct>>;
+    /** GET /v1/checkout/products */
+    list(params?: ListProductsParams): Promise<ListResponse<CheckoutProduct>>;
+    /** GET /v1/checkout/products/:id */
+    retrieve(productId: string): Promise<ApiResponse<CheckoutProduct>>;
+    /** PATCH /v1/checkout/products/:id */
+    update(productId: string, params: UpdateProductParams): Promise<ApiResponse<CheckoutProduct>>;
+}
+declare class PricesResource {
+    private readonly request;
+    constructor(request: CatalogRequester);
+    /** POST /v1/checkout/products/:id/prices */
+    create(productId: string, params: CreatePriceParams): Promise<ApiResponse<CheckoutPrice>>;
+    /** GET /v1/checkout/products/:id/prices */
+    list(productId: string, params?: ListPricesParams): Promise<ListResponse<CheckoutPrice>>;
+    /** GET /v1/checkout/prices/:id */
+    retrieve(priceId: string): Promise<ApiResponse<CheckoutPrice>>;
+    /**
+     * PATCH /v1/checkout/prices/:id — nickname(표시 메타)만.
+     * 금액류 필드(amount_atomic 등)는 immutable — 서버가 PRICE_IMMUTABLE_FIELD로 거부한다.
+     * 가격 변경은 `prices.create()`로 새 price를 만들 것. "그만 팔기"는 해당 Price 를 쓰는
+     * Payment Link 를 inactive 로 한다(Price 자체에는 active/inactive 개념이 없다).
+     */
+    update(priceId: string, params: UpdatePriceParams): Promise<ApiResponse<CheckoutPrice>>;
+}
+/**
+ * Payment Link 리소스 — 대시보드 없이 코드로 결제 링크 생성/관리 (PROD-LINK-4).
+ *
+ * 흐름: product 생성 → price 생성 → payment link 생성. link↔price binding 은 생성 후 고정.
+ *
+ * ```ts
+ * const { data: product } = await bitpal.checkout.products.create({ name: 'Pro Plan' });
+ * const { data: price }   = await bitpal.checkout.prices.create(product.id, { amount: '29' });
+ * const { data: link }    = await bitpal.checkout.paymentLinks.create({
+ *   price_id: price.id,
+ *   allowed_pay_chains: ['eip155:8453', 'solana:5eykt4Us…'],
+ * });
+ * // 호스티드 결제 페이지 URL: `{checkoutBase}/plink/${link.share_token}`
+ * ```
+ */
+declare class PaymentLinksResource {
+    private readonly request;
+    constructor(request: CatalogRequester);
+    /** POST /v1/checkout/payment-links */
+    create(params: CreatePaymentLinkParams): Promise<ApiResponse<CheckoutPaymentLink>>;
+    /** GET /v1/checkout/payment-links */
+    list(params?: ListPaymentLinksParams): Promise<ListResponse<CheckoutPaymentLink>>;
+    /** GET /v1/checkout/payment-links/:id */
+    retrieve(linkId: string): Promise<ApiResponse<CheckoutPaymentLink>>;
+    /** PATCH /v1/checkout/payment-links/:id */
+    update(linkId: string, params: UpdatePaymentLinkParams): Promise<ApiResponse<CheckoutPaymentLink>>;
+}
 
 /**
  * @bitpal/checkout SDK — 클라이언트
@@ -282,24 +466,40 @@ interface ListResponse<T> {
  */
 
 declare class BitPalCheckoutClient {
+    /** 서버 메서드용 secret 키. 공개(buyer-facing) 메서드는 없이도 동작. */
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    /** PROD-LINK-3a-SDK: Product 카탈로그 관리 (server-side 전용) */
+    readonly products: ProductsResource;
+    /** PROD-LINK-3a-SDK: immutable Price 관리 — 가격 변경은 비활성화 + 새 price 생성 */
+    readonly prices: PricesResource;
+    /** PROD-LINK-4-SDK: Payment Link 관리 — 대시보드 없이 코드로 결제 링크 생성 (server-side 전용) */
+    readonly paymentLinks: PaymentLinksResource;
     constructor(config: BitPalConfig);
     private request;
     /**
      * 체크아웃 세션 생성.
      *
-     * 모든 `line_items[].amount`는 atomic μUSDC 정수 문자열이어야 한다 ($1 = "1000000").
-     * decimal 표기는 거부된다 — `toAtomicUSDC()` 헬퍼 사용 권장.
+     * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
+     * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
      *
      * @example
-     * import { BitPal, toAtomicUSDC } from '@bitpal/checkout';
+     * import { BitPal } from '@bitpal/checkout';
      * const bp = new BitPal('bp_test_...');
      * const { data } = await bp.checkout.createSession({
-     *   line_items: [{ name: 'Pro', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
+     *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+     *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      * });
      * console.log(data.url); // → buyer를 redirect할 결제 페이지
+     *
+     * // 멀티체인 허용 — 구매자가 Base/Optimism 중 선택(하나뿐이면 자동 선택):
+     * //   어떤 체인·토큰이든 amount 그대로 — 서버가 발급 시 토큰 decimals 로 재스케일.
+     * await bp.checkout.createSession({
+     *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
+     *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
+     * });
+     * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
      */
     createSession(params: CreateSessionParams): Promise<ApiResponse<CheckoutSession>>;
     /** 세션 조회 */
@@ -311,109 +511,40 @@ declare class BitPalCheckoutClient {
         offset?: number;
     }): Promise<ListResponse<CheckoutSession>>;
     /**
-     * Auto refund — escrow 보관 중일 때 컨트랙트가 buyer에게 직접 transfer.
-     *
-     * `params.amount` 미지정 시 backend가 잔액 전액(`type: 'full'`). 명시 시 `type: 'partial'`.
-     * **Idempotency-Key 권장** — 같은 키로 재시도 시 backend가 같은 결과 반환.
-     *
-     * 머천트가 `frozen` 상태면 환불은 허용되지만, `suspended` 상태에서는 차단된다.
-     *
-     * @example
-     * ```ts
-     * import { randomUUID } from 'node:crypto';
-     * const { data } = await bitpal.checkout.refundSession(
-     *   sessionId,
-     *   { amount: toAtomicUSDC('5.00'), reason: 'customer_requested' },
-     *   { idempotencyKey: randomUUID() },
-     * );
-     * console.log(data.txHash);  // on-chain tx hash (또는 simulation 환경에서 sim_xxx)
-     * ```
-     */
-    refundSession(sessionId: string, params?: RefundSessionParams, opts?: IdempotencyOptions): Promise<ApiResponse<RefundSessionResult>>;
-    /**
-     * Record refund — `status='settled'` 후 머천트가 외부 지갑에서 직접 송금하고 tx_hash를 입력.
-     * 컨트랙트 호출 없음 (DB-only).
-     *
-     * **Idempotency-Key 권장**.
+     * 공개 세션 조회 (`GET /v1/checkout/sessions/:id/public`) — 인증 불요.
      *
-     * @example
-     * ```ts
-     * await bitpal.checkout.recordRefund(
-     *   sessionId,
-     *   {
-     *     refund_amount: toAtomicUSDC('5.00'),
-     *     tx_hash: '0xabc...',
-     *     reason: 'manual_offchain_refund',
-     *   },
-     *   { idempotencyKey: randomUUID() },
-     * );
-     * ```
+     * buyer-facing 결제 페이지가 표시/자산선택에 쓰는 서버 권위 뷰. `payment_options` 로
+     * 구매자 선택 가능한 chain×token 을 얻고, 발급 후에는 `deposit_address` 가 채워진다.
      */
-    recordRefund(sessionId: string, params: RecordRefundParams, opts?: IdempotencyOptions): Promise<ApiResponse<RefundEntry>>;
-    /** 세션별 환불 내역 (auto + record 통합) */
-    listRefunds(sessionId: string): Promise<ListResponse<RefundEntry>>;
+    getPublicSession(sessionId: string): Promise<ApiResponse<PublicSession>>;
     /**
-     * CheckoutEscrow에 직접 입금한 외부 결제를 BitPal에 제출·검증.
+     * 주문별 비수탁 입금주소 발급 (`POST /v1/checkout/sessions/:id/deposit-address`).
      *
-     * Buyer가 merchant UI/SDK에서 `CheckoutEscrow.deposit*()` 함수를 직접 호출한 뒤
-     * 결과 tx_hash를 이 메서드로 제출한다. BitPal은 receipt를 fetch하여
-     * `PaymentDeposited` 이벤트를 검증하고 세션 상태를 갱신한다.
+     * 안2 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
+     * 그 주문 전용 CREATE2 forwarder 주소를 돌려준다. 구매자는 아무 지갑/거래소에서 **정확한 금액**을
+     * 그 주소로 일반 송금하면 된다(서명·연결 불필요). watcher 가 감지 → keeper 가 정산.
      *
-     * **인증 방식:**
-     * - Merchant server (API key): `Authorization: Bearer bp_test_*` 헤더 자동 첨부
-     * - Buyer 측 (session_token): `params.session_token` 전달
+     * refundAddress 는 입금주소에 커밋되어 발급 후 변경 불가. session_token 은 createSession 응답값.
      *
      * @example
      * ```ts
-     * // Merchant server — API key 인증
-     * const { data } = await bitpal.checkout.submitExternalPayment(sessionId, {
-     *   tx_hash: '0xabc...',
-     *   chain: 'base',
+     * const { data } = await bitpal.checkout.issueDepositAddress(sessionId, {
+     *   session_token: session.session_token!,
+     *   refundAddress: '0xBuyerWallet...',
+     *   chain: 'eip155:8453', // 멀티옵션 세션만 필요
+     *   token: 'USDC',
      * });
-     * console.log(data.validation_status); // 'valid' | 'underpaid' | 'overpaid' | ...
-     * console.log(data.session_status);    // 'paid' | 'unresolved_underpaid' | ...
+     * console.log(data.depositAddress, data.expectedAmount); // 이 주소로 정확 금액 송금
      * ```
      */
-    submitExternalPayment(sessionId: string, params: SubmitExternalPaymentParams, opts?: IdempotencyOptions): Promise<ApiResponse<SubmitExternalPaymentResult>>;
+    issueDepositAddress(sessionId: string, params: IssueDepositAddressParams): Promise<ApiResponse<DepositAddress>>;
     /**
-     * Gasless checkout payment through the BitPal API relayer.
+     * 경량 상태 폴링 (`GET /v1/checkout/sessions/:id/status`) — 인증 불요.
      *
-     * The buyer signs **two** EIP-712 typed-data structures and the API calls
-     * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer:
-     *
-     * 1. **EIP-3009 USDC TransferWithAuthorization** (`params.authorization`) —
-     *    authorizes USDC transfer from buyer to escrow.
-     * 2. **PaymentAuthorization** (`params.payment_auth`, since SDK v0.2.0) —
-     *    binds the entire payment intent (paymentId, merchant, amount, fee,
-     *    reserve, duration) to the buyer's signature. Without this, a compromised
-     *    gateway key could redirect funds to an attacker-controlled merchant.
-     *
-     * Build the PaymentAuthorization typed-data with `buildPaymentAuthTypedData()`.
-     * The PaymentAuthorization nonce comes from `CheckoutEscrow.paymentAuthNonce(payer)`.
-     *
-     * Use the returned session/order state only as immediate UX feedback; the
-     * merchant backend should finalize fulfillment from signed webhooks.
-     *
-     * @breaking-change v0.2.0 — `payment_auth` field is now required. v0.1.x clients
-     *                          must upgrade their signing flow. See MIGRATION_v0.2.md.
-     */
-    payWithAuthorization(sessionId: string, params: PayWithAuthorizationParams, opts?: IdempotencyOptions): Promise<ApiResponse<CheckoutPaymentResult>>;
-    /**
-     * 세션의 external on-chain 결제 검증 기록 목록 조회.
-     *
-     * `getSession()`의 `payment_observations` 필드와 동일한 데이터를 반환하지만
-     * 검증 기록만 명시적으로 조회할 때 사용한다.
-     *
-     * @example
-     * ```ts
-     * const { data } = await bitpal.checkout.getExternalPaymentStatus(sessionId);
-     * const latest = data[0];
-     * if (latest?.finality_status === 'final_confirmed') {
-     *   // 12 confirmations 완료 — 결제 확정
-     * }
-     * ```
+     * status: awaiting_deposit → deposit_detected → paid_confirmed/swept. 확정/정산은 webhook 으로도
+     * 통지되므로, 서버 사이드 확정은 webhook 을 신뢰(폴링은 buyer UX 용).
      */
-    getExternalPaymentStatus(sessionId: string): Promise<ApiResponse<PaymentObservation[]>>;
+    getStatus(sessionId: string): Promise<ApiResponse<SessionStatus>>;
     /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
     previewFee(amount: string): Promise<ApiResponse<FeePreview>>;
 }
@@ -425,18 +556,12 @@ declare class BitPalError extends Error {
 /**
  * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
  *
- * BitPal backend의 canonical webhook contract와 1:1 정합:
- *   apps/api/src/services/webhook-canonical-delivery.ts
- *   apps/api/src/__tests__/webhook-canonical-delivery.test.ts
- *
- * 이벤트 명/서명 형식이 backend와 drift하면 머천트 검증이 깨진다.
+ * BitPal 이 보내는 canonical webhook contract(envelope/서명/헤더)와 1:1 정합한다.
  */
 /**
- * 발송되는 webhook 이벤트 타입.
- * Backend `services/checkout-webhook.ts:CHECKOUT_WEBHOOK_EVENTS`와 동일 — drift 시
- * 머천트 코드의 분기 매칭이 실패한다.
+ * BitPal 이 발송하는 webhook 이벤트 타입 전체 목록.
  */
-declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.session.release_deferred", "checkout.payment.failed", "checkout.payment.finalized", "checkout.payment.revoked", "checkout.refund.recorded", "checkout.refund.completed", "checkout.refund.partial"];
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded"];
 type CheckoutWebhookEvent = (typeof CHECKOUT_WEBHOOK_EVENTS)[number];
 /**
  * Canonical envelope (HTTP body).
@@ -482,16 +607,29 @@ declare const WEBHOOK_HEADERS: {
  * import { verifyWebhookSignature, parseWebhookEvent, WEBHOOK_HEADERS } from '@bitpal/checkout';
  *
  * app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
- *   const sig = req.header(WEBHOOK_HEADERS.signature) ?? '';
- *   const ok = await verifyWebhookSignature(req.body.toString(), sig, process.env.BITPAL_WEBHOOK_SECRET!);
+ *   const raw = req.body.toString('utf8'); // raw body — parse/re-serialize 하면 서명 깨짐
+ *   const ok = await verifyWebhookSignature(
+ *     raw,
+ *     req.header(WEBHOOK_HEADERS.signature) ?? '',
+ *     process.env.BITPAL_WEBHOOK_SECRET!,
+ *     { timestamp: req.header(WEBHOOK_HEADERS.timestamp) ?? '' }, // replay 방어 — 필수
+ *   );
  *   if (!ok) return res.status(400).send('invalid signature');
- *   const event = parseWebhookEvent(req.body.toString());
+ *   const event = parseWebhookEvent(raw);
+ *   // dedup 은 서명된 body 의 event.id 로 (헤더 X-Webhook-Id 는 미서명)
+ *   if (await alreadyProcessed(event.id)) return res.status(200).send('dup');
  *   if (event.event === 'checkout.session.paid') { ... }
  *   res.status(200).send('ok');
  * });
  * ```
  */
-declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+interface VerifyWebhookOptions {
+    /** `X-Webhook-Timestamp` 헤더 값(ISO UTC). 서명 대상에 포함되며 freshness 검사에 쓰인다. 필수. */
+    timestamp: string;
+    /** freshness 허용 오차(초). 기본 300(5분). |now - timestamp| 초과 시 replay 로 간주해 거부. */
+    toleranceSec?: number;
+}
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string, opts?: VerifyWebhookOptions): Promise<boolean>;
 /**
  * Webhook envelope 파싱.
  * 형식 검증 후 `WebhookPayload` 타입으로 캐스팅.
@@ -501,185 +639,43 @@ declare function verifyWebhookSignature(payload: string, signature: string, secr
 declare function parseWebhookEvent(body: string): WebhookPayload;
 
 /**
- * amount.ts — atomic μUSDC 변환 헬퍼
+ * amount.ts — atomic ↔ decimal 변환 헬퍼 (임의 decimals + USDC 하위호환)
  *
- * BitPal API는 모든 amount를 atomic 정수 문자열로 받는다 (USDC/USDT 6 decimals).
- *   $1   → "1000000"
- *   $10  → "10000000"
- *   $0.5 → "500000"
+ * BitPal API는 모든 amount를 atomic 정수 문자열로 받는다. decimals 는 토큰마다 다르다:
+ *   USDC/USDT(Base/Arb/Tron/Solana) = 6, BSC-USD(BNB USDT) = 18. → payment_options[].decimals /
+ *   PublicSession.token_decimals 로 서버가 내려준다. 6dp 를 하드코딩하면 non-6dp 토큰에서 금액이 틀린다.
  *
  * 정밀도 손실 방지를 위해 BigInt 연산만 사용한다 (Number 변환 금지 — CLAUDE.md 정책).
+ *   $1(6dp)   → "1000000"     $1(18dp) → "1000000000000000000"
  */
 /**
- * decimal 문자열 → atomic μUSDC 문자열
- *
- * @example
- * toAtomicUSDC('29.00')   // → '29000000'
- * toAtomicUSDC('0.5')     // → '500000'
- * toAtomicUSDC('1000')    // → '1000000000'
+ * decimal 문자열 → atomic 문자열 (임의 decimals).
  *
- * @throws {Error} 음수, 6자리 초과 소수, 형식 오류
+ * @param decimal 소수 문자열(음수 불가, 소수 자리 ≤ decimals)
+ * @param decimals 토큰 decimals (예: 6, 18). payment_options[].decimals 사용.
+ * @throws {Error} 음수, decimals 초과 소수 자리, 형식 오류
+ * @example toAtomic('29.00', 6) // '29000000'   toAtomic('1.5', 18) // '1500000000000000000'
  */
-declare function toAtomicUSDC(decimal: string): string;
+declare function toAtomic(decimal: string, decimals: number): string;
 /**
- * atomic μUSDC 문자열 → 사람이 읽기 좋은 decimal 문자열
- *
- * @example
- * fromAtomicUSDC('29000000')   // → '29.00'
- * fromAtomicUSDC('500000')     // → '0.50'
- * fromAtomicUSDC('1500000')    // → '1.50'
+ * atomic 문자열 → 사람이 읽기 좋은 decimal 문자열 (임의 decimals).
+ * 최소 2자리 소수를 유지하되(예: '29.00'), decimals 만큼만 노출.
  *
  * @throws {Error} 정수 문자열이 아니면
+ * @example fromAtomic('29000000', 6) // '29.00'   fromAtomic('1500000000000000000', 18) // '1.50'
  */
-declare function fromAtomicUSDC(atomic: string): string;
-
+declare function fromAtomic(atomic: string, decimals: number): string;
 /**
- * typed-data.ts — Q5 C-01 옵션 2 (SDK v0.2.0).
- *
- * BitPal Checkout 의 EIP-712 typed-data helper. SDK 가 모든 typed-data 작업을 직접
- * 수행하지 않고 (서명은 머천트의 wallet provider 가) **typed-data 객체만 생성** 한다.
- *
- * 사용 예 (viem):
- *
- * ```ts
- * import { buildPaymentAuthTypedData } from '@bitpal/checkout';
- * import { signTypedData } from 'viem/accounts';
- *
- * const td = buildPaymentAuthTypedData({
- *   escrowAddress: '0x...',
- *   chainId: 8453,
- *   paymentId: '0x...',     // = toBytes32(sessionId)
- *   payer: buyer.address,
- *   merchant: session.seller_wallet,
- *   token: session.token_address,
- *   amount: session.amount_total,
- *   feeAmount: '0',
- *   reserveAmount: '0',
- *   duration: '0',
- *   deadline: String(Math.floor(Date.now()/1000) + 3600),
- *   nonce: String(await escrow.read.paymentAuthNonce(buyer.address)),
- * });
- * const sig = await walletClient.signTypedData(td);
- * ```
- *
- * 사용 예 (wagmi `useSignTypedData`):
- *
- * ```tsx
- * const { signTypedDataAsync } = useSignTypedData();
- * const td = buildPaymentAuthTypedData({ ... });
- * const sig = await signTypedDataAsync(td);
- * ```
- */
-
-/**
- * Build EIP-712 typed-data object for PaymentAuthorization signing.
- * Returns a viem-compatible structure (also compatible with wagmi/ethers v6 signTypedData).
+ * decimal → atomic μUSDC (6dp). 하위호환 별칭 — 새 코드는 `toAtomic(decimal, decimals)` 권장
+ *   (BNB USDT=18dp 등 non-6dp 토큰은 이 헬퍼로 처리 불가).
+ * @example toAtomicUSDC('29.00') // '29000000'
  */
-declare function buildPaymentAuthTypedData(args: PaymentAuthTypedDataArgs): {
-    readonly domain: {
-        readonly name: "CheckoutEscrow";
-        readonly version: "1";
-        readonly chainId: number;
-        readonly verifyingContract: `0x${string}`;
-    };
-    readonly types: {
-        readonly PaymentAuthorization: readonly [{
-            readonly name: "paymentId";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "payer";
-            readonly type: "address";
-        }, {
-            readonly name: "merchant";
-            readonly type: "address";
-        }, {
-            readonly name: "token";
-            readonly type: "address";
-        }, {
-            readonly name: "amount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "feeAmount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "reserveAmount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "duration";
-            readonly type: "uint256";
-        }, {
-            readonly name: "deadline";
-            readonly type: "uint256";
-        }, {
-            readonly name: "nonce";
-            readonly type: "uint256";
-        }];
-    };
-    readonly primaryType: "PaymentAuthorization";
-    readonly message: {
-        readonly paymentId: `0x${string}`;
-        readonly payer: `0x${string}`;
-        readonly merchant: `0x${string}`;
-        readonly token: `0x${string}`;
-        readonly amount: bigint;
-        readonly feeAmount: bigint;
-        readonly reserveAmount: bigint;
-        readonly duration: bigint;
-        readonly deadline: bigint;
-        readonly nonce: bigint;
-    };
-};
-/**
- * Args for the EIP-712 ConfirmReceipt typed-data.
- * Used when buyer signs an off-chain receipt confirmation that BitPal gateway relays
- * on-chain via `confirmReceiptWithSignature` (Q4 H-01).
- */
-interface ConfirmReceiptTypedDataArgs {
-    escrowAddress: string;
-    chainId: number;
-    paymentId: string;
-    payer: string;
-    deadline: string;
-    nonce: string;
-}
-/**
- * Build EIP-712 typed-data object for ConfirmReceipt signing (Q4 H-01).
- */
-declare function buildConfirmReceiptTypedData(args: ConfirmReceiptTypedDataArgs): {
-    readonly domain: {
-        readonly name: "CheckoutEscrow";
-        readonly version: "1";
-        readonly chainId: number;
-        readonly verifyingContract: `0x${string}`;
-    };
-    readonly types: {
-        readonly ConfirmReceipt: readonly [{
-            readonly name: "paymentId";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "payer";
-            readonly type: "address";
-        }, {
-            readonly name: "deadline";
-            readonly type: "uint256";
-        }, {
-            readonly name: "nonce";
-            readonly type: "uint256";
-        }];
-    };
-    readonly primaryType: "ConfirmReceipt";
-    readonly message: {
-        readonly paymentId: `0x${string}`;
-        readonly payer: `0x${string}`;
-        readonly deadline: bigint;
-        readonly nonce: bigint;
-    };
-};
+declare function toAtomicUSDC(decimal: string): string;
 /**
- * Convert a session ID string into a 32-byte hex (`paymentId`) suitable for typed-data signing.
- * Mirrors the backend `toBytes32(sessionId)` helper.
+ * atomic μUSDC(6dp) → decimal. 하위호환 별칭 — 새 코드는 `fromAtomic(atomic, decimals)` 권장.
+ * @example fromAtomicUSDC('29000000') // '29.00'
  */
-declare function sessionIdToPaymentId(sessionId: string): `0x${string}`;
+declare function fromAtomicUSDC(atomic: string): string;
 
 /**
  * @bitpal/checkout — BitPal Checkout SDK
@@ -693,10 +689,11 @@ declare function sessionIdToPaymentId(sessionId: string): `0x${string}`;
  * const bitpal = new BitPal({ apiKey: 'bp_test_...' });
  *
  * const { data: session } = await bitpal.checkout.createSession({
- *   line_items: [{ name: 'Pro Plan', amount: '29.00', currency: 'USDC' }],
+ *   // amount: 사람 표기 USD("29","0.5"). decimal 계산 불필요 — 체인/토큰 decimal 무관.
+ *   line_items: [{ name: 'Pro Plan', amount: '29', currency: 'USDC' }],
  * });
  *
- * console.log(session.url); // 호스티드 결제 페이지 URL
+ * console.log(session.url); // 호스티드 결제 페이지 URL (checkout_url 별칭)
  * ```
  */
 
@@ -708,4 +705,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutPaymentResult, type CheckoutSession, type CheckoutWebhookEvent, type ConfirmReceiptTypedDataArgs, type CreateSessionParams, type ExternalPaymentConfig, type FeePreview, type IdempotencyOptions, type LineItem, type ListResponse, type PayWithAuthorizationParams, type PaymentAuthTypedDataArgs, type PaymentObservation, type RecordRefundParams, type RefundEntry, type RefundSessionParams, type RefundSessionResult, type SubmitExternalPaymentParams, type SubmitExternalPaymentResult, WEBHOOK_HEADERS, type WebhookPayload, buildConfirmReceiptTypedData, buildPaymentAuthTypedData, fromAtomicUSDC, parseWebhookEvent, sessionIdToPaymentId, toAtomicUSDC, verifyWebhookSignature };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type DepositAddress, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPaymentLinksParams, type ListPricesParams, type ListProductsParams, type ListResponse, PaymentLinksResource, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, fromAtomic, fromAtomicUSDC, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature };