@bitpal/checkout 0.5.0 → 0.7.0

package/README.md

@@ -11,25 +11,27 @@ pnpm add @bitpal/checkout
 # npm i @bitpal/checkout / yarn add @bitpal/checkout
 ```
 
-## ⚠️ Amount format (read this first)
+## Amounts — just pass a human number
 
-USDC / USDT have **6 decimals**. All amounts are **atomic μUSDC integer strings** — never floats.
+Use **`amount`** in line items — a plain USD string like `"20"`, `"0.5"`, `"29.00"`. No decimals to compute.
 
-```
-$1.00  → "1000000"
-$29.00 → "29000000"
-$0.50  → "500000"
+```ts
+line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }]
 ```
 
-Passing a decimal string like `"29.00"` returns **400**. Use the helpers:
+**The amount is a USD price — it does NOT depend on the chain or token decimals.** Whether the buyer pays with USDC (6dp) on Base or USDT (18dp) on BNB, you pass the same `amount`. BitPal rescales to the buyer's chosen token at deposit time. So you never compute per-token decimals. (Prices via `prices.create` take the same `amount`.)
 
-```ts
-import { toAtomicUSDC, fromAtomicUSDC } from '@bitpal/checkout';
+<details><summary>Advanced: raw atomic amounts</summary>
 
-toAtomicUSDC('29.00');      // → "29000000"
-fromAtomicUSDC('29000000'); // → "29.00"
+If you already hold **atomic μUSD integer strings** ($1 = `"1000000"`), pass `amount_atomic` instead (mutually exclusive with `amount`):
+
+```
+$1.00 → "1000000"   $29.00 → "29000000"   $0.50 → "500000"
 ```
 
+Helpers for atomic conversion (e.g. reading `amount_total` back): `toAtomic(v, decimals)` / `fromAtomic(v, decimals)` — read `decimals` from `payment_options[]`/`token_decimals` (6 for USDC/USDT, 18 for BNB USDT). `toAtomicUSDC`/`fromAtomicUSDC` are 6dp shortcuts.
+</details>
+
 ## Environments
 
 API keys are environment-scoped:
@@ -45,8 +47,8 @@ there is no separate flag.
 ### Setup
 
 ```ts
-// helpers (toAtomicUSDC / fromAtomicUSDC) are used in the snippets below
-import { BitPal, toAtomicUSDC, fromAtomicUSDC } from '@bitpal/checkout';
+import { BitPal } from '@bitpal/checkout';
+// (optional atomic helpers if you need them: import { toAtomic, fromAtomic } from '@bitpal/checkout')
 
 const bitpal = new BitPal(process.env.BITPAL_API_KEY!); // bp_test_... / bp_live_...
 ```
@@ -61,10 +63,16 @@ shows the per-order deposit address + QR, and confirms the payment on-chain.
 ```ts
 const { data: session } = await bitpal.checkout.createSession({
   line_items: [
-    { name: 'Pro Plan', amount: toAtomicUSDC('29.00'), currency: 'USDC' },
+    { name: 'Pro Plan', amount: '29', currency: 'USDC' },  // `currency` = price denomination (USD via USDC)
+  ],
+  // Payment options the buyer may choose — (chain, token) pairs. Mix tokens freely.
+  //   `chain` accepts a short-name ('base' | 'arbitrum' | 'bnb' | 'tron' | 'solana') or a CAIP-2 id;
+  //   it resolves to the right testnet/mainnet chain for your mode (test vs live key) automatically.
+  allowed_assets: [
+    { chain: 'base',   token: 'USDC' },
+    { chain: 'tron',   token: 'USDT' },
+    { chain: 'solana', token: 'USDC' },
   ],
-  pay_chain: 'eip155:84532',     // Base Sepolia (test mode). Live mode: 'eip155:8453' (Base mainnet).
-                                 // Or use allowed_pay_chains for a buyer-picked chain.
   expires_in_seconds: 1800,
   success_url: 'https://yourstore.com/thanks',
 });
