@bitpal/checkout 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -9,9 +9,11 @@ interface BitPalConfig {
      *
      * BitPal 콘솔 → Developers → API Keys 에서 발급.
      *
-     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. 그러나 buyer-facing 공개 메서드
-     * (getPublicSession/getStatus/issueDepositAddress)는 인증 불요(session_token 기반)이므로 브라우저에서
-     * apiKey 없이 쓸 수 있다 — 절대 secret 키를 브라우저에 노출하지 말 것.
+     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. buyer-facing 공개 메서드
+     * (getPublicSession/getStatus/issueDepositAddress)는 apiKey 가 필요 없다(issueDepositAddress 는 session_token 필요).
+     * 단 **브라우저(CORS)** 에서 임의 머천트 도메인이 직접 부를 수 있는 것은 `getPublicSession` 뿐이다 —
+     * `issueDepositAddress`/`getStatus` 는 머천트 백엔드를 경유해 호출한다(자체 결제 UI = 헤드리스 checkout).
+     * 절대 secret 키를 브라우저에 노출하지 말 것.
      */
     apiKey?: string;
     /**
@@ -25,28 +27,30 @@ interface BitPalConfig {
     /** 요청 타임아웃 (ms, 기본값: 30000) */
     timeout?: number;
 }
-/** 응답/정규화된 line item — amount 는 항상 atomic μUSD 정수. */
+/** 응답/정규화된 line item — amount 는 항상 canonical 6dp atomic 정수(실제 결제 토큰 decimals 아님). */
 interface LineItem {
     name: string;
-    /** Atomic μUSD 정수 문자열($1="1000000", $29="29000000"). */
+    /** canonical 6dp atomic 정수 문자열("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")인 경우(고급/기존 코드).
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
+ *     ※ `currency`(예: 'USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정한다 — `amount`는 그 통화의 canonical
+ *     6dp 표기일 뿐 항상 USD 를 뜻하지 않는다(예: currency='JPYC' + amount="29" → 29 JPYC/29엔, 환율
+ *     변환 없음). 실제 결제 토큰 decimals(USDC 6dp / JPYC 18dp 등)로의 재스케일은 발급 시 서버가 처리.
+ *   - `amount_atomic`: 이미 raw canonical 6dp 정수 문자열($1="1000000")인 경우(고급/기존 코드).
  * 둘 다 지정하거나 둘 다 생략하면 SDK 가 에러를 throw 한다.
  */
 interface LineItemInput {
     name: string;
     currency: string;
     quantity?: number;
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
 }
 interface PriceLineItem {
@@ -57,7 +61,7 @@ interface PriceLineItem {
 type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
     line_items: CheckoutLineItemInput[];
-    /** 고객 지갑 주소 (선택) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 입금자 주소는 결제 시 온체인에서 기록된다. */
     payer_wallet?: string;
     /** 결제 체인 (예: eip155:8453). 단일 고정 — allowed_pay_chains와 상호 배타. */
     pay_chain?: string;
@@ -78,11 +82,19 @@ interface CreateSessionParams {
         chain: string;
         token: string;
     }>;
-    /** 결제 자산 (예: USDC) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 결제 자산은 `allowed_assets` 로 지정한다. */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
     tolerance_percent?: string;
-    /** 만료 시간 (초, 기본값: 1800) */
+    /**
+     * 결제 대기 시간(분). 1~60, 기본 15. 이 시간이 지나면 세션이 만료된다
+     * (만료 후 도착한 정확 금액은 7일 안이면 늦은 결제로 인정 — `late: true`).
+     */
+    expires_in_minutes?: number;
+    /**
+     * @deprecated `expires_in_minutes` 를 쓴다. 60~3600 초만 허용되고 분 단위로 올림해 보낸다.
+     * (0.11 까지는 서버가 이 필드를 몰라 무시했고, 항상 기본 15분이 적용됐다.)
+     */
     expires_in_seconds?: number;
     /** 메타데이터 (모든 값은 string 이어야 함) */
     metadata?: Record<string, string>;
@@ -141,9 +153,18 @@ interface PublicSession {
     status: string;
     mode: string | null;
     currency: string;
-    /** Atomic 정수 문자열(토큰 decimals 기준). */
+    /**
+     * 주문 총액 — **canonical μUSD(6dp) 정수 문자열**(가격 통화 기준, $1 = "1000000"). 결제 토큰 decimals 와 무관하다
+     * (18dp 토큰으로 결제해도 6dp). 온체인으로 보낼 토큰 단위 금액은 `pay_amount`(또는 발급 응답 `expectedAmount`).
+     */
     amount_total: string;
+    /** 지금까지 입금주소에 들어온 금액 — **결제 토큰 atomic**(`token_decimals` 기준). 미입금이면 null. */
     amount_received?: string | null;
+    /**
+     * 선택된 결제 토큰 단위의 총액(atomic, `token_decimals` 기준) — 구매자가 송금할 정확 금액. 자산 미선택이면 null.
+     * = canonicalToTokenAtomic(amount_total, token_decimals). 부족액 = pay_amount − amount_received.
+     */
+    pay_amount?: string | null;
     pay_chain: string | null;
     pay_asset: string | null;
     /** 발급된 주문별 forwarder 입금주소(미발급이면 null). */
@@ -152,7 +173,7 @@ interface PublicSession {
     payment_options: PaymentOption[];
     chain_id: number | null;
     token_address: string | null;
-    /** 선택된 pay 토큰 decimals(발급 후). amount_total/amount_received atomic 해석에 사용 — 6dp 가정 금지. */
+    /** 선택된 pay 토큰 decimals(발급 후). amount_received / pay_amount 해석에 사용 — 6dp 가정 금지(amount_total 은 항상 6dp). */
     token_decimals?: number | null;
     tx_hash: string | null;
     release_tx_hash?: string | null;
@@ -284,16 +305,23 @@ interface UpdateProductParams {
 }
 /**
  * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
- *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
- *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw canonical 6dp 정수($1="1000000") — 고급/기존.
  * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ *
+ * `amount`/`amount_atomic`은 실제 결제 토큰의 decimals 가 아니라 **항상 canonical 6dp**다 — 서버가
+ * 결제 시점에 실제 토큰 decimals(예: JPYC=18dp)로 재스케일한다(1:1 가정, 환율 변환 없음). 즉
+ * `token_symbol: 'JPYC'`로 "29"를 등록하면 29 JPYC(≈29엔)로 결제되지, 29 USD 상당의 JPYC로
+ * 환산되지 않는다.
+ *
+ * `currency`는 입력받지 않는다 — 서버가 `token_symbol`에서 파생한다(불일치 방지).
  */
 interface CreatePriceParams {
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
-    currency?: string;
+    /** 'USDC' | 'USDT' | 'JPYC' — 미지정 시 'USDC'. 이 Price 의 유일한 결제 자산(currency 는 여기서 파생). */
     token_symbol?: string;
     billing_type?: 'one_time';
     nickname?: string;
@@ -492,14 +520,16 @@ declare class BitPalCheckoutClient {
     /**
      * 체크아웃 세션 생성.
      *
-     * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
-     * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
+     * `line_items[].amount` 는 사람 표기 canonical 6dp 문자열("29", "0.5") — decimal 계산 불필요.
+     * `currency`('USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정하고, amount 는 항상 그 통화 기준 값이다
+     * (USD 로 고정된 게 아님 — currency='JPYC' + amount='1500' → 1500엔/1500 JPYC, 환율 변환 없음).
+     * 이미 raw canonical 6dp 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
      *
      * @example
      * import { BitPal } from '@bitpal/checkout';
      * const bp = new BitPal('bp_test_...');
      * const { data } = await bp.checkout.createSession({
-     *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+     *   // amount: 사람 표기 canonical 6dp("29", "0.5"). 체인/토큰 decimal 은 발급 시 서버가 재스케일.
      *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      * });
      * console.log(data.url); // → buyer를 redirect할 결제 페이지
@@ -571,10 +601,32 @@ declare class BitPalCheckoutClient {
         amountAtomic: string;
     }): Promise<ApiResponse<FeePreview>>;
 }
+/** Structured fields parsed from an API error body. All optional — older endpoints omit some. */
+interface BitPalErrorDetails {
+    /** Machine-readable error code, e.g. `"FEATURE_NOT_ENABLED"`. */
+    code?: string;
+    /** Human-readable message from the API, when it sent one separately from the code. */
+    apiMessage?: string;
+    /** Whether retrying the same request may succeed. */
+    retryable?: boolean;
+    /** Server trace id — include it when contacting support. */
+    traceId?: string;
+}
 declare class BitPalError extends Error {
     readonly statusCode: number;
-    constructor(message: string, statusCode: number);
+    readonly code?: string;
+    readonly apiMessage?: string;
+    readonly retryable?: boolean;
+    readonly traceId?: string;
+    constructor(message: string, statusCode: number, details?: BitPalErrorDetails);
 }
+/**
+ * API 에러 body → BitPalError 상세. 두 가지 shape 를 모두 읽는다:
+ *   - 표준: `{ error: <message>, code, retryable, trace_id }`
+ *   - 일부 라우트: `{ error: <CODE>, message }`
+ * `message`(Error.message)는 0.11 과 같게 `body.error` 를 유지한다(하위 호환) — 추가 정보는 필드로만.
+ */
+declare function parseApiErrorBody(body: unknown): BitPalErrorDetails;
 
 /**
  * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
@@ -750,6 +802,7 @@ interface X402Requirements {
     x402Version: 1;
     accepts: X402Accept[];
 }
+/** EIP-3009 `TransferWithAuthorization` 의 서명 대상 필드. x402 표준 `payload.authorization`. */
 interface Eip3009Authorization {
     from: string;
     to: string;
@@ -757,21 +810,23 @@ interface Eip3009Authorization {
     validAfter: string;
     validBefore: string;
     nonce: string;
-    signature: {
-        v: number;
-        r: string;
-        s: string;
-    };
 }
+/**
+ * x402 표준 payload 그대로다 — 단일 authorization + 65바이트 packed 서명.
+ *
+ * 0.10.0 까지는 `{ merchant, fee }` 2건이었다. 포워더 없이 수수료를 나누려면 payer 가 두 번
+ * 서명해야 했고, 그 탓에 순정 x402 클라이언트가 BitPal 머천트에게 결제할 수 없었다.
+ * 이제 분배는 `payTo`(포워더) 주소가 커밋하므로 서명이 1건이면 된다.
+ */
 interface X402PaymentPayload {
     x402Version: 1;
     scheme: 'exact';
     /** x402 wire 이름 — 'base' / 'base-sepolia'. */
     network: string;
     payload: {
-        merchant: Eip3009Authorization;
-        /** 서버가 계산한 feeAmount > 0 이면 필수. */
-        fee?: Eip3009Authorization;
+        /** 65바이트 packed hex(`0x` + r + s + v). */
+        signature: string;
+        authorization: Eip3009Authorization;
     };
 }
 /** `ok` = 이번 호출이 최초 점유 / `inflight` = 다른 요청이 처리 중 / `used` = 이미 리소스를 내줌. */
@@ -1080,11 +1135,18 @@ declare function createX402Payment(options: CreateX402PaymentOptions): Promise<X
  * 65바이트(r‖s‖v)와 64바이트 EIP-2098 compact(r‖yParityAndS) 둘 다 받는다 — viem 의
  * `signTypedData` 는 65바이트를 주지만 일부 지갑·라이브러리는 compact 를 돌려준다.
  */
-declare function splitSignature(signature: string): {
-    v: number;
-    r: string;
-    s: string;
-};
+/**
+ * 지갑이 돌려준 서명을 **65바이트 packed hex** 로 수렴시킨다. x402 표준이 그 형태다.
+ *
+ * 두 가지를 정규화한다:
+ *   - EIP-2098 compact(64바이트) — 일부 지갑이 이걸 낸다. s 의 최상위 비트가 yParity 라 떼어내고
+ *     v 를 복원해 65바이트로 편다.
+ *   - v 가 0/1 인 경우 — 온체인 ecrecover 규약인 27/28 로 맞춘다.
+ *
+ * 서버가 130 hex 만 받으므로 여기서 안 맞추면 그쪽에서 거부된다. 그 외 값은 recover 가 어긋나
+ * 어차피 실패하므로 여기서 끊는다.
+ */
+declare function normalizeSignature(signature: string): string;
 
 /**
  * @bitpal/checkout — BitPal Checkout SDK
@@ -1114,4 +1176,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-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 CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, 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, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, parseWebhookEvent, splitSignature, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, type BitPalErrorDetails, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, 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, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, normalizeSignature, parseApiErrorBody, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };

package/dist/index.d.ts

@@ -9,9 +9,11 @@ interface BitPalConfig {
      *
      * BitPal 콘솔 → Developers → API Keys 에서 발급.
      *
-     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. 그러나 buyer-facing 공개 메서드
-     * (getPublicSession/getStatus/issueDepositAddress)는 인증 불요(session_token 기반)이므로 브라우저에서
-     * apiKey 없이 쓸 수 있다 — 절대 secret 키를 브라우저에 노출하지 말 것.
+     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. buyer-facing 공개 메서드
+     * (getPublicSession/getStatus/issueDepositAddress)는 apiKey 가 필요 없다(issueDepositAddress 는 session_token 필요).
+     * 단 **브라우저(CORS)** 에서 임의 머천트 도메인이 직접 부를 수 있는 것은 `getPublicSession` 뿐이다 —
+     * `issueDepositAddress`/`getStatus` 는 머천트 백엔드를 경유해 호출한다(자체 결제 UI = 헤드리스 checkout).
+     * 절대 secret 키를 브라우저에 노출하지 말 것.
      */
     apiKey?: string;
     /**
@@ -25,28 +27,30 @@ interface BitPalConfig {
     /** 요청 타임아웃 (ms, 기본값: 30000) */
     timeout?: number;
 }
-/** 응답/정규화된 line item — amount 는 항상 atomic μUSD 정수. */
+/** 응답/정규화된 line item — amount 는 항상 canonical 6dp atomic 정수(실제 결제 토큰 decimals 아님). */
 interface LineItem {
     name: string;
-    /** Atomic μUSD 정수 문자열($1="1000000", $29="29000000"). */
+    /** canonical 6dp atomic 정수 문자열("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")인 경우(고급/기존 코드).
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
+ *     ※ `currency`(예: 'USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정한다 — `amount`는 그 통화의 canonical
+ *     6dp 표기일 뿐 항상 USD 를 뜻하지 않는다(예: currency='JPYC' + amount="29" → 29 JPYC/29엔, 환율
+ *     변환 없음). 실제 결제 토큰 decimals(USDC 6dp / JPYC 18dp 등)로의 재스케일은 발급 시 서버가 처리.
+ *   - `amount_atomic`: 이미 raw canonical 6dp 정수 문자열($1="1000000")인 경우(고급/기존 코드).
  * 둘 다 지정하거나 둘 다 생략하면 SDK 가 에러를 throw 한다.
  */
 interface LineItemInput {
     name: string;
     currency: string;
     quantity?: number;
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
 }
 interface PriceLineItem {
@@ -57,7 +61,7 @@ interface PriceLineItem {
 type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
     line_items: CheckoutLineItemInput[];
-    /** 고객 지갑 주소 (선택) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 입금자 주소는 결제 시 온체인에서 기록된다. */
     payer_wallet?: string;
     /** 결제 체인 (예: eip155:8453). 단일 고정 — allowed_pay_chains와 상호 배타. */
     pay_chain?: string;
@@ -78,11 +82,19 @@ interface CreateSessionParams {
         chain: string;
         token: string;
     }>;
-    /** 결제 자산 (예: USDC) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 결제 자산은 `allowed_assets` 로 지정한다. */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
     tolerance_percent?: string;
-    /** 만료 시간 (초, 기본값: 1800) */
+    /**
+     * 결제 대기 시간(분). 1~60, 기본 15. 이 시간이 지나면 세션이 만료된다
+     * (만료 후 도착한 정확 금액은 7일 안이면 늦은 결제로 인정 — `late: true`).
+     */
+    expires_in_minutes?: number;
+    /**
+     * @deprecated `expires_in_minutes` 를 쓴다. 60~3600 초만 허용되고 분 단위로 올림해 보낸다.
+     * (0.11 까지는 서버가 이 필드를 몰라 무시했고, 항상 기본 15분이 적용됐다.)
+     */
     expires_in_seconds?: number;
     /** 메타데이터 (모든 값은 string 이어야 함) */
     metadata?: Record<string, string>;
@@ -141,9 +153,18 @@ interface PublicSession {
     status: string;
     mode: string | null;
     currency: string;
-    /** Atomic 정수 문자열(토큰 decimals 기준). */
+    /**
+     * 주문 총액 — **canonical μUSD(6dp) 정수 문자열**(가격 통화 기준, $1 = "1000000"). 결제 토큰 decimals 와 무관하다
+     * (18dp 토큰으로 결제해도 6dp). 온체인으로 보낼 토큰 단위 금액은 `pay_amount`(또는 발급 응답 `expectedAmount`).
+     */
     amount_total: string;
+    /** 지금까지 입금주소에 들어온 금액 — **결제 토큰 atomic**(`token_decimals` 기준). 미입금이면 null. */
     amount_received?: string | null;
+    /**
+     * 선택된 결제 토큰 단위의 총액(atomic, `token_decimals` 기준) — 구매자가 송금할 정확 금액. 자산 미선택이면 null.
+     * = canonicalToTokenAtomic(amount_total, token_decimals). 부족액 = pay_amount − amount_received.
+     */
+    pay_amount?: string | null;
     pay_chain: string | null;
     pay_asset: string | null;
     /** 발급된 주문별 forwarder 입금주소(미발급이면 null). */
@@ -152,7 +173,7 @@ interface PublicSession {
     payment_options: PaymentOption[];
     chain_id: number | null;
     token_address: string | null;
-    /** 선택된 pay 토큰 decimals(발급 후). amount_total/amount_received atomic 해석에 사용 — 6dp 가정 금지. */
+    /** 선택된 pay 토큰 decimals(발급 후). amount_received / pay_amount 해석에 사용 — 6dp 가정 금지(amount_total 은 항상 6dp). */
     token_decimals?: number | null;
     tx_hash: string | null;
     release_tx_hash?: string | null;
@@ -284,16 +305,23 @@ interface UpdateProductParams {
 }
 /**
  * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
- *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
- *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw canonical 6dp 정수($1="1000000") — 고급/기존.
  * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ *
+ * `amount`/`amount_atomic`은 실제 결제 토큰의 decimals 가 아니라 **항상 canonical 6dp**다 — 서버가
+ * 결제 시점에 실제 토큰 decimals(예: JPYC=18dp)로 재스케일한다(1:1 가정, 환율 변환 없음). 즉
+ * `token_symbol: 'JPYC'`로 "29"를 등록하면 29 JPYC(≈29엔)로 결제되지, 29 USD 상당의 JPYC로
+ * 환산되지 않는다.
+ *
+ * `currency`는 입력받지 않는다 — 서버가 `token_symbol`에서 파생한다(불일치 방지).
  */
 interface CreatePriceParams {
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
-    currency?: string;
+    /** 'USDC' | 'USDT' | 'JPYC' — 미지정 시 'USDC'. 이 Price 의 유일한 결제 자산(currency 는 여기서 파생). */
     token_symbol?: string;
     billing_type?: 'one_time';
     nickname?: string;
@@ -492,14 +520,16 @@ declare class BitPalCheckoutClient {
     /**
      * 체크아웃 세션 생성.
      *
-     * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
-     * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
+     * `line_items[].amount` 는 사람 표기 canonical 6dp 문자열("29", "0.5") — decimal 계산 불필요.
+     * `currency`('USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정하고, amount 는 항상 그 통화 기준 값이다
+     * (USD 로 고정된 게 아님 — currency='JPYC' + amount='1500' → 1500엔/1500 JPYC, 환율 변환 없음).
+     * 이미 raw canonical 6dp 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
      *
      * @example
      * import { BitPal } from '@bitpal/checkout';
      * const bp = new BitPal('bp_test_...');
      * const { data } = await bp.checkout.createSession({
-     *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+     *   // amount: 사람 표기 canonical 6dp("29", "0.5"). 체인/토큰 decimal 은 발급 시 서버가 재스케일.
      *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      * });
      * console.log(data.url); // → buyer를 redirect할 결제 페이지
@@ -571,10 +601,32 @@ declare class BitPalCheckoutClient {
         amountAtomic: string;
     }): Promise<ApiResponse<FeePreview>>;
 }
+/** Structured fields parsed from an API error body. All optional — older endpoints omit some. */
+interface BitPalErrorDetails {
+    /** Machine-readable error code, e.g. `"FEATURE_NOT_ENABLED"`. */
+    code?: string;
+    /** Human-readable message from the API, when it sent one separately from the code. */
+    apiMessage?: string;
+    /** Whether retrying the same request may succeed. */
+    retryable?: boolean;
+    /** Server trace id — include it when contacting support. */
+    traceId?: string;
+}
 declare class BitPalError extends Error {
     readonly statusCode: number;
-    constructor(message: string, statusCode: number);
+    readonly code?: string;
+    readonly apiMessage?: string;
+    readonly retryable?: boolean;
+    readonly traceId?: string;
+    constructor(message: string, statusCode: number, details?: BitPalErrorDetails);
 }
+/**
+ * API 에러 body → BitPalError 상세. 두 가지 shape 를 모두 읽는다:
+ *   - 표준: `{ error: <message>, code, retryable, trace_id }`
+ *   - 일부 라우트: `{ error: <CODE>, message }`
+ * `message`(Error.message)는 0.11 과 같게 `body.error` 를 유지한다(하위 호환) — 추가 정보는 필드로만.
+ */
+declare function parseApiErrorBody(body: unknown): BitPalErrorDetails;
 
 /**
  * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
@@ -750,6 +802,7 @@ interface X402Requirements {
     x402Version: 1;
     accepts: X402Accept[];
 }
+/** EIP-3009 `TransferWithAuthorization` 의 서명 대상 필드. x402 표준 `payload.authorization`. */
 interface Eip3009Authorization {
     from: string;
     to: string;
@@ -757,21 +810,23 @@ interface Eip3009Authorization {
     validAfter: string;
     validBefore: string;
     nonce: string;
-    signature: {
-        v: number;
-        r: string;
-        s: string;
-    };
 }
+/**
+ * x402 표준 payload 그대로다 — 단일 authorization + 65바이트 packed 서명.
+ *
+ * 0.10.0 까지는 `{ merchant, fee }` 2건이었다. 포워더 없이 수수료를 나누려면 payer 가 두 번
+ * 서명해야 했고, 그 탓에 순정 x402 클라이언트가 BitPal 머천트에게 결제할 수 없었다.
+ * 이제 분배는 `payTo`(포워더) 주소가 커밋하므로 서명이 1건이면 된다.
+ */
 interface X402PaymentPayload {
     x402Version: 1;
     scheme: 'exact';
     /** x402 wire 이름 — 'base' / 'base-sepolia'. */
     network: string;
     payload: {
-        merchant: Eip3009Authorization;
-        /** 서버가 계산한 feeAmount > 0 이면 필수. */
-        fee?: Eip3009Authorization;
+        /** 65바이트 packed hex(`0x` + r + s + v). */
+        signature: string;
+        authorization: Eip3009Authorization;
     };
 }
 /** `ok` = 이번 호출이 최초 점유 / `inflight` = 다른 요청이 처리 중 / `used` = 이미 리소스를 내줌. */
@@ -1080,11 +1135,18 @@ declare function createX402Payment(options: CreateX402PaymentOptions): Promise<X
  * 65바이트(r‖s‖v)와 64바이트 EIP-2098 compact(r‖yParityAndS) 둘 다 받는다 — viem 의
  * `signTypedData` 는 65바이트를 주지만 일부 지갑·라이브러리는 compact 를 돌려준다.
  */
-declare function splitSignature(signature: string): {
-    v: number;
-    r: string;
-    s: string;
-};
+/**
+ * 지갑이 돌려준 서명을 **65바이트 packed hex** 로 수렴시킨다. x402 표준이 그 형태다.
+ *
+ * 두 가지를 정규화한다:
+ *   - EIP-2098 compact(64바이트) — 일부 지갑이 이걸 낸다. s 의 최상위 비트가 yParity 라 떼어내고
+ *     v 를 복원해 65바이트로 편다.
+ *   - v 가 0/1 인 경우 — 온체인 ecrecover 규약인 27/28 로 맞춘다.
+ *
+ * 서버가 130 hex 만 받으므로 여기서 안 맞추면 그쪽에서 거부된다. 그 외 값은 recover 가 어긋나
+ * 어차피 실패하므로 여기서 끊는다.
+ */
+declare function normalizeSignature(signature: string): string;
 
 /**
  * @bitpal/checkout — BitPal Checkout SDK
@@ -1114,4 +1176,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-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 CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, 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, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, parseWebhookEvent, splitSignature, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, type BitPalErrorDetails, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, 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, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, normalizeSignature, parseApiErrorBody, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };