@bitpal/checkout 0.9.0 → 0.11.0

package/README.md

@@ -180,6 +180,7 @@ app.post(
 | `checkout.session.expired` | Session expired unpaid |
 | `checkout.session.unresolved` | Underpaid / overpaid / wrong token — needs review |
 | `checkout.refund.recorded` | An on-chain auto-refund (over / under / late payment) was recorded |
+| `x402.payment.resolved` | An x402 payment that `/settle` left unresolved was later settled on-chain (see below) |
 
 ### ⚠️ Replay defense + at-least-once delivery
 
@@ -227,6 +228,12 @@ handler with `X-PAYMENT-RESPONSE` set. The middleware also does what the API can
   timeout — answers `503` and asks for a retry with the *same* header. Handing back a `402` there
   would make the caller re-sign and pay twice.
 
+When `/settle` answers `503`, nobody knows yet whether the money moved — so BitPal watches the chain
+and tells you how it ended with a **`x402.payment.resolved`** webhook (`status`: `confirmed` |
+`reverted` | `expired`, plus `payment_id` and `tx_hash`). It fires only on that path: the normal case
+already returned the result to you, and you should not have to handle the same outcome twice. Verify
+it exactly like a checkout webhook.
+
 Not on Express? `X402Gate` is the framework-neutral core — give it the header and the resource URL,
 it tells you whether to bill or serve. On a `settled` result, call `commit()` once you have delivered
 the response, or `release()` if you could not.
@@ -242,9 +249,13 @@ the response, or `release()` if you could not.
 
 ### Payer side
 
-The fee split needs two authorizations, which a stock x402 client does not know about.
-`createX402Payment` reads the `402` and builds both. You supply the signer; the SDK has no crypto
-dependency.
+The payer signs **one** standard EIP-3009 authorization, so the `X-PAYMENT` payload is plain x402:
+`{ signature, authorization }`. The fee split happens on-chain — `payTo` in the `402` is not the
+merchant's wallet but a CREATE2 address that commits to the whole split, so nothing extra has to be
+signed for it.
+
+`createX402Payment` reads the `402` and builds the header. You supply the signer; the SDK has no
+crypto dependency.
 
 ```ts
 import { createX402Payment } from '@bitpal/checkout';
@@ -270,6 +281,10 @@ if (res.status === 402) {
 Amounts are human-readable (`'1.00'`), the same model as `line_items[].amount` — the server converts.
 Pass `amountAtomic` instead if you already have raw units.
 
+The `402` also carries a `feeBreakdown` (net / fee / bps / recipient). It is informational — a payer
+can ignore it entirely and still pay correctly, because the split is already committed by the `payTo`
+address. It is there so you can see where the money goes without reading the chain.
+
 EOA signers only — smart-contract wallets cannot sign EIP-3009 authorizations. Amounts are exact:
 over- and underpayment are both rejected, and this lane has no refund path. Authorizations are valid
 for 90–3600 seconds (the server's floor is 60s; the extra 30s absorbs clock skew and round trips).
@@ -301,6 +316,26 @@ store wiring session creation + webhook verification + idempotency.
 pnpm build   # tsup → dist/ (ESM + .d.ts)
 ```
 
+## Migrating to 0.11.0 (breaking — x402 payer only)
+
+The `X-PAYMENT` payload changed from BitPal's two-authorization shape to the **x402 standard**:
+
+```
+0.10.0   payload: { merchant: {...}, fee: {...} }     two signatures
+0.11.0   payload: { signature, authorization }        one signature — plain x402
+```
+
+- If you call `createX402Payment`, nothing changes in your code. It signs once now instead of twice,
+  and the wallet prompts once.
+- If you built the payload by hand, rebuild it in the standard shape.
+- `splitSignature` is gone. `normalizeSignature` replaces it — same input handling (65-byte or
+  EIP-2098 compact, `v` of 0/1/27/28) but it returns a 65-byte packed hex string, which is what the
+  payload carries.
+- The `402` is unchanged apart from `payTo`, which now points at the settlement address rather than
+  the merchant wallet. Both `X402Gate` and `x402()` handle this for you.
+
+Old headers are rejected — a payer on 0.10.0 gets a fresh `402` and re-signs, so no payment is lost.
+
 ## Migrating from 0.3.x → 0.5.0 (breaking)
 
 - **Webhook verification now requires the timestamp** and enforces replay defense. Pass the

package/dist/index.cjs

@@ -48,8 +48,8 @@ __export(index_exports, {
   encodePaymentHeader: () => encodePaymentHeader,
   fromAtomic: () => fromAtomic,
   fromAtomicUSDC: () => fromAtomicUSDC,
+  normalizeSignature: () => normalizeSignature,
   parseWebhookEvent: () => parseWebhookEvent,
-  splitSignature: () => splitSignature,
   toAtomic: () => toAtomic,
   toAtomicUSDC: () => toAtomicUSDC,
   verifyWebhookSignature: () => verifyWebhookSignature,
@@ -351,7 +351,12 @@ var CHECKOUT_WEBHOOK_EVENTS = [
   "checkout.session.settled",
   "checkout.session.expired",
   "checkout.session.unresolved",
-  "checkout.refund.recorded"
+  "checkout.refund.recorded",
+  // x402 결제의 **사후** 확정. 정상 경로(/settle 이 그 자리에서 결과를 반환)는 발행되지 않는다 —
+  //   이미 아는 결과를 중복으로 받지 않게 하기 위함이다. /settle 이 503 을 반환해 결과를 모른 채
+  //   남았을 때, reconciler 가 체인을 보고 종결시키면 이 이벤트가 온다.
+  //   payload: { payment_id, status: 'confirmed'|'reverted'|'expired', tx_hash, resource, amount, … }
+  "x402.payment.resolved"
 ];
 var WEBHOOK_HEADERS = {
   signature: "X-Webhook-Signature-256",
@@ -539,11 +544,11 @@ var X402Gate = class {
     } catch {
       return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
     }
-    const merchant = payload?.payload?.merchant;
-    if (!merchant?.from || !merchant?.nonce) {
+    const auth = payload?.payload?.authorization;
+    if (!auth?.from || !auth?.nonce) {
       return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
     }
-    const key = `${payload.network}:${merchant.from.toLowerCase()}:${merchant.nonce.toLowerCase()}`;
+    const key = `${payload.network}:${auth.from.toLowerCase()}:${auth.nonce.toLowerCase()}`;
     const claim = await this.store.claim(key, this.maxTimeoutSeconds);
     if (claim === "used") {
       return {
@@ -581,7 +586,12 @@ var X402Gate = class {
       },
       paymentRequirements: {
         asset: accept.asset,
+        // payer 가 서명한 목적지 = 분배 조건을 커밋한 정산 주소.
         payTo: accept.payTo,
+        // 머천트 정산 지갑. facilitator 가 이 값으로 정산 주소를 재계산해 payTo 와 대조한다 —
+        //   CREATE2 는 단방향이라 payTo 에서 되돌릴 수 없으므로 따로 보내야 한다.
+        //   우리 설정값을 그대로 쓴다(402 응답에서 읽지 않는다 — 그러면 재계산의 의미가 없다).
+        merchant: this.opts.payTo,
         maxAmountRequired: accept.maxAmountRequired,
         resource: accept.resource
       }
@@ -633,7 +643,7 @@ var X402Gate = class {
       txHash: settled.tx_hash,
       feeTxHash: settled.fee_tx_hash ?? null,
       network: settled.network,
-      payer: merchant.from,
+      payer: auth.from,
       amount: accept.maxAmountRequired,
       idempotent: settled.idempotent ?? false
     };
@@ -645,7 +655,7 @@ var X402Gate = class {
         success: true,
         transaction: settled.tx_hash,
         network: settled.network,
-        payer: merchant.from,
+        payer: auth.from,
         paymentId: settled.payment_id
       }),
       // 소진 확정은 **응답을 실제로 내준 뒤**다. 핸들러가 throw 하거나 프로세스가 죽으면 결제만 하고
@@ -766,18 +776,22 @@ function assertPaymentPayload(value) {
     throw new Error("[BitPal] x402: invalid network.");
   }
   const inner = asObject(root.payload, "payload");
-  const merchant = assertAuthorization(inner.merchant, "merchant");
-  const fee = inner.fee === void 0 ? void 0 : assertAuthorization(inner.fee, "fee");
+  if (typeof inner.signature !== "string" || !PACKED_SIG_RE.test(inner.signature)) {
+    throw new Error("[BitPal] x402: invalid payload.signature (expected 65-byte packed hex).");
+  }
   return {
     x402Version: 1,
     scheme: "exact",
     network: root.network,
-    payload: fee ? { merchant, fee } : { merchant }
+    payload: {
+      signature: inner.signature,
+      authorization: assertAuthorization(inner.authorization, "authorization")
+    }
   };
 }
+var PACKED_SIG_RE = /^0x[0-9a-fA-F]{130}$/;
 function assertAuthorization(value, label) {
-  const a = asObject(value, `${label} authorization`);
-  const sig = asObject(a.signature, `${label} signature`);
+  const a = asObject(value, label);
   const check = (ok, field) => {
     if (!ok) throw new Error(`[BitPal] x402: invalid ${label}.${field}.`);
   };
@@ -787,17 +801,13 @@ function assertAuthorization(value, label) {
   check(typeof a.validAfter === "string" && DECIMAL_RE.test(a.validAfter), "validAfter");
   check(typeof a.validBefore === "string" && DECIMAL_RE.test(a.validBefore), "validBefore");
   check(typeof a.nonce === "string" && HEX32_RE.test(a.nonce), "nonce");
-  check(typeof sig.v === "number" && Number.isInteger(sig.v), "signature.v");
-  check(typeof sig.r === "string" && HEX32_RE.test(sig.r), "signature.r");
-  check(typeof sig.s === "string" && HEX32_RE.test(sig.s), "signature.s");
   return {
     from: a.from,
     to: a.to,
     value: a.value,
     validAfter: a.validAfter,
     validBefore: a.validBefore,
-    nonce: a.nonce,
-    signature: { v: sig.v, r: sig.r, s: sig.s }
+    nonce: a.nonce
   };
 }
 function asObject(value, label) {
@@ -871,49 +881,33 @@ async function createX402Payment(options) {
   }
   const validAfter = "0";
   const validBefore = String(now + validFor);
-  const nextNonce = options.randomNonce ?? randomNonce;
-  const fee = accept.feeBreakdown;
-  const feeAmount = fee ? BigInt(fee.feeAmount) : 0n;
-  const merchantValue = fee ? fee.netAmount : accept.maxAmountRequired;
-  const merchant = await signAuthorization({
-    domain,
-    signTypedData: options.signTypedData,
+  const nonce = (options.randomNonce ?? randomNonce)();
+  const authorization = {
     from: options.from,
     to: accept.payTo,
-    value: merchantValue,
+    value: accept.maxAmountRequired,
     validAfter,
     validBefore,
-    nonce: nextNonce()
-  });
-  let feeLeg;
-  if (feeAmount > 0n) {
-    if (!fee?.feeRecipient) {
-      throw new Error("[BitPal] x402: feeAmount > 0 but feeRecipient is missing in the 402 response.");
-    }
-    feeLeg = await signAuthorization({
+    nonce
+  };
+  const signature = normalizeSignature(
+    await options.signTypedData({
       domain,
-      signTypedData: options.signTypedData,
-      from: options.from,
-      to: fee.feeRecipient,
-      value: fee.feeAmount,
-      validAfter,
-      validBefore,
-      nonce: nextNonce()
-    });
-    if (feeLeg.nonce.toLowerCase() === merchant.nonce.toLowerCase()) {
-      throw new Error("[BitPal] x402: the two authorizations must use different nonces.");
-    }
-  }
+      types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+      primaryType: "TransferWithAuthorization",
+      message: authorization
+    })
+  );
   const payload = {
     x402Version: 1,
     scheme: "exact",
     network: accept.network,
-    payload: feeLeg ? { merchant, fee: feeLeg } : { merchant }
+    payload: { signature, authorization }
   };
   return {
     header: encodePaymentHeader(payload),
     payload,
-    totalAmount: (BigInt(merchantValue) + feeAmount).toString()
+    totalAmount: accept.maxAmountRequired
   };
 }
 function resolveAccept(input) {
@@ -924,41 +918,24 @@ function resolveAccept(input) {
   }
   return input;
 }
-async function signAuthorization(args) {
-  const message = {
-    from: args.from,
-    to: args.to,
-    value: args.value,
-    validAfter: args.validAfter,
-    validBefore: args.validBefore,
-    nonce: args.nonce
-  };
-  const signature = await args.signTypedData({
-    domain: args.domain,
-    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
-    primaryType: "TransferWithAuthorization",
-    message
-  });
-  return { ...message, signature: splitSignature(signature) };
-}
-function splitSignature(signature) {
+function normalizeSignature(signature) {
   const hex = signature.startsWith("0x") ? signature.slice(2) : signature;
   if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== 130 && hex.length !== 128) {
     throw new Error(
       `[BitPal] x402: expected a 65-byte or 64-byte (EIP-2098) hex signature, got ${signature.length} chars.`
     );
   }
-  const r = `0x${hex.slice(0, 64)}`;
+  const r = hex.slice(0, 64);
   if (hex.length === 128) {
     const yParityAndS = BigInt(`0x${hex.slice(64, 128)}`);
     const yParity = Number(yParityAndS >> 255n & 1n);
-    const s2 = yParityAndS & (1n << 255n) - 1n;
-    return { v: 27 + yParity, r, s: `0x${s2.toString(16).padStart(64, "0")}` };
+    const s2 = (yParityAndS & (1n << 255n) - 1n).toString(16).padStart(64, "0");
+    return `0x${r}${s2}${(27 + yParity).toString(16).padStart(2, "0")}`;
   }
-  const s = `0x${hex.slice(64, 128)}`;
+  const s = hex.slice(64, 128);
   const raw = parseInt(hex.slice(128, 130), 16);
-  if (raw === 27 || raw === 28) return { v: raw, r, s };
-  if (raw === 0 || raw === 1) return { v: raw + 27, r, s };
+  if (raw === 27 || raw === 28) return `0x${r}${s}${raw.toString(16)}`;
+  if (raw === 0 || raw === 1) return `0x${r}${s}${(raw + 27).toString(16)}`;
   throw new Error(`[BitPal] x402: unexpected signature v=${raw} (expected 0, 1, 27 or 28).`);
 }
 function randomNonce() {
@@ -1000,8 +977,8 @@ var BitPal = class {
   encodePaymentHeader,
   fromAtomic,
   fromAtomicUSDC,
+  normalizeSignature,
   parseWebhookEvent,
-  splitSignature,
   toAtomic,
   toAtomicUSDC,
   verifyWebhookSignature,

package/dist/index.d.cts

@@ -584,7 +584,7 @@ declare class BitPalError extends Error {
 /**
  * BitPal 이 발송하는 webhook 이벤트 타입 전체 목록.
  */
-declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded"];
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded", "x402.payment.resolved"];
 type CheckoutWebhookEvent = (typeof CHECKOUT_WEBHOOK_EVENTS)[number];
 /**
  * Canonical envelope (HTTP body).
@@ -750,6 +750,7 @@ interface X402Requirements {
     x402Version: 1;
     accepts: X402Accept[];
 }
+/** EIP-3009 `TransferWithAuthorization` 의 서명 대상 필드. x402 표준 `payload.authorization`. */
 interface Eip3009Authorization {
     from: string;
     to: string;
@@ -757,21 +758,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 +1083,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 +1124,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, 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, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };

package/dist/index.d.ts

@@ -584,7 +584,7 @@ declare class BitPalError extends Error {
 /**
  * BitPal 이 발송하는 webhook 이벤트 타입 전체 목록.
  */
-declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded"];
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded", "x402.payment.resolved"];
 type CheckoutWebhookEvent = (typeof CHECKOUT_WEBHOOK_EVENTS)[number];
 /**
  * Canonical envelope (HTTP body).
@@ -750,6 +750,7 @@ interface X402Requirements {
     x402Version: 1;
     accepts: X402Accept[];
 }
+/** EIP-3009 `TransferWithAuthorization` 의 서명 대상 필드. x402 표준 `payload.authorization`. */
 interface Eip3009Authorization {
     from: string;
     to: string;
@@ -757,21 +758,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 +1083,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 +1124,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, 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, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };

package/dist/index.js

@@ -292,7 +292,12 @@ var CHECKOUT_WEBHOOK_EVENTS = [
   "checkout.session.settled",
   "checkout.session.expired",
   "checkout.session.unresolved",
-  "checkout.refund.recorded"
+  "checkout.refund.recorded",
+  // x402 결제의 **사후** 확정. 정상 경로(/settle 이 그 자리에서 결과를 반환)는 발행되지 않는다 —
+  //   이미 아는 결과를 중복으로 받지 않게 하기 위함이다. /settle 이 503 을 반환해 결과를 모른 채
+  //   남았을 때, reconciler 가 체인을 보고 종결시키면 이 이벤트가 온다.
+  //   payload: { payment_id, status: 'confirmed'|'reverted'|'expired', tx_hash, resource, amount, … }
+  "x402.payment.resolved"
 ];
 var WEBHOOK_HEADERS = {
   signature: "X-Webhook-Signature-256",
@@ -480,11 +485,11 @@ var X402Gate = class {
     } catch {
       return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
     }
-    const merchant = payload?.payload?.merchant;
-    if (!merchant?.from || !merchant?.nonce) {
+    const auth = payload?.payload?.authorization;
+    if (!auth?.from || !auth?.nonce) {
       return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
     }
-    const key = `${payload.network}:${merchant.from.toLowerCase()}:${merchant.nonce.toLowerCase()}`;
+    const key = `${payload.network}:${auth.from.toLowerCase()}:${auth.nonce.toLowerCase()}`;
     const claim = await this.store.claim(key, this.maxTimeoutSeconds);
     if (claim === "used") {
       return {
@@ -522,7 +527,12 @@ var X402Gate = class {
       },
       paymentRequirements: {
         asset: accept.asset,
+        // payer 가 서명한 목적지 = 분배 조건을 커밋한 정산 주소.
         payTo: accept.payTo,
+        // 머천트 정산 지갑. facilitator 가 이 값으로 정산 주소를 재계산해 payTo 와 대조한다 —
+        //   CREATE2 는 단방향이라 payTo 에서 되돌릴 수 없으므로 따로 보내야 한다.
+        //   우리 설정값을 그대로 쓴다(402 응답에서 읽지 않는다 — 그러면 재계산의 의미가 없다).
+        merchant: this.opts.payTo,
         maxAmountRequired: accept.maxAmountRequired,
         resource: accept.resource
       }
@@ -574,7 +584,7 @@ var X402Gate = class {
       txHash: settled.tx_hash,
       feeTxHash: settled.fee_tx_hash ?? null,
       network: settled.network,
-      payer: merchant.from,
+      payer: auth.from,
       amount: accept.maxAmountRequired,
       idempotent: settled.idempotent ?? false
     };
@@ -586,7 +596,7 @@ var X402Gate = class {
         success: true,
         transaction: settled.tx_hash,
         network: settled.network,
-        payer: merchant.from,
+        payer: auth.from,
         paymentId: settled.payment_id
       }),
       // 소진 확정은 **응답을 실제로 내준 뒤**다. 핸들러가 throw 하거나 프로세스가 죽으면 결제만 하고
@@ -707,18 +717,22 @@ function assertPaymentPayload(value) {
     throw new Error("[BitPal] x402: invalid network.");
   }
   const inner = asObject(root.payload, "payload");
-  const merchant = assertAuthorization(inner.merchant, "merchant");
-  const fee = inner.fee === void 0 ? void 0 : assertAuthorization(inner.fee, "fee");
+  if (typeof inner.signature !== "string" || !PACKED_SIG_RE.test(inner.signature)) {
+    throw new Error("[BitPal] x402: invalid payload.signature (expected 65-byte packed hex).");
+  }
   return {
     x402Version: 1,
     scheme: "exact",
     network: root.network,
-    payload: fee ? { merchant, fee } : { merchant }
+    payload: {
+      signature: inner.signature,
+      authorization: assertAuthorization(inner.authorization, "authorization")
+    }
   };
 }
+var PACKED_SIG_RE = /^0x[0-9a-fA-F]{130}$/;
 function assertAuthorization(value, label) {
-  const a = asObject(value, `${label} authorization`);
-  const sig = asObject(a.signature, `${label} signature`);
+  const a = asObject(value, label);
   const check = (ok, field) => {
     if (!ok) throw new Error(`[BitPal] x402: invalid ${label}.${field}.`);
   };
@@ -728,17 +742,13 @@ function assertAuthorization(value, label) {
   check(typeof a.validAfter === "string" && DECIMAL_RE.test(a.validAfter), "validAfter");
   check(typeof a.validBefore === "string" && DECIMAL_RE.test(a.validBefore), "validBefore");
   check(typeof a.nonce === "string" && HEX32_RE.test(a.nonce), "nonce");
-  check(typeof sig.v === "number" && Number.isInteger(sig.v), "signature.v");
-  check(typeof sig.r === "string" && HEX32_RE.test(sig.r), "signature.r");
-  check(typeof sig.s === "string" && HEX32_RE.test(sig.s), "signature.s");
   return {
     from: a.from,
     to: a.to,
     value: a.value,
     validAfter: a.validAfter,
     validBefore: a.validBefore,
-    nonce: a.nonce,
-    signature: { v: sig.v, r: sig.r, s: sig.s }
+    nonce: a.nonce
   };
 }
 function asObject(value, label) {
@@ -812,49 +822,33 @@ async function createX402Payment(options) {
   }
   const validAfter = "0";
   const validBefore = String(now + validFor);
-  const nextNonce = options.randomNonce ?? randomNonce;
-  const fee = accept.feeBreakdown;
-  const feeAmount = fee ? BigInt(fee.feeAmount) : 0n;
-  const merchantValue = fee ? fee.netAmount : accept.maxAmountRequired;
-  const merchant = await signAuthorization({
-    domain,
-    signTypedData: options.signTypedData,
+  const nonce = (options.randomNonce ?? randomNonce)();
+  const authorization = {
     from: options.from,
     to: accept.payTo,
-    value: merchantValue,
+    value: accept.maxAmountRequired,
     validAfter,
     validBefore,
-    nonce: nextNonce()
-  });
-  let feeLeg;
-  if (feeAmount > 0n) {
-    if (!fee?.feeRecipient) {
-      throw new Error("[BitPal] x402: feeAmount > 0 but feeRecipient is missing in the 402 response.");
-    }
-    feeLeg = await signAuthorization({
+    nonce
+  };
+  const signature = normalizeSignature(
+    await options.signTypedData({
       domain,
-      signTypedData: options.signTypedData,
-      from: options.from,
-      to: fee.feeRecipient,
-      value: fee.feeAmount,
-      validAfter,
-      validBefore,
-      nonce: nextNonce()
-    });
-    if (feeLeg.nonce.toLowerCase() === merchant.nonce.toLowerCase()) {
-      throw new Error("[BitPal] x402: the two authorizations must use different nonces.");
-    }
-  }
+      types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+      primaryType: "TransferWithAuthorization",
+      message: authorization
+    })
+  );
   const payload = {
     x402Version: 1,
     scheme: "exact",
     network: accept.network,
-    payload: feeLeg ? { merchant, fee: feeLeg } : { merchant }
+    payload: { signature, authorization }
   };
   return {
     header: encodePaymentHeader(payload),
     payload,
-    totalAmount: (BigInt(merchantValue) + feeAmount).toString()
+    totalAmount: accept.maxAmountRequired
   };
 }
 function resolveAccept(input) {
@@ -865,41 +859,24 @@ function resolveAccept(input) {
   }
   return input;
 }
-async function signAuthorization(args) {
-  const message = {
-    from: args.from,
-    to: args.to,
-    value: args.value,
-    validAfter: args.validAfter,
-    validBefore: args.validBefore,
-    nonce: args.nonce
-  };
-  const signature = await args.signTypedData({
-    domain: args.domain,
-    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
-    primaryType: "TransferWithAuthorization",
-    message
-  });
-  return { ...message, signature: splitSignature(signature) };
-}
-function splitSignature(signature) {
+function normalizeSignature(signature) {
   const hex = signature.startsWith("0x") ? signature.slice(2) : signature;
   if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== 130 && hex.length !== 128) {
     throw new Error(
       `[BitPal] x402: expected a 65-byte or 64-byte (EIP-2098) hex signature, got ${signature.length} chars.`
     );
   }
-  const r = `0x${hex.slice(0, 64)}`;
+  const r = hex.slice(0, 64);
   if (hex.length === 128) {
     const yParityAndS = BigInt(`0x${hex.slice(64, 128)}`);
     const yParity = Number(yParityAndS >> 255n & 1n);
-    const s2 = yParityAndS & (1n << 255n) - 1n;
-    return { v: 27 + yParity, r, s: `0x${s2.toString(16).padStart(64, "0")}` };
+    const s2 = (yParityAndS & (1n << 255n) - 1n).toString(16).padStart(64, "0");
+    return `0x${r}${s2}${(27 + yParity).toString(16).padStart(2, "0")}`;
   }
-  const s = `0x${hex.slice(64, 128)}`;
+  const s = hex.slice(64, 128);
   const raw = parseInt(hex.slice(128, 130), 16);
-  if (raw === 27 || raw === 28) return { v: raw, r, s };
-  if (raw === 0 || raw === 1) return { v: raw + 27, r, s };
+  if (raw === 27 || raw === 28) return `0x${r}${s}${raw.toString(16)}`;
+  if (raw === 0 || raw === 1) return `0x${r}${s}${(raw + 27).toString(16)}`;
   throw new Error(`[BitPal] x402: unexpected signature v=${raw} (expected 0, 1, 27 or 28).`);
 }
 function randomNonce() {
@@ -940,8 +917,8 @@ export {
   encodePaymentHeader,
   fromAtomic,
   fromAtomicUSDC,
+  normalizeSignature,
   parseWebhookEvent,
-  splitSignature,
   toAtomic,
   toAtomicUSDC,
   verifyWebhookSignature,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "BitPal Checkout SDK — non-custodial crypto checkout: create sessions, issue per-order deposit addresses, poll status, verify signed webhooks, and charge per API call with x402.",
   "license": "MIT",
   "repository": {