@zucker-framework/payment 1.0.2 → 1.0.5

package/dist/index.js

@@ -26,30 +26,189 @@ __export(index_exports, {
   OrderNotFoundError: () => OrderNotFoundError,
   OrderService: () => OrderService,
   PAYMENT_PROVIDERS: () => PAYMENT_PROVIDERS,
+  PAYPAL_SUPPORTED_CURRENCIES: () => PAYPAL_SUPPORTED_CURRENCIES,
   PayPalPaymentTransport: () => PayPalPaymentTransport,
   PaymentEvents: () => PaymentEvents,
+  PaymentProviderRegistry: () => PaymentProviderRegistry,
   PaymentRecoveryService: () => PaymentRecoveryService,
-  PaymentService: () => PaymentService,
   RECOVERY_ATTEMPT_STORE: () => RECOVERY_ATTEMPT_STORE,
   RECOVERY_MAIL_SENDER: () => RECOVERY_MAIL_SENDER,
   RECOVERY_URL_GENERATOR: () => RECOVERY_URL_GENERATOR,
   RECOVERY_USER_LOOKUP: () => RECOVERY_USER_LOOKUP,
+  SETTLEMENT_STATES: () => SETTLEMENT_STATES,
   ZuckerPaymentModule: () => ZuckerPaymentModule,
+  adapterSupportsCurrency: () => adapterSupportsCurrency,
+  checkPaymentAdapterContract: () => checkPaymentAdapterContract,
+  createFakeAdapter: () => createFakeAdapter,
+  createPayPalAdapter: () => createPayPalAdapter,
+  createStripeAdapter: () => createStripeAdapter,
   createStripeCheckoutSession: () => createStripeCheckoutSession,
   createStripeClient: () => createStripeClient,
+  currencyExponent: () => currencyExponent,
+  decodePayPalMoneyReturnedEvent: () => decodePayPalMoneyReturnedEvent,
   decodePayPalWebhookEvent: () => decodePayPalWebhookEvent,
   friendlyErrorReason: () => friendlyErrorReason,
+  fromMinorUnits: () => fromMinorUnits,
+  isMoneyMoved: () => isMoneyMoved,
+  isTerminal: () => isTerminal,
   observePayPalOrder: () => observePayPalOrder,
+  observePayPalState: () => observePayPalState,
   observeStripeCheckoutSession: () => observeStripeCheckoutSession,
   observeStripePaymentIntent: () => observeStripePaymentIntent,
+  observeStripeState: () => observeStripeState,
+  reconcile: () => reconcile,
   retrieveStripeCheckoutSession: () => retrieveStripeCheckoutSession,
   retrieveStripePaymentIntent: () => retrieveStripePaymentIntent,
   stripeResourceId: () => stripeResourceId,
+  toMinorUnits: () => toMinorUnits,
   verifyStripeWebhookEvent: () => verifyStripeWebhookEvent
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/payment.service.ts
+// src/contract/payment-contract.ts
+function adapterSupportsCurrency(adapter, currency) {
+  return !adapter.supportedCurrencies || adapter.supportedCurrencies.includes(currency.toUpperCase());
+}
+__name(adapterSupportsCurrency, "adapterSupportsCurrency");
+
+// src/contract/settlement.ts
+var SETTLEMENT_STATES = [
+  /** 已创建，用户尚未授权 */
+  "created",
+  /** 用户已授权但尚未扣款（PayPal APPROVED / Stripe requires_capture） */
+  "authorized",
+  /** 已扣款 */
+  "captured",
+  /** 已全额退款 */
+  "refunded",
+  /** 已部分退款 */
+  "partially_refunded",
+  /** 终态失败 */
+  "failed",
+  /** 终态取消（用户放弃 / 商户撤单） */
+  "canceled",
+  /**
+  * 无法判定。
+  * 不是"失败"，也不是一个可持久化的终态——查询异常、供应商返回中间态、
+  * 回调迟到都会落到这里，必须保留原状继续观察。
+  */
+  "unknown"
+];
+var MONEY_MOVED = /* @__PURE__ */ new Set([
+  "captured",
+  "refunded",
+  "partially_refunded"
+]);
+var TERMINAL = /* @__PURE__ */ new Set([
+  "refunded",
+  "failed",
+  "canceled"
+]);
+function isMoneyMoved(state) {
+  return MONEY_MOVED.has(state);
+}
+__name(isMoneyMoved, "isMoneyMoved");
+function isTerminal(state) {
+  return TERMINAL.has(state);
+}
+__name(isTerminal, "isTerminal");
+function reconcile(current, observed) {
+  if (observed === "unknown") {
+    return {
+      next: current,
+      changed: false,
+      rejected: "not-observable"
+    };
+  }
+  if (observed === current) {
+    return {
+      next: current,
+      changed: false
+    };
+  }
+  if (isMoneyMoved(current) && (observed === "failed" || observed === "canceled")) {
+    return {
+      next: current,
+      changed: false,
+      rejected: "money-already-moved"
+    };
+  }
+  if (current === "refunded") {
+    return {
+      next: current,
+      changed: false,
+      rejected: "already-terminal"
+    };
+  }
+  if (current === "partially_refunded" && observed === "captured") {
+    return {
+      next: current,
+      changed: false,
+      rejected: "already-terminal"
+    };
+  }
+  if (isTerminal(current) && !isMoneyMoved(observed)) {
+    return {
+      next: current,
+      changed: false,
+      rejected: "already-terminal"
+    };
+  }
+  return {
+    next: observed,
+    changed: true
+  };
+}
+__name(reconcile, "reconcile");
+
+// src/contract/money.ts
+var ZERO_DECIMAL = /* @__PURE__ */ new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "UGX",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF"
+]);
+function currencyExponent(currency) {
+  return ZERO_DECIMAL.has(currency.toUpperCase()) ? 0 : 2;
+}
+__name(currencyExponent, "currencyExponent");
+function toMinorUnits(amount, currency) {
+  const exponent = currencyExponent(currency);
+  const match = /^(-?)(\d+)(?:\.(\d*))?$/.exec(amount.trim());
+  if (!match) throw new Error(`\u91D1\u989D\u683C\u5F0F\u975E\u6CD5\uFF1A${amount}`);
+  const [, sign, whole, fraction = ""] = match;
+  if (fraction.length > exponent && /[^0]/.test(fraction.slice(exponent))) {
+    throw new Error(`${currency} \u6700\u591A\u652F\u6301 ${exponent} \u4F4D\u5C0F\u6570\uFF0C\u6536\u5230 ${amount}`);
+  }
+  const padded = (fraction + "0".repeat(exponent)).slice(0, exponent);
+  const value = Number(`${whole}${padded}`);
+  if (!Number.isSafeInteger(value)) throw new Error(`\u91D1\u989D\u8D85\u51FA\u5B89\u5168\u6574\u6570\u8303\u56F4\uFF1A${amount}`);
+  return sign === "-" ? -value : value;
+}
+__name(toMinorUnits, "toMinorUnits");
+function fromMinorUnits(value, currency) {
+  if (!Number.isInteger(value)) throw new Error(`\u6700\u5C0F\u5355\u4F4D\u5FC5\u987B\u662F\u6574\u6570\uFF1A${value}`);
+  const exponent = currencyExponent(currency);
+  const sign = value < 0 ? "-" : "";
+  const digits = String(Math.abs(value)).padStart(exponent + 1, "0");
+  if (exponent === 0) return `${sign}${digits}`;
+  return `${sign}${digits.slice(0, -exponent)}.${digits.slice(-exponent)}`;
+}
+__name(fromMinorUnits, "fromMinorUnits");
+
+// src/contract/registry.ts
 var import_common = require("@nestjs/common");
 function _ts_decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -65,73 +224,586 @@ function _ts_decorate(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate, "_ts_decorate");
