@bitpal/checkout 0.3.0 → 0.5.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 컨트랙트
@@ -32,12 +36,24 @@ interface LineItem {
     currency: string;
     quantity?: number;
 }
+interface PriceLineItem {
+    /** price_... — bitpal.checkout.prices.create()로 만든 가격 */
+    price_id: string;
+    quantity?: number;
+}
+type CheckoutLineItemInput = LineItem | 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 +83,8 @@ interface CheckoutSession {
     settled_at: string | null;
     tx_hash: string | null;
     created_at: string;
-    /** 'hosted' | 'external' — 결제 경로 구분 */
+    /** 'hosted' — 결제 경로. 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 +92,89 @@ 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;
-    decimals: number;
-    supported_methods: Array<'authorization_relay'>;
-}
 /**
- * CheckoutEscrow.PaymentDeposited 이벤트 단위 검증 기록.
- * `GET /v1/checkout/sessions/:id` 응답의 `payment_observations` 배열 원소.
+ * 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
+ * `issueDepositAddress({ chain, token })` 로 입금주소를 발급받는다. 단일-자산 세션은 1개.
  */
-interface PaymentObservation {
-    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_at: string;
+interface PaymentOption {
+    /** CAIP-2 (예: eip155:8453) */
+    caip2: string;
+    chain_id: number;
+    token_symbol: string;
+    token_address: string;
 }
 /**
- * `submitExternalPayment` 요청 파라미터.
- * 검증에 필요한 값은 tx_hash + chain만으로 충분 — payer_wallet, asset 등은 on-chain 이벤트에서 도출.
+ * `getPublicSession()` (`GET /v1/checkout/sessions/:id/public`) 응답 — 인증 불요(공개).
+ * buyer-facing 결제 페이지가 표시/폴링에 쓰는 서버 권위 뷰.
  */
-interface SubmitExternalPaymentParams {
-    /** CheckoutEscrow 입금 tx hash (0x...) */
-    tx_hash: string;
-    /** 체인 식별자 (기본값: 'base'). 예: 'base', 'bnb', 'polygon' */
-    chain?: string;
-    /** Public session token — buyer 측 제출 시 사용. API key 인증 시 불필요. */
-    session_token?: string;
+interface PublicSession {
+    id: string;
+    /** 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;
+    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` 응답.
+ * `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 는 미지원.
-     */
-    payment_auth: {
-        deadline: string;
-        duration: string;
-        v: number;
-        r: string;
-        s: string;
-    };
+    /** 환불 주소(0x EVM). 필수. */
+    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;
+    /** 주문별 CREATE2 forwarder 입금주소. */
+    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 +188,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 +206,125 @@ 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';
+}
+interface CreatePriceParams {
+    /** 원자 단위 정수 문자열 ($1 = "1000000"). `toAtomicUSDC('1.00')` 헬퍼 사용 권장 */
+    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;
+}
+
+/**
+ * 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>>;
+}
 
 /**
  * @bitpal/checkout SDK — 클라이언트
@@ -282,9 +334,14 @@ 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;
     constructor(config: BitPalConfig);
     private request;
     /**
@@ -300,6 +357,13 @@ declare class BitPalCheckoutClient {
      *   line_items: [{ name: 'Pro', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
      * });
      * console.log(data.url); // → buyer를 redirect할 결제 페이지
+     *
+     * // 멀티체인 허용 — 구매자가 Base/Optimism 중 선택(하나뿐이면 자동 선택):
+     * await bp.checkout.createSession({
+     *   line_items: [{ name: 'Pro', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
+     *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
+     * });
+     * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
      */
     createSession(params: CreateSessionParams): Promise<ApiResponse<CheckoutSession>>;
     /** 세션 조회 */
@@ -311,109 +375,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` 이벤트를 검증하고 세션 상태를 갱신한다.
+     * 비수탁 결제 진입점. 구매자가 자산(멀티옵션이면 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.
-     *
-     * 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.
+     * 경량 상태 폴링 (`GET /v1/checkout/sessions/:id/status`) — 인증 불요.
      *
-     * @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.
+     * status: awaiting_deposit → deposit_detected → paid_confirmed/swept. 확정/정산은 webhook 으로도
+     * 통지되므로, 서버 사이드 확정은 webhook 을 신뢰(폴링은 buyer UX 용).
      */
-    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 완료 — 결제 확정
-     * }
-     * ```
-     */
-    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 +420,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 +471,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` 타입으로 캐스팅.
@@ -533,154 +535,6 @@ declare function toAtomicUSDC(decimal: string): string;
  */
 declare function fromAtomicUSDC(atomic: string): 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).
- */
-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;
-    };
-};
-/**
- * Convert a session ID string into a 32-byte hex (`paymentId`) suitable for typed-data signing.
- * Mirrors the backend `toBytes32(sessionId)` helper.
- */
-declare function sessionIdToPaymentId(sessionId: string): `0x${string}`;
-
 /**
  * @bitpal/checkout — BitPal Checkout SDK
  *
@@ -693,10 +547,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 는 원자 단위 μUSDC 문자열(6 decimals). $29.00 → '29000000'. toAtomicUSDC 사용 권장.
+ *   line_items: [{ name: 'Pro Plan', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
  * });
  *
- * console.log(session.url); // 호스티드 결제 페이지 URL
+ * console.log(session.url); // 호스티드 결제 페이지 URL (checkout_url 별칭)
  * ```
  */
 
@@ -708,4 +563,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 CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type DepositAddress, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPricesParams, type ListProductsParams, type ListResponse, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, fromAtomicUSDC, parseWebhookEvent, toAtomicUSDC, verifyWebhookSignature };