@bitpal/checkout 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,15 +1,80 @@
+// src/catalog.ts
+function toQuery(params) {
+  if (!params) return "";
+  const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+  if (entries.length === 0) return "";
+  const qs = new URLSearchParams(entries.map(([k, v]) => [k, String(v)]));
+  return `?${qs.toString()}`;
+}
+var ProductsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  /** POST /v1/checkout/products */
+  create(params) {
+    return this.request("POST", "/v1/checkout/products", params);
+  }
+  /** GET /v1/checkout/products */
+  list(params) {
+    return this.request("GET", `/v1/checkout/products${toQuery(params)}`);
+  }
+  /** GET /v1/checkout/products/:id */
+  retrieve(productId) {
+    return this.request("GET", `/v1/checkout/products/${encodeURIComponent(productId)}`);
+  }
+  /** PATCH /v1/checkout/products/:id */
+  update(productId, params) {
+    return this.request("PATCH", `/v1/checkout/products/${encodeURIComponent(productId)}`, params);
+  }
+};
+var PricesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  /** POST /v1/checkout/products/:id/prices */
+  create(productId, params) {
+    return this.request("POST", `/v1/checkout/products/${encodeURIComponent(productId)}/prices`, params);
+  }
+  /** GET /v1/checkout/products/:id/prices */
+  list(productId, params) {
+    return this.request("GET", `/v1/checkout/products/${encodeURIComponent(productId)}/prices${toQuery(params)}`);
+  }
+  /** GET /v1/checkout/prices/:id */
+  retrieve(priceId) {
+    return this.request("GET", `/v1/checkout/prices/${encodeURIComponent(priceId)}`);
+  }
+  /**
+   * PATCH /v1/checkout/prices/:id — nickname(표시 메타)만.
+   * 금액류 필드(amount_atomic 등)는 immutable — 서버가 PRICE_IMMUTABLE_FIELD로 거부한다.
+   * 가격 변경은 `prices.create()`로 새 price를 만들 것. "그만 팔기"는 해당 Price 를 쓰는
+   * Payment Link 를 inactive 로 한다(Price 자체에는 active/inactive 개념이 없다).
+   */
+  update(priceId, params) {
+    return this.request("PATCH", `/v1/checkout/prices/${encodeURIComponent(priceId)}`, params);
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.bitpal.io";
 var DEFAULT_TIMEOUT = 3e4;
 var BitPalCheckoutClient = class {
+  /** 서버 메서드용 secret 키. 공개(buyer-facing) 메서드는 없이도 동작. */
   apiKey;
   baseUrl;
   timeout;
+  /** PROD-LINK-3a-SDK: Product 카탈로그 관리 (server-side 전용) */
+  products;
+  /** PROD-LINK-3a-SDK: immutable Price 관리 — 가격 변경은 비활성화 + 새 price 생성 */
+  prices;
   constructor(config) {
-    if (!config.apiKey) throw new Error("apiKey is required");
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    const requester = (method, path, body) => this.request(method, path, body);
+    this.products = new ProductsResource(requester);
+    this.prices = new PricesResource(requester);
   }
   /* ─── 내부 HTTP ─── */
   async request(method, path, body, extraHeaders) {
@@ -21,7 +86,8 @@ var BitPalCheckoutClient = class {
         method,
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`,
+          // 공개 메서드(session_token 기반)는 apiKey 없이 호출 가능 — 있을 때만 Authorization 첨부.
+          ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {},
           ...extraHeaders ?? {}
         },
         body: body ? JSON.stringify(body) : void 0,
@@ -51,8 +117,18 @@ var BitPalCheckoutClient = class {
    *   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 사용(둘은 상호 배타).
    */
   async createSession(params) {
+    if (params.pay_chain && params.allowed_pay_chains && params.allowed_pay_chains.length > 0) {
+      throw new Error("[BitPal] pay_chain and allowed_pay_chains are mutually exclusive \u2014 use only one.");
+    }
     const res = await this.request(
       "POST",
       "/v1/checkout/sessions",
@@ -86,148 +162,56 @@ var BitPalCheckoutClient = class {
       `/v1/checkout/sessions${query ? `?${query}` : ""}`
     );
   }
-  /* ─── Refunds ─── */
-  /**
-   * 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)
-   * ```
-   */
-  async refundSession(sessionId, params = {}, opts) {
-    return this.request(
-      "POST",
-      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/refund`,
-      params,
-      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
-    );
-  }
+  /* ─── 비수탁 결제 (deposit-address) ─── */
   /**
-   * 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` 가 채워진다.
    */
-  async recordRefund(sessionId, params, opts) {
-    return this.request(
-      "POST",
-      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/record-refund`,
-      params,
-      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
-    );
-  }
-  /** 세션별 환불 내역 (auto + record 통합) */
-  async listRefunds(sessionId) {
+  async getPublicSession(sessionId) {
     return this.request(
       "GET",
-      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/refunds`
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/public`
     );
   }
-  /* ─── External On-chain Payments ─── */
   /**
-   * 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); // 이 주소로 정확 금액 송금
    * ```
    */
-  async submitExternalPayment(sessionId, params, opts) {
+  async issueDepositAddress(sessionId, params) {
     return this.request(
       "POST",
-      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/submit-external-payment`,
-      params,
-      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
-    );
-  }
-  /**
-   * 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.
-   *
-   * @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.
-   */
-  async payWithAuthorization(sessionId, params, opts) {
-    return this.request(
-      "POST",
-      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/submit-payment`,
-      params,
-      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/deposit-address`,
+      params
     );
   }
   /**
-   * 세션의 external on-chain 결제 검증 기록 목록 조회.
-   *
-   * `getSession()`의 `payment_observations` 필드와 동일한 데이터를 반환하지만
-   * 검증 기록만 명시적으로 조회할 때 사용한다.
+   * 경량 상태 폴링 (`GET /v1/checkout/sessions/:id/status`) — 인증 불요.
    *
-   * @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 용).
    */
-  async getExternalPaymentStatus(sessionId) {
+  async getStatus(sessionId) {
     return this.request(
       "GET",
-      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/payment-observations`
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/status`
     );
   }
   /* ─── Fees ─── */
@@ -251,17 +235,12 @@ var BitPalError = class extends Error {
 // src/webhook.ts
 var CHECKOUT_WEBHOOK_EVENTS = [
   "checkout.session.created",
+  "checkout.session.deposit_detected",
   "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"
+  "checkout.refund.recorded"
 ];
 var WEBHOOK_HEADERS = {
   signature: "X-Webhook-Signature-256",
@@ -271,14 +250,21 @@ var WEBHOOK_HEADERS = {
   deliveryId: "X-Webhook-Delivery-Id"
 };
 var SIGNATURE_PREFIX = "sha256=";
-async function verifyWebhookSignature(payload, signature, secret) {
+async function verifyWebhookSignature(payload, signature, secret, opts) {
   if (!payload || !signature || !secret) return false;
   if (!signature.startsWith(SIGNATURE_PREFIX)) return false;
+  const timestamp = opts?.timestamp;
+  if (!timestamp) return false;
+  const parsedMs = Date.parse(timestamp);
+  if (!Number.isFinite(parsedMs)) return false;
+  if (new Date(parsedMs).toISOString() !== timestamp) return false;
+  const toleranceMs = (opts?.toleranceSec ?? 300) * 1e3;
+  if (Math.abs(Date.now() - parsedMs) > toleranceMs) return false;
   const sigHex = signature.slice(SIGNATURE_PREFIX.length);
-  if (!/^[0-9a-f]+$/.test(sigHex)) return false;
+  if (!/^[0-9a-f]{64}$/.test(sigHex)) return false;
   try {
     const crypto = await import("crypto");
-    const expectedHex = crypto.createHmac("sha256", secret).update(payload, "utf8").digest("hex");
+    const expectedHex = crypto.createHmac("sha256", secret).update(`${timestamp}.${payload}`, "utf8").digest("hex");
     if (sigHex.length !== expectedHex.length) return false;
     return crypto.timingSafeEqual(
       Buffer.from(sigHex, "hex"),
@@ -303,7 +289,7 @@ function toAtomicUSDC(decimal) {
   if (typeof decimal !== "string" || !/^\d+(\.\d{1,6})?$/.test(decimal)) {
     throw new Error(`toAtomicUSDC: invalid decimal '${decimal}' (max 6 fractional digits, no negatives)`);
   }
-  const [whole, frac = ""] = decimal.split(".");
+  const [whole = "0", frac = ""] = decimal.split(".");
   const fracPadded = frac.padEnd(Number(USDC_DECIMALS), "0");
   return (BigInt(whole) * USDC_SCALE + BigInt(fracPadded || "0")).toString();
 }
@@ -318,74 +304,6 @@ function fromAtomicUSDC(atomic) {
   return fracStr.length > 0 ? `${whole}.${fracStr.padEnd(2, "0")}` : `${whole}.00`;
 }
 
-// src/typed-data.ts
-function buildPaymentAuthTypedData(args) {
-  return {
-    domain: {
-      name: "CheckoutEscrow",
-      version: "1",
-      chainId: args.chainId,
-      verifyingContract: args.escrowAddress
-    },
-    types: {
-      PaymentAuthorization: [
-        { name: "paymentId", type: "bytes32" },
-        { name: "payer", type: "address" },
-        { name: "merchant", type: "address" },
-        { name: "token", type: "address" },
-        { name: "amount", type: "uint256" },
-        { name: "feeAmount", type: "uint256" },
-        { name: "reserveAmount", type: "uint256" },
-        { name: "duration", type: "uint256" },
-        { name: "deadline", type: "uint256" },
-        { name: "nonce", type: "uint256" }
-      ]
-    },
-    primaryType: "PaymentAuthorization",
-    message: {
-      paymentId: args.paymentId,
-      payer: args.payer,
-      merchant: args.merchant,
-      token: args.token,
-      amount: BigInt(args.amount),
-      feeAmount: BigInt(args.feeAmount),
-      reserveAmount: BigInt(args.reserveAmount),
-      duration: BigInt(args.duration),
-      deadline: BigInt(args.deadline),
-      nonce: BigInt(args.nonce)
-    }
-  };
-}
-function buildConfirmReceiptTypedData(args) {
-  return {
-    domain: {
-      name: "CheckoutEscrow",
-      version: "1",
-      chainId: args.chainId,
-      verifyingContract: args.escrowAddress
-    },
-    types: {
-      ConfirmReceipt: [
-        { name: "paymentId", type: "bytes32" },
-        { name: "payer", type: "address" },
-        { name: "deadline", type: "uint256" },
-        { name: "nonce", type: "uint256" }
-      ]
-    },
-    primaryType: "ConfirmReceipt",
-    message: {
-      paymentId: args.paymentId,
-      payer: args.payer,
-      deadline: BigInt(args.deadline),
-      nonce: BigInt(args.nonce)
-    }
-  };
-}
-function sessionIdToPaymentId(sessionId) {
-  const hex = Array.from(new TextEncoder().encode(sessionId)).map((b) => b.toString(16).padStart(2, "0")).join("").padEnd(64, "0");
-  return `0x${hex}`;
-}
-
 // src/index.ts
 var BitPal = class {
   checkout;
@@ -399,12 +317,11 @@ export {
   BitPalCheckoutClient,
   BitPalError,
   CHECKOUT_WEBHOOK_EVENTS,
+  PricesResource,
+  ProductsResource,
   WEBHOOK_HEADERS,
-  buildConfirmReceiptTypedData,
-  buildPaymentAuthTypedData,
   fromAtomicUSDC,
   parseWebhookEvent,
-  sessionIdToPaymentId,
   toAtomicUSDC,
   verifyWebhookSignature
 };

package/package.json

@@ -1,21 +1,35 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.3.0",
-  "description": "BitPal Checkout SDK — crypto payment sessions, external on-chain payment verification, gasless checkout (with PaymentAuthorization double-defense), refunds, fee preview.",
-  "license": "UNLICENSED",
+  "version": "0.5.0",
+  "description": "BitPal Checkout SDK — non-custodial crypto checkout: create sessions, issue per-order deposit addresses, poll status, verify signed webhooks.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superlabs-x/bitpal-checkout-sdk.git"
+  },
+  "homepage": "https://github.com/superlabs-x/bitpal-checkout-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/superlabs-x/bitpal-checkout-sdk/issues"
+  },
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
     "dist",
-    "README.md",
-    "MIGRATION_v0.2.md"
+    "README.md"
   ],
   "keywords": [
     "bitpal",
@@ -27,7 +41,7 @@
     "evm",
     "base",
     "stablecoin",
-    "escrow"
+    "non-custodial"
   ],
   "publishConfig": {
     "access": "public"
@@ -35,15 +49,17 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm test && npm run build",
+    "release": "npm publish --access public"
+  },
   "devDependencies": {
+    "@types/node": "^20.11.0",
     "tsup": "^8.5.1",
     "typescript": "^5.5.0",
     "vitest": "^2.1.9"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "lint": "tsc --noEmit",
-    "test": "vitest run",
-    "release": "pnpm publish --access public --no-git-checks"
   }
-}
+}

package/MIGRATION_v0.2.md

@@ -1,135 +0,0 @@
-# @bitpal/checkout — Migration Guide v0.1.x → v0.2.0
-
-> Audit doc 11 §3 C-01 option 2 (PaymentAuthorization 이중방어) 적용으로 인한 SDK 메이저 bump.
-
-## Why this change
-
-v0.1.x 까지의 `payWithAuthorization` 흐름은 buyer 의 EIP-3009 USDC sig 만 받았다. 이 sig 는
-`(from, to, value, validAfter, validBefore, nonce)` 만 바인딩하므로, **paymentId / merchant /
-amount / fee / reserve / duration** 은 호출자(BitPal gateway)가 자유롭게 지정 가능했다.
-
-→ gateway 키 탈취 시 공격자가 (a) buyer 의 EIP-3009 sig 입수 후 (b) 자기 주소를 merchant 로 설정,
-   (c) `depositWithAuthorization` 호출 → buyer 자금이 attacker merchant 로 흘러간다.
-
-v0.2.0 는 buyer 가 **결제 의도 전체** 에 별도 EIP-712 서명 (`PaymentAuthorization`) 을 한다. gateway
-키 탈취 시에도 buyer 의도 밖 결제 생성 불가 (이중방어).
-
-## Breaking changes
-
-### `BitPal.checkout.payWithAuthorization(sessionId, params)`
-
-`params.payment_auth` 필드가 **필수** 가 됐다.
-
-**Before (v0.1.x):**
-```ts
-await bp.checkout.payWithAuthorization(sessionId, {
-  session_token: 'xyz...',
-  chain: 'base',
-  authorization: {
-    from: buyer.address,
-    validAfter: '0',
-    validBefore: String(Math.floor(Date.now()/1000) + 3600),
-    authNonce: '0x...',
-    v: 27, r: '0x...', s: '0x...',
-  },
-});
-```
-
-**After (v0.2.0):**
-```ts
-import {
-  buildPaymentAuthTypedData,
-  sessionIdToPaymentId,
-} from '@bitpal/checkout';
-
-// 1. PaymentAuthorization nonce 조회 (CheckoutEscrow.paymentAuthNonce)
-const nonce = await escrow.read.paymentAuthNonce([buyer.address]);
-
-// 2. PaymentAuthorization typed-data sig
-const paymentAuthDeadline = Math.floor(Date.now()/1000) + 3600;
-const paymentId = sessionIdToPaymentId(sessionId);
-const paymentAuthTd = buildPaymentAuthTypedData({
-  escrowAddress: escrow.address,
-  chainId: 8453,
-  paymentId,
-  payer: buyer.address,
-  merchant: session.seller_wallet,
-  token: session.token_address,
-  amount: session.amount_total,
-  feeAmount: '0',
-  reserveAmount: '0',
-  duration: '0',
-  deadline: String(paymentAuthDeadline),
-  nonce: String(nonce),
-});
-const paymentAuthSig = await wallet.signTypedData(paymentAuthTd);
-const paymentAuthParsed = parseSignature(paymentAuthSig);  // viem helper
-
-// 3. USDC EIP-3009 sig (변경 없음 — 기존 흐름 그대로)
-const usdcSig = await wallet.signTypedData({ /* TransferWithAuthorization ... */ });
-const usdcParsed = parseSignature(usdcSig);
-
-// 4. payWithAuthorization 호출 — payment_auth 필드 추가
-await bp.checkout.payWithAuthorization(sessionId, {
-  session_token: 'xyz...',
-  chain: 'base',
-  authorization: {
-    from: buyer.address,
-    validAfter: '0',
-    validBefore: String(Math.floor(Date.now()/1000) + 3600),
-    authNonce: '0x...',
-    v: Number(usdcParsed.v), r: usdcParsed.r, s: usdcParsed.s,
-  },
-  // ← 신규 필수
-  payment_auth: {
-    deadline: String(paymentAuthDeadline),
-    duration: '0',
-    v: Number(paymentAuthParsed.v),
-    r: paymentAuthParsed.r,
-    s: paymentAuthParsed.s,
-  },
-});
-```
-
-### 백엔드 응답에서 `payment_auth_nonce` 노출
-
-서버는 `GET /v1/checkout/sessions/:id/public` 응답에 `payment_auth_nonce` 필드를 포함한다
-(Q5 적용 후). buyer UI 가 컨트랙트를 직접 호출하지 않고도 nonce 를 얻을 수 있다. 단,
-`merchant_wallet` (seller_wallet) 도 sig 에 들어가므로 public response 에서 확인할 수 있어야 한다.
-
-## Non-breaking changes
-
-다음 SDK 흐름은 변경 없음:
-
-- `createSession()`, `getSession()`, `listSessions()`, `previewFee()`
-- `refundSession()`, `recordRefund()`, `listRefunds()`
-- `submitExternalPayment()` (Mode A — buyer 가 본인 지갑으로 직접 deposit)
-- Webhook helpers (`verifyWebhookSignature`, `parseWebhookEvent`)
-- Amount helpers (`toAtomicUSDC`, `fromAtomicUSDC`)
-
-## Why `payment_auth` is required (no opt-out)
-
-Q4 PR 적용 후 `CheckoutEscrow.depositWithAuthorization` 가 PaymentAuthorization sig 를 강제한다
-(컨트랙트 require). SDK 가 sig 없이 호출 시 백엔드가 `PAYMENT_AUTH_REQUIRED` (400) 로 거부.
-
-## Compatibility matrix
-
-| SDK version | Backend (CheckoutEscrow contract) | Result |
-|---|---|---|
-| v0.1.x | post-Q5 (PaymentAuthorization 필수) | ❌ `PAYMENT_AUTH_REQUIRED` 400 |
-| v0.2.0 | post-Q5 | ✅ OK |
-| v0.2.0 | pre-Q5 (legacy 미배포 contract) | ❌ contract revert (signature 추가 인자 없음) |
-
-→ SDK v0.2.0 와 컨트랙트 Q4+Q5 적용은 **동시 배포** 가 원칙. testnet 부터 함께 갈아끼움.
-
-## New helpers
-
-- `buildPaymentAuthTypedData(args)` — `signTypedData` 호환 객체 생성
-- `buildConfirmReceiptTypedData(args)` — Q4 H-01 `confirmReceiptWithSignature` 용 (off-chain receipt confirmation 직접 구현 시 사용. 기본 흐름에서는 BitPal hosted page 가 처리)
-- `sessionIdToPaymentId(sessionId)` — 32-byte hex 변환 (= 백엔드 `toBytes32()`)
-
-## See also
-
-- `docs/_dan/b2b-spec/2026-05-14-11-smart-contract-security-audit.md` §3 C-01
-- `docs/_dan/b2b-spec/2026-05-18-14-post-audit-remaining-hardening-plan.md` §4 (PR-C 실행 가이드)
-- README.md §"Gasless lane (Hosted / Gasless)"