-var PaymentService = class _PaymentService {
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata, "_ts_metadata");
+var PaymentProviderRegistry = class _PaymentProviderRegistry {
   static {
-    __name(this, "PaymentService");
-  }
-  logger = new import_common.Logger(_PaymentService.name);
-  providers = /* @__PURE__ */ new Map();
-  /** 注册支付提供商 */
-  register(provider) {
-    if (this.providers.has(provider.id)) {
-      this.logger.warn(`PaymentProvider "${provider.id}" \u5DF2\u6CE8\u518C\uFF0C\u5C06\u88AB\u8986\u76D6`);
-    }
-    this.providers.set(provider.id, provider);
-    this.logger.log(`PaymentProvider "${provider.id}" (${provider.name}) \u5DF2\u6CE8\u518C`);
-  }
-  /** 注销支付提供商 */
-  unregister(providerId) {
-    const removed = this.providers.delete(providerId);
-    if (removed) {
-      this.logger.log(`PaymentProvider "${providerId}" \u5DF2\u6CE8\u9500`);
-    }
-    return removed;
-  }
-  /** 获取已注册的提供商列表 */
-  listProviders() {
-    return Array.from(this.providers.values());
-  }
-  /** 获取指定提供商 */
-  getProvider(providerId) {
-    const provider = this.providers.get(providerId);
-    if (!provider) {
-      throw new Error(`PaymentProvider "${providerId}" \u672A\u6CE8\u518C\u3002\u5DF2\u6CE8\u518C: [${Array.from(this.providers.keys()).join(", ")}]`);
-    }
-    return provider;
-  }
-  /** 创建支付意图 */
-  async createPaymentIntent(providerId, params) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u521B\u5EFA\u652F\u4ED8\u610F\u56FE: ${params.amount} ${params.currency}`);
-    return provider.createPaymentIntent(params);
-  }
-  /** 确认支付 */
-  async confirmPayment(providerId, intentId) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u786E\u8BA4\u652F\u4ED8: ${intentId}`);
-    return provider.confirmPayment(intentId);
-  }
-  /** 退款 */
-  async refund(providerId, paymentId, amount, reason) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u9000\u6B3E: ${paymentId}, amount=${amount ?? "full"}`);
-    return provider.refund(paymentId, amount, reason);
-  }
-  /** 查询支付状态 */
-  async getPaymentStatus(providerId, intentId) {
-    const provider = this.getProvider(providerId);
-    return provider.getPaymentStatus(intentId);
-  }
-  /** 处理 Webhook */
-  async handleWebhook(providerId, payload, signature) {
-    const provider = this.getProvider(providerId);
-    this.logger.log(`[${providerId}] \u5904\u7406 Webhook`);
-    return provider.handleWebhook(payload, signature);
+    __name(this, "PaymentProviderRegistry");
+  }
+  logger = new import_common.Logger(_PaymentProviderRegistry.name);
+  adapters = /* @__PURE__ */ new Map();
+  constructor(adapters = []) {
+    for (const adapter of adapters) this.register(adapter);
+  }
+  register(adapter) {
+    if (this.adapters.has(adapter.id)) {
+      throw new Error(`\u6E20\u9053 "${adapter.id}" \u5DF2\u6CE8\u518C\uFF1B\u91CD\u590D\u6CE8\u518C\u901A\u5E38\u610F\u5473\u7740\u88C5\u914D\u9519\u8BEF\uFF0C\u4E0D\u4E88\u9759\u9ED8\u8986\u76D6`);
+    }
+    this.adapters.set(adapter.id, adapter);
+    this.logger.log(`\u5DF2\u6CE8\u518C\u652F\u4ED8\u6E20\u9053 "${adapter.id}"`);
+  }
+  has(id) {
+    return this.adapters.has(id);
+  }
+  get(id) {
+    const adapter = this.adapters.get(id);
+    if (!adapter) {
+      throw new Error(`\u6E20\u9053 "${id}" \u672A\u6CE8\u518C\u3002\u5DF2\u6CE8\u518C\uFF1A[${[
+        ...this.adapters.keys()
+      ].join(", ")}]`);
+    }
+    return adapter;
+  }
+  list() {
+    return [
+      ...this.adapters.values()
+    ];
+  }
+  /** 能处理该币种的渠道；"本产品卖不卖这个币种"由上层决定，不在这里过滤。 */
+  listForCurrency(currency) {
+    return this.list().filter((adapter) => adapterSupportsCurrency(adapter, currency));
   }
 };
-PaymentService = _ts_decorate([
-  (0, import_common.Injectable)()
-], PaymentService);
+PaymentProviderRegistry = _ts_decorate([
+  (0, import_common.Injectable)(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    Object
+  ])
+], PaymentProviderRegistry);
+
+// src/contract/adapters/paypal.adapter.ts
+var CAPTURE_INTENT = "CAPTURE";
+var PAY_NOW = "PAY_NOW";
+var NO_SHIPPING = "NO_SHIPPING";
+var PAYPAL_SUPPORTED_CURRENCIES = [
+  "AUD",
+  "BRL",
+  "CAD",
+  "CNY",
+  "CZK",
+  "DKK",
+  "EUR",
+  "HKD",
+  "HUF",
+  "ILS",
+  "JPY",
+  "MYR",
+  "MXN",
+  "TWD",
+  "NZD",
+  "NOK",
+  "PHP",
+  "PLN",
+  "GBP",
+  "RUB",
+  "SGD",
+  "SEK",
+  "CHF",
+  "THB",
+  "USD"
+];
+function observePayPalState(order) {
+  const captures = order.purchaseUnits?.[0]?.payments?.captures ?? [];
+  switch (order.status) {
+    case "CREATED":
+    case "SAVED":
+    case "PAYER_ACTION_REQUIRED":
+      return "created";
+    case "APPROVED":
+      return "authorized";
+    case "VOIDED":
+      return "canceled";
+    case "COMPLETED": {
+      if (captures.some((capture) => capture.status === "COMPLETED")) return "captured";
+      if (captures.some((c) => c.status === "DECLINED" || c.status === "FAILED")) return "failed";
+      return "authorized";
+    }
+    default:
+      return "unknown";
+  }
+}
+__name(observePayPalState, "observePayPalState");
+function createPayPalAdapter(options) {
+  const { transport } = options;
+  const toSession = /* @__PURE__ */ __name((order) => {
+    const unit = order.purchaseUnits?.[0];
+    const approve = order.links?.find((link) => link.rel === "approve")?.href;
+    return {
+      providerRef: order.id ?? "",
+      nextAction: approve ? {
+        kind: "redirect",
+        url: approve
+      } : {
+        kind: "none"
+      },
+      state: observePayPalState(order),
+      money: {
+        amount: unit?.amount?.value ?? "0",
+        currency: unit?.amount?.currencyCode ?? ""
+      },
+      raw: order
+    };
+  }, "toSession");
+  return {
+    id: "paypal",
+    supportedCurrencies: PAYPAL_SUPPORTED_CURRENCIES,
+    async createPayment(input2) {
+      const payment = await transport.createOrder({
+        body: {
+          intent: CAPTURE_INTENT,
+          purchaseUnits: [
+            {
+              referenceId: input2.reference,
+              amount: {
+                currencyCode: input2.money.currency,
+                // 原样透传十进制字符串，不经过 Number
+                value: input2.money.amount
+              },
+              description: input2.description
+            }
+          ],
+          applicationContext: {
+            returnUrl: input2.returnUrl,
+            cancelUrl: input2.cancelUrl,
+            userAction: PAY_NOW,
+            shippingPreference: NO_SHIPPING,
+            brandName: options.brandName
+          }
+        },
+        // 幂等：同一个键重试，PayPal 返回同一笔订单
+        paypalRequestId: input2.idempotencyKey,
+        prefer: "return=representation"
+      });
+      return toSession(payment.raw);
+    },
+    async capture(providerRef, idempotencyKey) {
+      const payment = await transport.captureOrder({
+        id: providerRef,
+        paypalRequestId: idempotencyKey,
+        prefer: "return=representation"
+      });
+      return toSession(payment.raw);
+    },
+    /** 只读。对账会反复调用它，绝不能在这里触发 captureOrder。 */
+    async retrieve(providerRef) {
+      const payment = await transport.getOrder({
+        id: providerRef
+      });
+      return toSession(payment.raw);
+    },
+    async refund(input2) {
+      const refund = await transport.refundCapture(input2.providerRef, {
+        ...input2.money ? {
+          amount: {
+            value: input2.money.amount,
+            currency_code: input2.money.currency
+          }
+        } : {},
+        note_to_payer: input2.reason
+      }, input2.idempotencyKey);
+      return {
+        refundRef: refund.id ?? "",
+        state: refund.status === "COMPLETED" ? "refunded" : "unknown"
+      };
+    },
+    async parseWebhook(request) {
+      if (!options.webhookId) {
+        throw new Error("PayPal webhookId is not configured; refusing to trust the request");
+      }
+      const body = typeof request.rawBody === "string" ? request.rawBody : new TextDecoder().decode(request.rawBody);
+      const valid = await transport.verifyWebhookSignature(body, request.headers, options.webhookId);
+      if (!valid) throw new Error("PayPal webhook signature verification failed");
+      const event = JSON.parse(body);
+      const type = event.event_type ?? "unknown";
+      const providerRef = event.resource?.supplementary_data?.related_ids?.order_id;
+      const state = type === "PAYMENT.CAPTURE.COMPLETED" ? "captured" : type === "PAYMENT.CAPTURE.DENIED" || type === "PAYMENT.CAPTURE.DECLINED" ? "failed" : type === "PAYMENT.CAPTURE.REFUNDED" ? "refunded" : type === "PAYMENT.CAPTURE.REVERSED" ? "refunded" : "unknown";
+      return {
+        type,
+        providerRef,
+        state,
+        raw: event
+      };
+    }
+  };
+}
+__name(createPayPalAdapter, "createPayPalAdapter");
+
+// src/providers/stripe.ts
+var import_node_module = require("module");
+var import_meta = {};
+var requireSdk = (0, import_node_module.createRequire)(typeof __filename === "string" ? __filename : import_meta.url);
+function createStripeClient(secretKey, options) {
+  const StripeSdk = requireSdk("stripe");
+  return new StripeSdk(secretKey, options);
+}
+__name(createStripeClient, "createStripeClient");
+function verifyStripeWebhookEvent(client, payload, signature, webhookSecret) {
+  return client.webhooks.constructEvent(payload, signature, webhookSecret);
+}
+__name(verifyStripeWebhookEvent, "verifyStripeWebhookEvent");
+function stripeResourceId(value) {
+  return typeof value === "string" ? value : value?.id;
+}
+__name(stripeResourceId, "stripeResourceId");
+function observeStripeCheckoutSession(raw) {
+  return {
+    raw,
+    id: raw.id,
+    url: raw.url || void 0,
+    clientReferenceId: raw.client_reference_id || void 0,
+    paymentIntentId: stripeResourceId(raw.payment_intent),
+    subscriptionId: stripeResourceId(raw.subscription),
+    settlement: raw.payment_status === "paid" ? "paid" : raw.status === "expired" ? "unpaid" : "unknown"
+  };
+}
+__name(observeStripeCheckoutSession, "observeStripeCheckoutSession");
+async function createStripeCheckoutSession(client, params, options) {
+  return observeStripeCheckoutSession(options ? await client.checkout.sessions.create(params, options) : await client.checkout.sessions.create(params));
+}
+__name(createStripeCheckoutSession, "createStripeCheckoutSession");
+async function retrieveStripeCheckoutSession(client, id) {
+  return observeStripeCheckoutSession(await client.checkout.sessions.retrieve(id));
+}
+__name(retrieveStripeCheckoutSession, "retrieveStripeCheckoutSession");
+function observeStripePaymentIntent(raw) {
+  const charge = typeof raw.latest_charge === "object" ? raw.latest_charge : null;
+  return {
+    raw,
+    id: raw.id,
+    chargeId: stripeResourceId(raw.latest_charge) ?? null,
+    paymentMethodType: charge?.payment_method_details?.type,
+    failureCode: raw.last_payment_error?.code,
+    failureMessage: raw.last_payment_error?.message,
+    settlement: raw.status === "succeeded" ? "paid" : raw.status === "canceled" ? "unpaid" : "unknown"
+  };
+}
+__name(observeStripePaymentIntent, "observeStripePaymentIntent");
+async function retrieveStripePaymentIntent(client, id, params) {
+  const raw = params ? await client.paymentIntents.retrieve(id, params) : await client.paymentIntents.retrieve(id);
+  return observeStripePaymentIntent(raw);
+}
+__name(retrieveStripePaymentIntent, "retrieveStripePaymentIntent");
+
+// src/contract/adapters/stripe.adapter.ts
+function observeStripeState(session) {
+  if (session.payment_status === "paid" || session.payment_status === "no_payment_required") {
+    return "captured";
+  }
+  if (session.status === "expired") return "canceled";
+  if (session.status === "open") return "created";
+  return "unknown";
+}
+__name(observeStripeState, "observeStripeState");
+function createStripeAdapter(options) {
+  const { client } = options;
+  const toSession = /* @__PURE__ */ __name((raw) => ({
+    providerRef: raw.id,
+    nextAction: raw.url ? {
+      kind: "redirect",
+      url: raw.url
+    } : {
+      kind: "none"
+    },
+    state: observeStripeState(raw),
+    money: {
+      amount: fromMinorUnits(raw.amount_total ?? 0, raw.currency ?? "usd"),
+      currency: (raw.currency ?? "").toUpperCase()
+    },
+    raw
+  }), "toSession");
+  return {
+    id: "stripe",
+    // Stripe 支持的币种远超本契约会用到的范围，不声明限制；
+    // 不受支持的币种由 Stripe 自己拒绝，胡乱穷举一份只会过期。
+    supportedCurrencies: void 0,
+    async createPayment(input2) {
+      const observation = await createStripeCheckoutSession(client, {
+        mode: "payment",
+        line_items: [
+          {
+            price_data: {
+              currency: input2.money.currency.toLowerCase(),
+              product_data: {
+                name: input2.description || input2.reference
+              },
+              unit_amount: toMinorUnits(input2.money.amount, input2.money.currency)
+            },
+            quantity: 1
+          }
+        ],
+        success_url: input2.returnUrl,
+        cancel_url: input2.cancelUrl,
+        client_reference_id: input2.reference,
+        metadata: input2.metadata,
+        ...options.paymentMethodConfiguration ? {
+          payment_method_configuration: options.paymentMethodConfiguration
+        } : {}
+      }, {
+        idempotencyKey: input2.idempotencyKey
+      });
+      return toSession(observation.raw);
+    },
+    /**
+    * Stripe Checkout 默认自动扣款，没有独立的 capture 步骤。
+    * 按契约仍需实现：返回当前真实状态即可，不得伪造成已扣款。
+    */
+    async capture(providerRef) {
+      const observation = await retrieveStripeCheckoutSession(client, providerRef);
+      return toSession(observation.raw);
+    },
+    async retrieve(providerRef) {
+      const observation = await retrieveStripeCheckoutSession(client, providerRef);
+      return toSession(observation.raw);
+    },
+    async refund(input2) {
+      const session = await retrieveStripeCheckoutSession(client, input2.providerRef);
+      const paymentIntent = session.paymentIntentId;
+      if (!paymentIntent) throw new Error("\u8BE5 Checkout \u4F1A\u8BDD\u6CA1\u6709\u53EF\u9000\u6B3E\u7684 PaymentIntent");
+      const refund = await client.refunds.create({
+        payment_intent: paymentIntent,
+        ...input2.money ? {
+          amount: toMinorUnits(input2.money.amount, input2.money.currency)
+        } : {}
+      }, {
+        idempotencyKey: input2.idempotencyKey
+      });
+      return {
+        refundRef: refund.id,
+        state: refund.status === "succeeded" ? "refunded" : "unknown"
+      };
+    },
+    async parseWebhook(request) {
+      if (!options.webhookSecret) {
+        throw new Error("Stripe webhookSecret is not configured; refusing to trust the request");
+      }
+      const signature = request.headers["stripe-signature"];
+      if (!signature) throw new Error("Stripe webhook is missing the stripe-signature header");
+      const event = verifyStripeWebhookEvent(client, typeof request.rawBody === "string" ? request.rawBody : Buffer.from(request.rawBody), signature, options.webhookSecret);
+      const object = event.data.object;
+      const state = event.type === "checkout.session.completed" ? observeStripeState(event.data.object) : event.type === "checkout.session.expired" ? "canceled" : event.type === "charge.refunded" ? "refunded" : "unknown";
+      return {
+        type: event.type,
+        providerRef: object.id,
+        state,
+        raw: event
+      };
+    }
+  };
+}
+__name(createStripeAdapter, "createStripeAdapter");
+
+// src/contract/contract-suite.ts
+var MUTATING = [
+  "capture",
+  "refund",
+  "cancel"
+];
+async function checkPaymentAdapterContract(probe) {
+  const checks = [];
+  const captureNames = probe.captureCallNames ?? MUTATING;
+  const run = /* @__PURE__ */ __name(async (name, fn) => {
+    try {
+      const detail = await fn();
+      checks.push({
+        name,
+        ok: detail === void 0,
+        detail
+      });
+    } catch (error) {
+      checks.push({
+        name,
+        ok: false,
+        detail: `\u629B\u51FA\u5F02\u5E38\uFF1A${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }, "run");
+  await run("retrieve \u5FC5\u987B\u53EA\u8BFB", async () => {
+    const { adapter, mutatingCalls } = probe.create();
+    const created = await adapter.createPayment(input(probe.supportedCurrency));
+    const before = mutatingCalls().filter((c) => captureNames.includes(c)).length;
+    await adapter.retrieve(created.providerRef);
+    const after = mutatingCalls().filter((c) => captureNames.includes(c)).length;
+    return after > before ? `retrieve \u89E6\u53D1\u4E86\u5199\u64CD\u4F5C\uFF1A${mutatingCalls().join(", ")}` : void 0;
+  });
+  await run("\u76F8\u540C\u5E42\u7B49\u952E\u4E0D\u5F97\u4EA7\u751F\u7B2C\u4E8C\u7B14\u652F\u4ED8", async () => {
+    const { adapter } = probe.create();
+    const key = "contract-idempotency-key";
+    const first = await adapter.createPayment(input(probe.supportedCurrency, key));
+    const second = await adapter.createPayment(input(probe.supportedCurrency, key));
+    return first.providerRef === second.providerRef ? void 0 : `\u4EA7\u751F\u4E86\u4E24\u7B14\uFF1A${first.providerRef} \u4E0E ${second.providerRef}`;
+  });
+  await run("\u9A8C\u7B7E\u5931\u8D25\u5FC5\u987B\u629B\u9519\u800C\u975E\u8FD4\u56DE\u672A\u77E5\u4E8B\u4EF6", async () => {
+    const { adapter } = probe.create();
+    try {
+      const observation = await adapter.parseWebhook(probe.invalidWebhook);
+      return `\u672A\u629B\u9519\uFF0C\u8FD4\u56DE\u4E86 ${JSON.stringify(observation.type)}`;
+    } catch {
+      return void 0;
+    }
+  });
+  await run("\u91D1\u989D\u5FC5\u987B\u4EE5\u5341\u8FDB\u5236\u5B57\u7B26\u4E32\u539F\u6837\u900F\u4F20", async () => {
+    const { adapter } = probe.create();
+    const amount = "29.00";
+    const created = await adapter.createPayment({
+      ...input(probe.supportedCurrency),
+      money: {
+        amount,
+        currency: probe.supportedCurrency
+      }
+    });
+    return created.money.amount === amount ? void 0 : `\u671F\u671B "${amount}"\uFF0C\u5B9E\u9645 ${JSON.stringify(created.money.amount)}`;
+  });
+  await run("\u5728\u9014\u652F\u4ED8\u4E0D\u5F97\u88AB\u5224\u4E3A failed", async () => {
+    const { adapter } = probe.create();
+    const created = await adapter.createPayment(input(probe.supportedCurrency));
+    const retrieved = await adapter.retrieve(created.providerRef);
+    return retrieved.state === "failed" ? "\u521A\u521B\u5EFA\u3001\u7528\u6237\u5C1A\u672A\u64CD\u4F5C\u7684\u652F\u4ED8\u88AB\u5224\u4E3A failed" : void 0;
+  });
+  await run("nextAction \u5FC5\u987B\u662F\u5951\u7EA6\u5185\u7684 kind", async () => {
+    const { adapter } = probe.create();
+    const created = await adapter.createPayment(input(probe.supportedCurrency));
+    const known = [
+      "redirect",
+      "qrcode",
+      "form_post",
+      "sdk_params",
+      "none"
+    ];
+    return known.includes(created.nextAction.kind) ? void 0 : `\u672A\u77E5 kind\uFF1A${created.nextAction.kind}`;
+  });
+  await run("\u5E01\u79CD\u80FD\u529B\u58F0\u660E\u4E0E\u5B9E\u9645\u4E00\u81F4", async () => {
+    const { adapter } = probe.create();
+    if (!adapter.supportedCurrencies) return void 0;
+    if (!adapterSupportsCurrency(adapter, probe.supportedCurrency)) {
+      return `\u58F0\u660E\u4E0D\u652F\u6301 ${probe.supportedCurrency}\uFF0C\u4F46\u63A2\u9488\u79F0\u5176\u652F\u6301`;
+    }
+    if (probe.unsupportedCurrency && adapterSupportsCurrency(adapter, probe.unsupportedCurrency)) {
+      return `\u58F0\u660E\u652F\u6301 ${probe.unsupportedCurrency}\uFF0C\u4F46\u63A2\u9488\u79F0\u5176\u4E0D\u652F\u6301`;
+    }
+    return void 0;
+  });
+  return checks;
+}
+__name(checkPaymentAdapterContract, "checkPaymentAdapterContract");
+function input(currency, idempotencyKey = "contract-default-key") {
+  return {
+    reference: "contract-order",
+    money: {
+      amount: "10.00",
+      currency
+    },
+    idempotencyKey
+  };
+}
+__name(input, "input");
+
+// src/contract/fake-adapter.ts
+function createFakeAdapter(options = {}) {
+  const defects = options.defects ?? {};
+  const payments = /* @__PURE__ */ new Map();
+  const byIdempotencyKey = /* @__PURE__ */ new Map();
+  const mutatingCalls = [];
+  let counter = 0;
+  const adapter = {
+    id: options.id ?? "fake",
+    supportedCurrencies: options.supportedCurrencies,
+    async createPayment(input2) {
+      mutatingCalls.push("createPayment");
+      const existing = defects.ignoreIdempotency ? void 0 : byIdempotencyKey.get(input2.idempotencyKey);
+      if (existing) {
+        const payment2 = payments.get(existing);
+        return session(payment2);
+      }
+      const ref = `fake_${++counter}`;
+      const amount = defects.mangleAmount ? String(Number(input2.money.amount)) : input2.money.amount;
+      const payment = {
+        ref,
+        state: "created",
+        amount,
+        currency: input2.money.currency
+      };
+      payments.set(ref, payment);
+      byIdempotencyKey.set(input2.idempotencyKey, ref);
+      return session(payment);
+    },
+    async capture(providerRef) {
+      mutatingCalls.push("capture");
+      const payment = expect(providerRef);
+      payment.state = "captured";
+      return session(payment);
+    },
+    async retrieve(providerRef) {
+      if (defects.retrieveCaptures) {
+        mutatingCalls.push("capture");
+        expect(providerRef).state = "captured";
+      }
+      const payment = expect(providerRef);
+      if (defects.guessesPendingAsFailed && payment.state === "created") {
+        return {
+          ...session(payment),
+          state: "failed"
+        };
+      }
+      return session(payment);
+    },
+    async refund(input2) {
+      mutatingCalls.push("refund");
+      const payment = expect(input2.providerRef);
+      payment.state = input2.money ? "partially_refunded" : "refunded";
+      return {
+        refundRef: `refund_${payment.ref}`,
+        state: payment.state
+      };
+    },
+    async parseWebhook(request) {
+      const valid = request.headers["x-fake-signature"] === "valid";
+      if (!valid && !defects.acceptsBadSignature) {
+        throw new Error("webhook signature verification failed");
+      }
+      const ref = request.headers["x-fake-ref"];
+      return {
+        type: "fake.payment.updated",
+        providerRef: ref,
+        state: ref && payments.has(ref) ? payments.get(ref).state : "unknown",
+        raw: {}
+      };
+    }
+  };
+  function expect(ref) {
+    const payment = payments.get(ref);
+    if (!payment) throw new Error(`unknown payment ${ref}`);
+    return payment;
+  }
+  __name(expect, "expect");
+  function session(payment) {
+    return {
+      providerRef: payment.ref,
+      nextAction: {
+        kind: "redirect",
+        url: `https://fake.test/pay/${payment.ref}`
+      },
+      state: payment.state,
+      money: {
+        amount: payment.amount,
+        currency: payment.currency
+      },
+      raw: {}
+    };
+  }
+  __name(session, "session");
+  return {
+    adapter,
+    mutatingCalls: /* @__PURE__ */ __name(() => [
+      ...mutatingCalls
+    ], "mutatingCalls")
+  };
+}
+__name(createFakeAdapter, "createFakeAdapter");
 
 // src/order.service.ts
 var import_common2 = require("@nestjs/common");