@@ -73,7 +81,13 @@ const { data: session } = await bitpal.checkout.createSession({
 redirect(session.checkout_url!);
 ```
 
-`pay_chain` (single fixed chain) and `allowed_pay_chains` (buyer picks) are mutually exclusive.
+**Setting the payment options** (precedence, highest first):
+
+- **`allowed_assets`** — `(chain, token)` cells. The standard, most explicit way; the buyer picks any listed pair (lets you mix tokens, e.g. USDC on Base + USDT on Tron).
+- `allowed_pay_chains: string[]` — shorthand for "the line-item `currency` across these chains" (one token, many chains).
+- `pay_chain: string` — a single fixed chain, no buyer choice.
+
+`pay_chain` and `allowed_pay_chains` are mutually exclusive; `allowed_assets` takes precedence over both. Omit all three and it defaults to **one chain × the line-item currency**. `currency` on the line item is always the **price denomination** (what the amount is quoted in) — independent of which token the buyer pays with.
 
 ### Self-hosted flow: issue a deposit address yourself
 
@@ -85,9 +99,9 @@ you.
 ```ts
 const { data } = await bitpal.checkout.issueDepositAddress(session.id, {
   session_token: session.session_token!, // from createSession
-  refundAddress: '0xBuyerWallet...',      // committed to the address, immutable after issuance
+  refundAddress: '0xBuyerWallet...',      // VM-matched (EVM 0x… / Tron T… / Solana base58); committed, immutable after issuance
   chain: 'eip155:84532',                  // match the session's chain (test: Base Sepolia / live: eip155:8453).
-                                          // only needed for multi-option (allowed_pay_chains) sessions
+                                          // only needed for multi-option (allowed_assets / allowed_pay_chains) sessions
   token: 'USDC',
 });
 
@@ -195,10 +209,9 @@ new BitPal({ apiKey, baseUrl: 'https://…' }); // config object — override ba
 
 ## Runnable examples
 
-The [source repo](https://github.com/superlabs-x/bitpal-checkout-sdk)'s `examples/` directory
-has runnable references (not shipped in the npm package): `create-session.mjs`,
-`webhook-receiver.mjs`, and a `full-integration/` Express store wiring session creation +
-webhook verification + idempotency.
+The source repo's `examples/` directory has runnable references (not shipped in the npm
+package): `create-session.mjs`, `webhook-receiver.mjs`, and a `full-integration/` Express
+store wiring session creation + webhook verification + idempotency.
 
 ## Build
 
@@ -213,7 +226,7 @@ pnpm build   # tsup → dist/ (ESM + .d.ts)
   `verifyWebhookSignature(rawBody, sigHeader, secret, { timestamp: tsHeader })`. A 3-argument call now
   returns `false`. The signed content changed from `body` to `` `${timestamp}.${body}` ``.
 - Deduplicate on the signed `event.id`, not the `X-Webhook-Id` header.
-- Removed legacy pre-release methods (`payWithAuthorization`, `submitExternalPayment`) and escrow refund helpers —
+- Removed 안1 methods (`payWithAuthorization`, `submitExternalPayment`) and escrow refund helpers —
   checkout is non-custodial deposit-address (see Usage above).
 
 ## License

package/dist/index.cjs

@@ -34,11 +34,14 @@ __export(index_exports, {
   BitPalCheckoutClient: () => BitPalCheckoutClient,
   BitPalError: () => BitPalError,
   CHECKOUT_WEBHOOK_EVENTS: () => CHECKOUT_WEBHOOK_EVENTS,
+  PaymentLinksResource: () => PaymentLinksResource,
   PricesResource: () => PricesResource,
   ProductsResource: () => ProductsResource,
   WEBHOOK_HEADERS: () => WEBHOOK_HEADERS,
+  fromAtomic: () => fromAtomic,
   fromAtomicUSDC: () => fromAtomicUSDC,
   parseWebhookEvent: () => parseWebhookEvent,
+  toAtomic: () => toAtomic,
   toAtomicUSDC: () => toAtomicUSDC,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
@@ -101,8 +104,39 @@ var PricesResource = class {
     return this.request("PATCH", `/v1/checkout/prices/${encodeURIComponent(priceId)}`, params);
   }
 };
+var PaymentLinksResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  /** POST /v1/checkout/payment-links */
+  create(params) {
+    return this.request("POST", "/v1/checkout/payment-links", params);
+  }
+  /** GET /v1/checkout/payment-links */
+  list(params) {
+    return this.request("GET", `/v1/checkout/payment-links${toQuery(params)}`);
+  }
+  /** GET /v1/checkout/payment-links/:id */
+  retrieve(linkId) {
+    return this.request("GET", `/v1/checkout/payment-links/${encodeURIComponent(linkId)}`);
+  }
+  /** PATCH /v1/checkout/payment-links/:id */
+  update(linkId, params) {
+    return this.request("PATCH", `/v1/checkout/payment-links/${encodeURIComponent(linkId)}`, params);
+  }
+};
 
 // src/client.ts
+function validateLineItem(li) {
+  if ("price_id" in li) return li;
+  const hasHuman = li.amount != null;
+  const hasAtomic = li.amount_atomic != null;
+  if (hasHuman === hasAtomic) {
+    throw new Error('[BitPal] line item requires exactly one of `amount` (USD number, e.g. "29") or `amount_atomic` (raw \u03BCUSD integer, e.g. "29000000").');
+  }
+  return li;
+}
 var DEFAULT_BASE_URL = "https://api.bitpal.io";
 var DEFAULT_TIMEOUT = 3e4;
 var BitPalCheckoutClient = class {
@@ -114,6 +148,8 @@ var BitPalCheckoutClient = class {
   products;
   /** PROD-LINK-3a-SDK: immutable Price 관리 — 가격 변경은 비활성화 + 새 price 생성 */
   prices;
+  /** PROD-LINK-4-SDK: Payment Link 관리 — 대시보드 없이 코드로 결제 링크 생성 (server-side 전용) */
+  paymentLinks;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -121,6 +157,7 @@ var BitPalCheckoutClient = class {
     const requester = (method, path, body) => this.request(method, path, body);
     this.products = new ProductsResource(requester);
     this.prices = new PricesResource(requester);
+    this.paymentLinks = new PaymentLinksResource(requester);
   }
   /* ─── 내부 HTTP ─── */
   async request(method, path, body, extraHeaders) {
@@ -153,20 +190,22 @@ var BitPalCheckoutClient = class {
   /**
    * 체크아웃 세션 생성.
    *
-   * 모든 `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: toAtomicUSDC('29.00'), currency: 'USDC' }],
+   *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
    *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
    * });
    * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
@@ -175,10 +214,15 @@ var BitPalCheckoutClient = class {
     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 body = {
+      ...params,
+      line_items: params.line_items.map(validateLineItem),
+      ...params.allowed_assets ? { allowed_assets: params.allowed_assets.map((a) => ({ caip2: a.chain, token: a.token })) } : {}
+    };
     const res = await this.request(
       "POST",
       "/v1/checkout/sessions",
-      params
+      body
     );
     if (res.data) {
       if (res.data.checkout_url) {
@@ -208,7 +252,7 @@ var BitPalCheckoutClient = class {
       `/v1/checkout/sessions${query ? `?${query}` : ""}`
     );
   }
-  /* ─── 비수탁 결제 (deposit-address) ─── */
+  /* ─── 안2 비수탁 결제 (deposit-address) ─── */
   /**
    * 공개 세션 조회 (`GET /v1/checkout/sessions/:id/public`) — 인증 불요.
    *
@@ -224,7 +268,7 @@ var BitPalCheckoutClient = class {
   /**
    * 주문별 비수탁 입금주소 발급 (`POST /v1/checkout/sessions/:id/deposit-address`).
    *
-   * 비수탁 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
+   * 안2 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
    * 그 주문 전용 CREATE2 forwarder 주소를 돌려준다. 구매자는 아무 지갑/거래소에서 **정확한 금액**을
    * 그 주소로 일반 송금하면 된다(서명·연결 불필요). watcher 가 감지 → keeper 가 정산.
    *
@@ -329,26 +373,40 @@ function parseWebhookEvent(body) {
 }
 
 // src/amount.ts
-var USDC_DECIMALS = 6n;
-var USDC_SCALE = 10n ** USDC_DECIMALS;
-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)`);
+function toAtomic(decimal, decimals) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    throw new Error(`toAtomic: invalid decimals '${decimals}'`);
+  }
+  const fracPattern = decimals > 0 ? `(\\.\\d{1,${decimals}})?` : "";
+  if (typeof decimal !== "string" || !new RegExp(`^\\d+${fracPattern}$`).test(decimal)) {
+    throw new Error(`toAtomic: invalid decimal '${decimal}' (max ${decimals} fractional digits, no negatives)`);
   }
+  const scale = 10n ** BigInt(decimals);
   const [whole = "0", frac = ""] = decimal.split(".");
-  const fracPadded = frac.padEnd(Number(USDC_DECIMALS), "0");
-  return (BigInt(whole) * USDC_SCALE + BigInt(fracPadded || "0")).toString();
+  const fracPadded = frac.padEnd(decimals, "0");
+  return (BigInt(whole) * scale + BigInt(fracPadded || "0")).toString();
 }
-function fromAtomicUSDC(atomic) {
+function fromAtomic(atomic, decimals) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    throw new Error(`fromAtomic: invalid decimals '${decimals}'`);
+  }
   if (typeof atomic !== "string" || !/^\d+$/.test(atomic)) {
-    throw new Error(`fromAtomicUSDC: invalid atomic '${atomic}' (must be non-negative integer string)`);
+    throw new Error(`fromAtomic: invalid atomic '${atomic}' (must be non-negative integer string)`);
   }
+  const scale = 10n ** BigInt(decimals);
   const big = BigInt(atomic);
-  const whole = big / USDC_SCALE;
-  const frac = big % USDC_SCALE;
-  const fracStr = frac.toString().padStart(Number(USDC_DECIMALS), "0").replace(/0+$/, "");
+  const whole = big / scale;
+  const frac = big % scale;
+  if (decimals === 0) return `${whole}`;
+  const fracStr = frac.toString().padStart(decimals, "0").replace(/0+$/, "");
   return fracStr.length > 0 ? `${whole}.${fracStr.padEnd(2, "0")}` : `${whole}.00`;
 }
+function toAtomicUSDC(decimal) {
+  return toAtomic(decimal, 6);
+}
+function fromAtomicUSDC(atomic) {
+  return fromAtomic(atomic, 6);
+}
 
 // src/index.ts
 var BitPal = class {
@@ -364,11 +422,14 @@ var BitPal = class {
   BitPalCheckoutClient,
   BitPalError,
   CHECKOUT_WEBHOOK_EVENTS,
+  PaymentLinksResource,
   PricesResource,
   ProductsResource,
   WEBHOOK_HEADERS,
+  fromAtomic,
   fromAtomicUSDC,
   parseWebhookEvent,
+  toAtomic,
   toAtomicUSDC,
   verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -25,23 +25,36 @@ 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 = LineItem | PriceLineItem;
+type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
     line_items: CheckoutLineItemInput[];
     /** 고객 지갑 주소 (선택) */
@@ -54,6 +67,17 @@ interface CreateSessionParams {
      * 예: ['eip155:84532', 'eip155:11155420', 'eip155:80002', 'eip155:421614']
      */
     allowed_pay_chains?: string[];
+    /**
+     * chain×token cell 허용 목록(**결제 수단** 표준 입력) — buyer 가 (체인, 토큰) 조합을 고른다.
+     * allowed_pay_chains(×단일 currency shorthand)보다 우선. 서로 다른 토큰을 섞을 때 사용.
+     * `chain` 은 short-name('base','tron','solana') 또는 CAIP-2 둘 다 허용(서버가 mode-relative 로 정규화).
+     * paymentLinks.allowed_assets 와 동일 형태(SDK 일관).
+     * 예: [{ chain: 'base', token: 'USDC' }, { chain: 'tron', token: 'USDT' }]
+     */
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }>;
     /** 결제 자산 (예: USDC) */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
@@ -83,7 +107,7 @@ interface CheckoutSession {
     settled_at: string | null;
     tx_hash: string | null;
     created_at: string;
-    /** 'hosted' — 결제 경로. hosted deposit-address 단일 경로. */
+    /** 'hosted' — 결제 경로. 안2 는 hosted deposit-address 단일 경로. */
     payment_source?: string;
     /** 호스티드 결제 페이지 URL (token 쿼리 포함). backend 응답 그대로 사용 — buyer를 이 URL로 redirect. */
     checkout_url?: string;
@@ -93,15 +117,19 @@ interface CheckoutSession {
     url: string;
 }
 /**
- * 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
+ * 안2 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
  * `issueDepositAddress({ chain, token })` 로 입금주소를 발급받는다. 단일-자산 세션은 1개.
  */
 interface PaymentOption {
-    /** CAIP-2 (예: eip155:8453) */
+    /** CAIP-2 (예: eip155:8453, tron:0x2b6653dc, solana:5eykt4…). 체인 식별의 canonical. */
     caip2: string;
-    chain_id: number;
+    /** 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;
 }
 /**
  * `getPublicSession()` (`GET /v1/checkout/sessions/:id/public`) 응답 — 인증 불요(공개).
@@ -124,6 +152,8 @@ interface PublicSession {
     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;
@@ -145,7 +175,11 @@ interface PublicSession {
 interface IssueDepositAddressParams {
     /** 결제 페이지 접근 증명(HMAC). createSession 응답의 session_token. */
     session_token: string;
-    /** 환불 주소(0x EVM). 필수. */
+    /**
+     * 환불 주소. 필수. 선택한 체인의 VM 형식이어야 한다:
+     *   EVM=0x…, Tron=base58(T…), Solana=base58. 결제와 같은 네트워크의 본인 주소.
+     * 금액부족/잘못된토큰/만료 시 이 주소로 환불되며, 입금주소에 커밋되어 발급 후 변경 불가.
+     */
     refundAddress: string;
     /** 선택 자산의 chain(CAIP-2 또는 short-name). 멀티옵션 세션 필수. */
     chain?: string;
@@ -158,7 +192,7 @@ interface IssueDepositAddressParams {
 interface DepositAddress {
     sessionId: string;
     chain: string;
-    /** 주문별 CREATE2 forwarder 입금주소. */
+    /** 주문별 결정적 입금주소(EVM/Tron=CREATE2 forwarder, Solana=order PDA 의 deposit ATA). */
     depositAddress: string;
     expectedToken: string;
     /** Atomic 정수 문자열. */
@@ -248,9 +282,17 @@ interface UpdateProductParams {
     metadata?: Record<string, unknown>;
     status?: 'active' | 'inactive';
 }
+/**
+ * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
+ *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ */
 interface CreatePriceParams {
-    /** 원자 단위 정수 문자열 ($1 = "1000000"). `toAtomicUSDC('1.00')` 헬퍼 사용 권장 */
-    amount_atomic: string;
+    /** 사람 표기 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';
@@ -274,6 +316,80 @@ 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)
@@ -325,6 +441,33 @@ declare class PricesResource {
      */
     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 — 클라이언트
@@ -342,25 +485,29 @@ declare class BitPalCheckoutClient {
     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: toAtomicUSDC('29.00'), currency: 'USDC' }],
+     *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
      * });
      * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
@@ -384,7 +531,7 @@ declare class BitPalCheckoutClient {
     /**
      * 주문별 비수탁 입금주소 발급 (`POST /v1/checkout/sessions/:id/deposit-address`).
      *
-     * 비수탁 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
+     * 안2 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
      * 그 주문 전용 CREATE2 forwarder 주소를 돌려준다. 구매자는 아무 지갑/거래소에서 **정확한 금액**을
      * 그 주소로 일반 송금하면 된다(서명·연결 불필요). watcher 가 감지 → keeper 가 정산.
      *
@@ -503,35 +650,41 @@ 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 fromAtomic(atomic: string, decimals: number): string;
+/**
+ * decimal → atomic μUSDC (6dp). 하위호환 별칭 — 새 코드는 `toAtomic(decimal, decimals)` 권장
+ *   (BNB USDT=18dp 등 non-6dp 토큰은 이 헬퍼로 처리 불가).
+ * @example toAtomicUSDC('29.00') // '29000000'
+ */
+declare function toAtomicUSDC(decimal: string): string;
+/**
+ * atomic μUSDC(6dp) → decimal. 하위호환 별칭 — 새 코드는 `fromAtomic(atomic, decimals)` 권장.
+ * @example fromAtomicUSDC('29000000') // '29.00'
  */
 declare function fromAtomicUSDC(atomic: string): string;
 
@@ -547,8 +700,8 @@ declare function fromAtomicUSDC(atomic: string): string;
  * const bitpal = new BitPal({ apiKey: 'bp_test_...' });
  *
  * const { data: session } = await bitpal.checkout.createSession({
- *   // amount 는 원자 단위 μUSDC 문자열(6 decimals). $29.00 → '29000000'. toAtomicUSDC 사용 권장.
- *   line_items: [{ name: 'Pro Plan', amount: toAtomicUSDC('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 (checkout_url 별칭)
@@ -563,4 +716,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-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 };
+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 };

package/dist/index.d.ts

@@ -25,23 +25,36 @@ 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 = LineItem | PriceLineItem;
+type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
     line_items: CheckoutLineItemInput[];
     /** 고객 지갑 주소 (선택) */
@@ -54,6 +67,17 @@ interface CreateSessionParams {
      * 예: ['eip155:84532', 'eip155:11155420', 'eip155:80002', 'eip155:421614']
      */
     allowed_pay_chains?: string[];
+    /**
+     * chain×token cell 허용 목록(**결제 수단** 표준 입력) — buyer 가 (체인, 토큰) 조합을 고른다.
+     * allowed_pay_chains(×단일 currency shorthand)보다 우선. 서로 다른 토큰을 섞을 때 사용.
+     * `chain` 은 short-name('base','tron','solana') 또는 CAIP-2 둘 다 허용(서버가 mode-relative 로 정규화).
+     * paymentLinks.allowed_assets 와 동일 형태(SDK 일관).
+     * 예: [{ chain: 'base', token: 'USDC' }, { chain: 'tron', token: 'USDT' }]
+     */
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }>;
     /** 결제 자산 (예: USDC) */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
@@ -83,7 +107,7 @@ interface CheckoutSession {
     settled_at: string | null;
     tx_hash: string | null;
     created_at: string;
-    /** 'hosted' — 결제 경로. hosted deposit-address 단일 경로. */
+    /** 'hosted' — 결제 경로. 안2 는 hosted deposit-address 단일 경로. */
     payment_source?: string;
     /** 호스티드 결제 페이지 URL (token 쿼리 포함). backend 응답 그대로 사용 — buyer를 이 URL로 redirect. */
     checkout_url?: string;
@@ -93,15 +117,19 @@ interface CheckoutSession {
     url: string;
 }
 /**
- * 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
+ * 안2 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
  * `issueDepositAddress({ chain, token })` 로 입금주소를 발급받는다. 단일-자산 세션은 1개.
  */
 interface PaymentOption {
-    /** CAIP-2 (예: eip155:8453) */
+    /** CAIP-2 (예: eip155:8453, tron:0x2b6653dc, solana:5eykt4…). 체인 식별의 canonical. */
     caip2: string;
-    chain_id: number;
+    /** 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;
 }
 /**
  * `getPublicSession()` (`GET /v1/checkout/sessions/:id/public`) 응답 — 인증 불요(공개).
@@ -124,6 +152,8 @@ interface PublicSession {
     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;
@@ -145,7 +175,11 @@ interface PublicSession {
 interface IssueDepositAddressParams {
     /** 결제 페이지 접근 증명(HMAC). createSession 응답의 session_token. */
     session_token: string;
-    /** 환불 주소(0x EVM). 필수. */
+    /**
+     * 환불 주소. 필수. 선택한 체인의 VM 형식이어야 한다:
+     *   EVM=0x…, Tron=base58(T…), Solana=base58. 결제와 같은 네트워크의 본인 주소.
+     * 금액부족/잘못된토큰/만료 시 이 주소로 환불되며, 입금주소에 커밋되어 발급 후 변경 불가.
+     */
     refundAddress: string;
     /** 선택 자산의 chain(CAIP-2 또는 short-name). 멀티옵션 세션 필수. */
     chain?: string;
@@ -158,7 +192,7 @@ interface IssueDepositAddressParams {
 interface DepositAddress {
     sessionId: string;
     chain: string;
-    /** 주문별 CREATE2 forwarder 입금주소. */
+    /** 주문별 결정적 입금주소(EVM/Tron=CREATE2 forwarder, Solana=order PDA 의 deposit ATA). */
     depositAddress: string;
     expectedToken: string;
     /** Atomic 정수 문자열. */
@@ -248,9 +282,17 @@ interface UpdateProductParams {
     metadata?: Record<string, unknown>;
     status?: 'active' | 'inactive';
 }
+/**
+ * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
+ *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ */
 interface CreatePriceParams {
-    /** 원자 단위 정수 문자열 ($1 = "1000000"). `toAtomicUSDC('1.00')` 헬퍼 사용 권장 */
-    amount_atomic: string;
+    /** 사람 표기 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';
@@ -274,6 +316,80 @@ 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)
@@ -325,6 +441,33 @@ declare class PricesResource {
      */
     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 — 클라이언트
@@ -342,25 +485,29 @@ declare class BitPalCheckoutClient {
     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: toAtomicUSDC('29.00'), currency: 'USDC' }],
+     *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
      * });
      * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
@@ -384,7 +531,7 @@ declare class BitPalCheckoutClient {
     /**
      * 주문별 비수탁 입금주소 발급 (`POST /v1/checkout/sessions/:id/deposit-address`).
      *
-     * 비수탁 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
+     * 안2 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
      * 그 주문 전용 CREATE2 forwarder 주소를 돌려준다. 구매자는 아무 지갑/거래소에서 **정확한 금액**을
      * 그 주소로 일반 송금하면 된다(서명·연결 불필요). watcher 가 감지 → keeper 가 정산.
      *
@@ -503,35 +650,41 @@ 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 fromAtomic(atomic: string, decimals: number): string;
+/**
+ * decimal → atomic μUSDC (6dp). 하위호환 별칭 — 새 코드는 `toAtomic(decimal, decimals)` 권장
+ *   (BNB USDT=18dp 등 non-6dp 토큰은 이 헬퍼로 처리 불가).
+ * @example toAtomicUSDC('29.00') // '29000000'
+ */
+declare function toAtomicUSDC(decimal: string): string;
+/**
+ * atomic μUSDC(6dp) → decimal. 하위호환 별칭 — 새 코드는 `fromAtomic(atomic, decimals)` 권장.
+ * @example fromAtomicUSDC('29000000') // '29.00'
  */
 declare function fromAtomicUSDC(atomic: string): string;
 
@@ -547,8 +700,8 @@ declare function fromAtomicUSDC(atomic: string): string;
  * const bitpal = new BitPal({ apiKey: 'bp_test_...' });
  *
  * const { data: session } = await bitpal.checkout.createSession({
- *   // amount 는 원자 단위 μUSDC 문자열(6 decimals). $29.00 → '29000000'. toAtomicUSDC 사용 권장.
- *   line_items: [{ name: 'Pro Plan', amount: toAtomicUSDC('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 (checkout_url 별칭)
@@ -563,4 +716,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-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 };
+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 };

package/dist/index.js

@@ -55,8 +55,39 @@ var PricesResource = class {
     return this.request("PATCH", `/v1/checkout/prices/${encodeURIComponent(priceId)}`, params);
   }
 };
+var PaymentLinksResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  /** POST /v1/checkout/payment-links */
+  create(params) {
+    return this.request("POST", "/v1/checkout/payment-links", params);
+  }
+  /** GET /v1/checkout/payment-links */
+  list(params) {
+    return this.request("GET", `/v1/checkout/payment-links${toQuery(params)}`);
+  }
+  /** GET /v1/checkout/payment-links/:id */
+  retrieve(linkId) {
+    return this.request("GET", `/v1/checkout/payment-links/${encodeURIComponent(linkId)}`);
+  }
+  /** PATCH /v1/checkout/payment-links/:id */
+  update(linkId, params) {
+    return this.request("PATCH", `/v1/checkout/payment-links/${encodeURIComponent(linkId)}`, params);
+  }
+};
 
 // src/client.ts
+function validateLineItem(li) {
+  if ("price_id" in li) return li;
+  const hasHuman = li.amount != null;
+  const hasAtomic = li.amount_atomic != null;
+  if (hasHuman === hasAtomic) {
+    throw new Error('[BitPal] line item requires exactly one of `amount` (USD number, e.g. "29") or `amount_atomic` (raw \u03BCUSD integer, e.g. "29000000").');
+  }
+  return li;
+}
 var DEFAULT_BASE_URL = "https://api.bitpal.io";
 var DEFAULT_TIMEOUT = 3e4;
 var BitPalCheckoutClient = class {
@@ -68,6 +99,8 @@ var BitPalCheckoutClient = class {
   products;
   /** PROD-LINK-3a-SDK: immutable Price 관리 — 가격 변경은 비활성화 + 새 price 생성 */
   prices;
+  /** PROD-LINK-4-SDK: Payment Link 관리 — 대시보드 없이 코드로 결제 링크 생성 (server-side 전용) */
+  paymentLinks;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -75,6 +108,7 @@ var BitPalCheckoutClient = class {
     const requester = (method, path, body) => this.request(method, path, body);
     this.products = new ProductsResource(requester);
     this.prices = new PricesResource(requester);
+    this.paymentLinks = new PaymentLinksResource(requester);
   }
   /* ─── 내부 HTTP ─── */
   async request(method, path, body, extraHeaders) {
@@ -107,20 +141,22 @@ var BitPalCheckoutClient = class {
   /**
    * 체크아웃 세션 생성.
    *
-   * 모든 `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: toAtomicUSDC('29.00'), currency: 'USDC' }],
+   *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
    *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
    * });
    * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
@@ -129,10 +165,15 @@ var BitPalCheckoutClient = class {
     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 body = {
+      ...params,
+      line_items: params.line_items.map(validateLineItem),
+      ...params.allowed_assets ? { allowed_assets: params.allowed_assets.map((a) => ({ caip2: a.chain, token: a.token })) } : {}
+    };
     const res = await this.request(
       "POST",
       "/v1/checkout/sessions",
-      params
+      body
     );
     if (res.data) {
       if (res.data.checkout_url) {
@@ -162,7 +203,7 @@ var BitPalCheckoutClient = class {
       `/v1/checkout/sessions${query ? `?${query}` : ""}`
     );
   }
-  /* ─── 비수탁 결제 (deposit-address) ─── */
+  /* ─── 안2 비수탁 결제 (deposit-address) ─── */
   /**
    * 공개 세션 조회 (`GET /v1/checkout/sessions/:id/public`) — 인증 불요.
    *
@@ -178,7 +219,7 @@ var BitPalCheckoutClient = class {
   /**
    * 주문별 비수탁 입금주소 발급 (`POST /v1/checkout/sessions/:id/deposit-address`).
    *
-   * 비수탁 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
+   * 안2 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
    * 그 주문 전용 CREATE2 forwarder 주소를 돌려준다. 구매자는 아무 지갑/거래소에서 **정확한 금액**을
    * 그 주소로 일반 송금하면 된다(서명·연결 불필요). watcher 가 감지 → keeper 가 정산.
    *
@@ -283,26 +324,40 @@ function parseWebhookEvent(body) {
 }
 
 // src/amount.ts
-var USDC_DECIMALS = 6n;
-var USDC_SCALE = 10n ** USDC_DECIMALS;
-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)`);
+function toAtomic(decimal, decimals) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    throw new Error(`toAtomic: invalid decimals '${decimals}'`);
+  }
+  const fracPattern = decimals > 0 ? `(\\.\\d{1,${decimals}})?` : "";
+  if (typeof decimal !== "string" || !new RegExp(`^\\d+${fracPattern}$`).test(decimal)) {
+    throw new Error(`toAtomic: invalid decimal '${decimal}' (max ${decimals} fractional digits, no negatives)`);
   }
+  const scale = 10n ** BigInt(decimals);
   const [whole = "0", frac = ""] = decimal.split(".");
-  const fracPadded = frac.padEnd(Number(USDC_DECIMALS), "0");
-  return (BigInt(whole) * USDC_SCALE + BigInt(fracPadded || "0")).toString();
+  const fracPadded = frac.padEnd(decimals, "0");
+  return (BigInt(whole) * scale + BigInt(fracPadded || "0")).toString();
 }
-function fromAtomicUSDC(atomic) {
+function fromAtomic(atomic, decimals) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    throw new Error(`fromAtomic: invalid decimals '${decimals}'`);
+  }
   if (typeof atomic !== "string" || !/^\d+$/.test(atomic)) {
-    throw new Error(`fromAtomicUSDC: invalid atomic '${atomic}' (must be non-negative integer string)`);
+    throw new Error(`fromAtomic: invalid atomic '${atomic}' (must be non-negative integer string)`);
   }
+  const scale = 10n ** BigInt(decimals);
   const big = BigInt(atomic);
-  const whole = big / USDC_SCALE;
-  const frac = big % USDC_SCALE;
-  const fracStr = frac.toString().padStart(Number(USDC_DECIMALS), "0").replace(/0+$/, "");
+  const whole = big / scale;
+  const frac = big % scale;
+  if (decimals === 0) return `${whole}`;
+  const fracStr = frac.toString().padStart(decimals, "0").replace(/0+$/, "");
   return fracStr.length > 0 ? `${whole}.${fracStr.padEnd(2, "0")}` : `${whole}.00`;
 }
+function toAtomicUSDC(decimal) {
+  return toAtomic(decimal, 6);
+}
+function fromAtomicUSDC(atomic) {
+  return fromAtomic(atomic, 6);
+}
 
 // src/index.ts
 var BitPal = class {
@@ -317,11 +372,14 @@ export {
   BitPalCheckoutClient,
   BitPalError,
   CHECKOUT_WEBHOOK_EVENTS,
+  PaymentLinksResource,
   PricesResource,
   ProductsResource,
   WEBHOOK_HEADERS,
+  fromAtomic,
   fromAtomicUSDC,
   parseWebhookEvent,
+  toAtomic,
   toAtomicUSDC,
   verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "BitPal Checkout SDK — non-custodial crypto checkout: create sessions, issue per-order deposit addresses, poll status, verify signed webhooks.",
   "license": "MIT",
   "repository": {