@@ -191,12 +863,12 @@ function _ts_decorate2(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate2, "_ts_decorate");
-function _ts_metadata(metadataKey, metadataValue) {
+function _ts_metadata2(metadataKey, metadataValue) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
     return Reflect.metadata(metadataKey, metadataValue);
   }
 }
-__name(_ts_metadata, "_ts_metadata");
+__name(_ts_metadata2, "_ts_metadata");
 function _ts_param(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
@@ -217,10 +889,10 @@ var OrderService = class {
   static {
     __name(this, "OrderService");
   }
-  paymentService;
+  providers;
   orders;
-  constructor(paymentService, orders) {
-    this.paymentService = paymentService;
+  constructor(providers, orders) {
+    this.providers = providers;
     this.orders = orders;
     if (!orders) throw new Error("Order persistence must be configured");
   }
@@ -237,8 +909,8 @@ var OrderService = class {
       data: {
         id: params.orderId,
         providerId: params.providerId,
-        amount: params.payment.amount,
-        currency: params.payment.currency,
+        amount: params.payment.money.amount,
+        currency: params.payment.money.currency,
         metadata: params.payment.metadata,
         status: "created",
         createdAt: now,
@@ -248,68 +920,99 @@ var OrderService = class {
     return this.initiatePayment(order, params.payment);
   }
   async initiatePayment(order, payment) {
-    const intent = await this.paymentService.createPaymentIntent(order.providerId, payment);
+    const session = await this.providers.get(order.providerId).createPayment(payment);
     await this.transition(order.id, [
       "created"
     ], "paying", {
-      paymentIntentId: intent.id
+      paymentIntentId: session.providerRef
     });
     return this.getOrder(order.id);
   }
-  async confirmOrder(orderId) {
+  /**
+  * 扣款。幂等键由调用方给出——同一笔订单重试必须复用同一个键，否则渠道会认为是新支付。
+  * 判定不了的结果保持 confirming，交由只读对账解决，绝不在这里重复扣款。
+  */
+  async confirmOrder(orderId, idempotencyKey) {
     const order = await this.getOrder(orderId);
     if (!order.paymentIntentId) throw new Error(`\u8BA2\u5355 "${orderId}" \u7F3A\u5C11 paymentIntentId`);
     await this.transition(orderId, [
       "paying"
     ], "confirming");
-    const result = await this.paymentService.confirmPayment(order.providerId, order.paymentIntentId);
-    if (result.status === "succeeded") {
+    const session = await this.providers.get(order.providerId).capture(order.paymentIntentId, idempotencyKey);
+    await this.applySettlement(orderId, "confirming", session.state, session.providerRef);
+    return session;
+  }
+  /**
+  * 把渠道观察到的结算状态落到订单上。
+  * 迁移是否允许由 reconcile() 统一裁决，保证所有渠道遵守同一套安全性质
+  * （unknown 不覆盖已知状态、已收款不被迟到的失败回调回退）。
+  */
+  async applySettlement(orderId, from, observed, paymentRef) {
+    const current = from === "paid" ? "captured" : from === "refunded" ? "refunded" : "created";
+    const decision = reconcile(current, observed);
+    if (!decision.changed) return;
+    if (decision.next === "captured") {
       await this.transition(orderId, [
-        "confirming"
+        from
       ], "paid", {
-        paymentId: result.id,
-        paidAt: result.paidAt ?? /* @__PURE__ */ new Date()
+        paymentId: paymentRef,
+        paidAt: /* @__PURE__ */ new Date()
       });
-    } else if (result.status === "failed" || result.status === "cancelled") {
+    } else if (decision.next === "failed" || decision.next === "canceled") {
       await this.transition(orderId, [
-        "confirming"
+        from
       ], "failed");
-    } else if (result.status === "refunded") {
+    } else if (decision.next === "refunded" || decision.next === "partially_refunded") {
       await this.transition(orderId, [
-        "confirming"
-      ], "refunded");
+        from
+      ], "refunded", {
+        refundedAt: /* @__PURE__ */ new Date()
+      });
     }
-    return result;
   }
-  async refundOrder(orderId, amount, reason) {
+  async refundOrder(orderId, idempotencyKey, options = {}) {
     const order = await this.getOrder(orderId);
     if (!order.paymentId) throw new Error(`\u8BA2\u5355 "${orderId}" \u7F3A\u5C11 paymentId`);
     await this.transition(orderId, [
       "paid"
     ], "refunding");
-    const result = await this.paymentService.refund(order.providerId, order.paymentId, amount, reason);
-    if (result.status === "succeeded") {
+    const result = await this.providers.get(order.providerId).refund({
+      providerRef: order.paymentId,
+      money: options.money,
+      reason: options.reason,
+      idempotencyKey
+    });
+    if (result.state === "refunded") {
       await this.transition(orderId, [
         "refunding"
       ], "refunded", {
         refundedAt: /* @__PURE__ */ new Date()
       });
-    } else if (result.status === "failed") {
+    } else if (result.state === "failed") {
       await this.transition(orderId, [
         "refunding"
       ], "paid");
     }
     return result;
   }
-  async retryOrder(orderId) {
+  /**
+  * 重试失败订单。
+  * idempotencyKey 必须与上一次不同：沿用旧键会让渠道原样返回那笔已失败的支付，
+  * 看起来"重试了"其实什么都没发生。
+  */
+  async retryOrder(orderId, idempotencyKey) {
     const order = await this.getOrder(orderId);
     await this.transition(orderId, [
       "failed"
     ], "created");
     return this.initiatePayment(order, {
-      amount: order.amount,
-      currency: order.currency,
-      metadata: order.metadata
+      reference: order.id,
+      money: {
+        amount: order.amount,
+        currency: order.currency
+      },
+      metadata: order.metadata,
+      idempotencyKey
     });
   }
   async cancelOrder(orderId) {
@@ -348,9 +1051,9 @@ var OrderService = class {
 OrderService = _ts_decorate2([
   (0, import_common2.Injectable)(),
   _ts_param(1, (0, import_common2.Inject)(ORDER_PERSISTENCE)),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof PaymentService === "undefined" ? Object : PaymentService,
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof PaymentProviderRegistry === "undefined" ? Object : PaymentProviderRegistry,
     typeof OrderPersistence === "undefined" ? Object : OrderPersistence
   ])
 ], OrderService);
@@ -384,12 +1087,12 @@ function _ts_decorate3(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate3, "_ts_decorate");
-function _ts_metadata2(metadataKey, metadataValue) {
+function _ts_metadata3(metadataKey, metadataValue) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
     return Reflect.metadata(metadataKey, metadataValue);
   }
 }
-__name(_ts_metadata2, "_ts_metadata");
+__name(_ts_metadata3, "_ts_metadata");
 function _ts_param2(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
@@ -500,10 +1203,11 @@ var PaymentRecoveryService = class _PaymentRecoveryService {
     }
   }
   /**
-  * 重试失败订单 — 将 failed → created 并重新发起支付
+  * 重试失败订单 — 将 failed → created 并重新发起支付。
+  * 幂等键由调用方给出且必须与上次不同，否则渠道会原样返回那笔已失败的支付。
   */
-  retryOrder(orderId) {
-    return this.orderService.retryOrder(orderId);
+  retryOrder(orderId, idempotencyKey) {
+    return this.orderService.retryOrder(orderId, idempotencyKey);
   }
   getRecoveryAttempts(orderId) {
     if (!this.attempts) throw new Error("Recovery attempt persistence must be configured");
@@ -526,8 +1230,8 @@ PaymentRecoveryService = _ts_decorate3([
   _ts_param2(4, (0, import_common3.Optional)()),
   _ts_param2(4, (0, import_common3.Inject)(RECOVERY_URL_GENERATOR)),
   _ts_param2(5, (0, import_common3.Optional)()),
-  _ts_metadata2("design:type", Function),
-  _ts_metadata2("design:paramtypes", [
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
     typeof OrderService === "undefined" ? Object : OrderService,
     Object,
     typeof RecoveryMailSender === "undefined" ? Object : RecoveryMailSender,
@@ -590,24 +1294,20 @@ function configuredProviders() {
       useFactory: /* @__PURE__ */ __name((options) => options.recoveryAttempts ?? null, "useFactory")
     },
     {
-      provide: PaymentService,
+      provide: PaymentProviderRegistry,
       inject: [
         PAYMENT_OPTIONS
       ],
-      useFactory: /* @__PURE__ */ __name((options) => {
-        const service = new PaymentService();
-        for (const provider of options.providers ?? []) service.register(provider);
-        return service;
-      }, "useFactory")
+      useFactory: /* @__PURE__ */ __name((options) => new PaymentProviderRegistry(options.providers ?? []), "useFactory")
     },
     OrderService,
     PaymentRecoveryService,
     {
       provide: PAYMENT_PROVIDERS,
       inject: [
-        PaymentService
+        PaymentProviderRegistry
       ],
-      useFactory: /* @__PURE__ */ __name((service) => service.listProviders(), "useFactory")
+      useFactory: /* @__PURE__ */ __name((registry) => registry.list(), "useFactory")
     }
   ];
 }
@@ -628,7 +1328,7 @@ var ZuckerPaymentModule = class _ZuckerPaymentModule {
         ...configuredProviders()
       ],
       exports: [
-        PaymentService,
+        PaymentProviderRegistry,
         OrderService,
         PaymentRecoveryService
       ]
@@ -648,7 +1348,7 @@ var ZuckerPaymentModule = class _ZuckerPaymentModule {
         ...configuredProviders()
       ],
       exports: [
-        PaymentService,
+        PaymentProviderRegistry,
         OrderService,
         PaymentRecoveryService
       ]
@@ -660,62 +1360,6 @@ ZuckerPaymentModule = _ts_decorate4([
   (0, import_common4.Module)({})
 ], ZuckerPaymentModule);
 
-// src/providers/stripe.ts
-var import_node_module = require("module");
-var import_meta = {};
-var requireSdk = (0, import_node_module.createRequire)(typeof __filename === "string" ? __filename : import_meta.url);
-function createStripeClient(secretKey, options) {
-  const StripeSdk = requireSdk("stripe");
-  return new StripeSdk(secretKey, options);
-}
-__name(createStripeClient, "createStripeClient");
-function verifyStripeWebhookEvent(client, payload, signature, webhookSecret) {
-  return client.webhooks.constructEvent(payload, signature, webhookSecret);
-}
-__name(verifyStripeWebhookEvent, "verifyStripeWebhookEvent");
-function stripeResourceId(value) {
-  return typeof value === "string" ? value : value?.id;
-}
-__name(stripeResourceId, "stripeResourceId");
-function observeStripeCheckoutSession(raw) {
-  return {
-    raw,
-    id: raw.id,
-    url: raw.url || void 0,
-    clientReferenceId: raw.client_reference_id || void 0,
-    paymentIntentId: stripeResourceId(raw.payment_intent),
-    subscriptionId: stripeResourceId(raw.subscription),
-    settlement: raw.payment_status === "paid" ? "paid" : raw.status === "expired" ? "unpaid" : "unknown"
-  };
-}
-__name(observeStripeCheckoutSession, "observeStripeCheckoutSession");
-async function createStripeCheckoutSession(client, params) {
-  return observeStripeCheckoutSession(await client.checkout.sessions.create(params));
-}
-__name(createStripeCheckoutSession, "createStripeCheckoutSession");
-async function retrieveStripeCheckoutSession(client, id) {
-  return observeStripeCheckoutSession(await client.checkout.sessions.retrieve(id));
-}
-__name(retrieveStripeCheckoutSession, "retrieveStripeCheckoutSession");
-function observeStripePaymentIntent(raw) {
-  const charge = typeof raw.latest_charge === "object" ? raw.latest_charge : null;
-  return {
-    raw,
-    id: raw.id,
-    chargeId: stripeResourceId(raw.latest_charge) ?? null,
-    paymentMethodType: charge?.payment_method_details?.type,
-    failureCode: raw.last_payment_error?.code,
-    failureMessage: raw.last_payment_error?.message,
-    settlement: raw.status === "succeeded" ? "paid" : raw.status === "canceled" ? "unpaid" : "unknown"
-  };
-}
-__name(observeStripePaymentIntent, "observeStripePaymentIntent");
-async function retrieveStripePaymentIntent(client, id, params) {
-  const raw = params ? await client.paymentIntents.retrieve(id, params) : await client.paymentIntents.retrieve(id);
-  return observeStripePaymentIntent(raw);
-}
-__name(retrieveStripePaymentIntent, "retrieveStripePaymentIntent");
-
 // src/providers/paypal.ts
 var import_node_module2 = require("module");
 var import_meta2 = {};
@@ -730,6 +1374,22 @@ function observePayPalOrder(raw) {
   };
 }
 __name(observePayPalOrder, "observePayPalOrder");
+function captureLinkId(resource) {
+  if (!Array.isArray(resource.links)) return void 0;
+  for (const value of resource.links) {
+    const link = asRecord(value);
+    if (link?.rel !== "up" || typeof link.href !== "string") continue;
+    try {
+      const url = new URL(link.href);
+      if (url.protocol !== "https:" || !/^api(?:-m)?(?:\.sandbox)?\.paypal\.com$/.test(url.hostname)) continue;
+      const match = /^\/v2\/payments\/captures\/([A-Za-z0-9_-]+)$/.exec(url.pathname);
+      if (match) return match[1];
+    } catch {
+    }
+  }
+  return void 0;
+}
+__name(captureLinkId, "captureLinkId");
 function asRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
@@ -761,6 +1421,42 @@ function decodePayPalWebhookEvent(payload) {
   };
 }
 __name(decodePayPalWebhookEvent, "decodePayPalWebhookEvent");
+function decodePayPalMoneyReturnedEvent(payload) {
+  const raw = asRecord(JSON.parse(payload));
+  if (!raw || typeof raw.event_type !== "string") throw new Error("Invalid PayPal webhook event");
+  const type = raw.event_type;
+  if (type === "PAYMENT.CAPTURE.REFUNDED" || type === "PAYMENT.CAPTURE.REVERSED") {
+    const resource = asRecord(raw.resource);
+    const amount = asRecord(resource?.amount);
+    const related = asRecord(asRecord(resource?.supplementary_data)?.related_ids);
+    const reversal = type === "PAYMENT.CAPTURE.REVERSED";
+    if (!resource || typeof resource.id !== "string" || !resource.id || typeof amount?.value !== "string" || !/^\d+(?:\.\d{1,2})?$/.test(amount.value) || typeof amount.currency_code !== "string" || !/^[A-Z]{3}$/.test(amount.currency_code)) {
+      throw new Error("Invalid PayPal money-returned event");
+    }
+    const status = reversal ? "COMPLETED" : resource.status;
+    if (status !== "PENDING" && status !== "COMPLETED" && status !== "FAILED" && status !== "CANCELLED") {
+      throw new Error("Unknown PayPal refund status");
+    }
+    const captureId = reversal ? resource.id : typeof related?.capture_id === "string" ? related.capture_id : captureLinkId(resource);
+    const orderId = typeof related?.order_id === "string" ? related.order_id : void 0;
+    if (!captureId && !orderId) throw new Error("PayPal refund event has no capture or order identity");
+    return {
+      raw,
+      type,
+      kind: reversal ? "capture-reversed" : "capture-refunded",
+      returned: {
+        id: reversal ? `reversal:${resource.id}` : resource.id,
+        captureId,
+        orderId,
+        amount: amount.value,
+        currency: amount.currency_code,
+        status
+      }
+    };
+  }
+  return null;
+}
+__name(decodePayPalMoneyReturnedEvent, "decodePayPalMoneyReturnedEvent");
 var PayPalPaymentTransport = class {
   static {
     __name(this, "PayPalPaymentTransport");
@@ -793,17 +1489,17 @@ var PayPalPaymentTransport = class {
     this.baseUrl = options.mode === "live" ? "https://api.paypal.com" : "https://api.sandbox.paypal.com";
     this.fetcher = options.fetcher ?? fetch;
   }
-  async createOrder(input) {
-    const { result } = await this.orders.createOrder(input);
+  async createOrder(input2) {
+    const { result } = await this.orders.createOrder(input2);
     return observePayPalOrder(result);
   }
   /** An explicit capture command; never invoked by getOrder or status observation. */
-  async captureOrder(input) {
-    const { result } = await this.orders.captureOrder(input);
+  async captureOrder(input2) {
+    const { result } = await this.orders.captureOrder(input2);
     return observePayPalOrder(result);
   }
-  async getOrder(input) {
-    const { result } = await this.orders.getOrder(input);
+  async getOrder(input2) {
+    const { result } = await this.orders.getOrder(input2);
     return observePayPalOrder(result);
   }
   async getAccessToken() {
@@ -856,18 +1552,21 @@ var PayPalPaymentTransport = class {
       return false;
     }
   }
-  async refundCapture(captureId, request) {
+  async refundCapture(captureId, request, requestId) {
     const accessToken = await this.getAccessToken();
     const response = await this.fetcher(`${this.baseUrl}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${accessToken}`
+        Authorization: `Bearer ${accessToken}`,
+        ...requestId ? {
+          "PayPal-Request-Id": requestId
+        } : {}
       },
       body: JSON.stringify(request)
     });
     const result = await response.json();
-    if (!response.ok && result.status === "COMPLETED") throw new Error(`PayPal refund request failed (${response.status})`);
+    if (!response.ok) throw new Error(`PayPal refund request failed (${response.status})`);
     return result;
   }
 };
@@ -878,24 +1577,40 @@ var PayPalPaymentTransport = class {
   OrderNotFoundError,
   OrderService,
   PAYMENT_PROVIDERS,
+  PAYPAL_SUPPORTED_CURRENCIES,
   PayPalPaymentTransport,
   PaymentEvents,
+  PaymentProviderRegistry,
   PaymentRecoveryService,
-  PaymentService,
   RECOVERY_ATTEMPT_STORE,
   RECOVERY_MAIL_SENDER,
   RECOVERY_URL_GENERATOR,
   RECOVERY_USER_LOOKUP,
+  SETTLEMENT_STATES,
   ZuckerPaymentModule,
+  adapterSupportsCurrency,
+  checkPaymentAdapterContract,
+  createFakeAdapter,
+  createPayPalAdapter,
+  createStripeAdapter,
   createStripeCheckoutSession,
   createStripeClient,
+  currencyExponent,
+  decodePayPalMoneyReturnedEvent,
   decodePayPalWebhookEvent,
   friendlyErrorReason,
+  fromMinorUnits,
+  isMoneyMoved,
+  isTerminal,
   observePayPalOrder,
+  observePayPalState,
   observeStripeCheckoutSession,
   observeStripePaymentIntent,
+  observeStripeState,
+  reconcile,
   retrieveStripeCheckoutSession,
   retrieveStripePaymentIntent,
   stripeResourceId,
+  toMinorUnits,
   verifyStripeWebhookEvent
 });