@zucker-framework/payment 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -1,121 +1,425 @@
+import * as _paypal_paypal_server_sdk from '@paypal/paypal-server-sdk';
+import { OrdersController, Order as Order$1 } from '@paypal/paypal-server-sdk';
+import Stripe from 'stripe';
 import { ModelOperations } from '@zucker-framework/core';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { Type, DynamicModule, InjectionToken } from '@nestjs/common';
-import Stripe from 'stripe';
-import * as _paypal_paypal_server_sdk from '@paypal/paypal-server-sdk';
-import { OrdersController } from '@paypal/paypal-server-sdk';
 
 /**
- * 支付网关接口 — 不绑定任何具体支付商。
- * 用户通过注入 Stripe/PayPal/微信支付适配器来使用。
+ * 结算状态的中立模型与迁移规则。
+ *
+ * 这是多渠道支付里最容易出错、也最值得统一的一层：各渠道的状态名不同
+ * （Stripe 的 requires_capture / succeeded、PayPal 的 APPROVED / COMPLETED、
+ * 微信的 NOTPAY / SUCCESS / CLOSED），但"钱有没有动"的语义是共通的。
+ *
+ * 适配器只负责把供应商状态映射成这里的 SettlementState，不做任何持久化决策；
+ * 迁移是否允许由 reconcile() 统一裁决，保证所有渠道遵守同一套安全性质。
  */
-interface PaymentProvider {
-    id: string;
-    name: string;
-    /** 创建支付意图/订单 */
-    createPaymentIntent(params: CreatePaymentParams): Promise<PaymentIntent>;
-    /** 确认支付 */
-    confirmPayment(intentId: string): Promise<PaymentResult>;
-    /** 退款 */
-    refund(paymentId: string, amount?: number, reason?: string): Promise<RefundResult>;
-    /** 查询支付状态 */
-    getPaymentStatus(intentId: string): Promise<PaymentStatus>;
-    /** 处理 Webhook */
-    handleWebhook(payload: unknown, signature: string): Promise<WebhookEvent>;
-}
-interface CreatePaymentParams {
-    amount: number;
+declare const SETTLEMENT_STATES: readonly ["created", "authorized", "captured", "refunded", "partially_refunded", "failed", "canceled", "unknown"];
+type SettlementState = (typeof SETTLEMENT_STATES)[number];
+declare function isMoneyMoved(state: SettlementState): boolean;
+declare function isTerminal(state: SettlementState): boolean;
+/** reconcile 的裁决结果，供调用方决定是否写库、是否告警。 */
+interface SettlementDecision {
+    /** 应当持久化的状态；与 current 相同表示不必写库 */
+    next: SettlementState;
+    /** 是否发生了实际变化 */
+    changed: boolean;
+    /**
+     * 观察到的状态被拒绝采纳时给出原因，调用方应据此告警而不是静默丢弃。
+     * 例如已扣款的订单收到 failed 通知——这通常意味着两边对不上，需要人工核对。
+     */
+    rejected?: "money-already-moved" | "already-terminal" | "not-observable";
+}
+/**
+ * 依据当前持久化状态与本次观察到的状态，裁决应当落库的状态。
+ *
+ * 安全性质（由测试锁定）：
+ *   1. unknown 永不覆盖任何已知状态——查不到不等于没付。
+ *   2. 钱已移动过的状态不会被 failed / canceled 回退——迟到的失败回调不能抹掉已收款。
+ *   3. 终态不会被非终态覆盖——已退款的订单不会因为一条旧的 captured 回调变回已付。
+ *   4. captured → partially_refunded → refunded 单向推进，不可逆。
+ *   5. 幂等：同样的观察重复裁决，结果不变且 changed=false。
+ */
+declare function reconcile(current: SettlementState, observed: SettlementState): SettlementDecision;
+
+/**
+ * 多渠道支付的中立契约。
+ *
+ * 取代 ../payment.interface.ts 里那份未经任何适配器验证的 PaymentProvider。
+ * 形状取自 CNIPA 已跑通 Stripe + PayPal 的 PaymentGateway，并按 Medusa
+ * AbstractPaymentProcessor 的生命周期补齐授权/扣款分离，同时预留微信、
+ * 支付宝这类非跳转渠道所需的结构。
+ */
+/**
+ * 金额。
+ *
+ * 刻意用十进制字符串而不是 number：
+ *   - 旧 PaymentProvider 用 `number` + 注释"最小单位（分）"，CNIPA 用 Decimal 元，
+ *     两套单位并存迟早在某个边界上错一位。
+ *   - 浮点数表示钱本身就是错的。
+ *   - JPY/HUF/TWD 无小数位，cents 模型对它们是特例；字符串对所有币种一致。
+ * 适配器负责在边界上转成各自 SDK 需要的形式。
+ */
+interface Money {
+    /** 十进制字符串，如 "29.00"；不接受 number */
+    amount: string;
+    /** ISO 4217，大写 */
     currency: string;
+}
+/**
+ * 用户需要执行的下一步动作。
+ *
+ * 不能简化成 `redirectUrl?: string`——微信 Native 下单返回的是
+ * `weixin://wxpay/bizpayurl?pr=...`，是要渲染成二维码给用户扫的字符串，
+ * 不是能 location.assign 过去的地址；支付宝 PC 常返回需自动提交的表单。
+ * 用判别联合表达，调用方按 kind 分派，新增渠道不必改已有分支。
+ */
+type PaymentNextAction = {
+    kind: "redirect";
+    url: string;
+} | {
+    kind: "qrcode";
+    value: string;
+} | {
+    kind: "form_post";
+    action: string;
+    fields: Record<string, string>;
+} | {
+    kind: "sdk_params";
+    params: Record<string, unknown>;
+} | {
+    kind: "none";
+};
+interface PaymentSession {
+    /** 供应商侧的支付标识，后续 capture / retrieve / refund 都用它 */
+    providerRef: string;
+    nextAction: PaymentNextAction;
+    state: SettlementState;
+    /**
+     * 供应商侧记录的金额。
+     * 放在契约里而不是让调用方去 raw 里翻：金额是每个渠道都必须如实回传的字段，
+     * 调用方要拿它和本地订单核对，不该为此了解某个供应商的响应结构。
+     */
+    money: Money;
+    /** 供应商原始响应，供排查与对账留痕；不参与业务判断 */
+    raw?: unknown;
+}
+interface CreatePaymentInput {
+    /** 调用方的订单标识，会回传到供应商以便双向核对 */
+    reference: string;
+    money: Money;
     description?: string;
-    metadata?: Record<string, string>;
-    customerId?: string;
+    /** 付款完成/取消后的回跳地址；不适用的渠道可忽略 */
     returnUrl?: string;
     cancelUrl?: string;
+    /**
+     * 幂等键。同一个键重试必须返回同一笔支付，不得产生第二笔。
+     * 旧接口完全没有这个概念，重试即重复下单。
+     */
+    idempotencyKey: string;
+    metadata?: Record<string, string>;
 }
-interface PaymentIntent {
-    id: string;
-    clientSecret?: string;
-    status: PaymentStatus;
-    amount: number;
-    currency: string;
-    redirectUrl?: string;
+/**
+ * Webhook 原始请求。
+ *
+ * 必须同时给出原始字节与**全部**请求头：PayPal 验签需要 5 个头
+ * （paypal-transmission-id/time/sig、paypal-cert-url、paypal-auth-algo），
+ * 旧接口的 `signature: string` 结构上装不下；微信 v3 同样需要多个头。
+ * 验签必须针对原始字节，序列化过一轮再验会因键序/数字规范化失败。
+ */
+interface WebhookRequest {
+    rawBody: Uint8Array | string;
+    headers: Record<string, string>;
 }
-type PaymentStatus = 'pending' | 'processing' | 'succeeded' | 'failed' | 'cancelled' | 'refunded';
-interface PaymentResult {
-    id: string;
-    status: PaymentStatus;
-    amount: number;
-    currency: string;
-    paidAt?: Date;
+interface WebhookObservation {
+    /** 供应商事件类型原文，便于排查 */
+    type: string;
+    /** 本次事件指向的支付；无法关联时为 undefined，调用方应告警而非静默丢弃 */
+    providerRef?: string;
+    /** 归一化后的状态；无法判定时为 unknown */
+    state: SettlementState;
+    raw: unknown;
+}
+interface RefundInput {
+    providerRef: string;
+    /** 省略表示全额退款 */
+    money?: Money;
+    reason?: string;
+    idempotencyKey: string;
+}
+/**
+ * 渠道适配器。
+ *
+ * 实现约定：
+ *   - 只做协议与状态映射，不做任何产品决策（金额、资格、时机、文案）。
+ *   - retrieve 必须是只读的。对账会调用它，绝不能在对账过程中扣款——
+ *     "查询顺手把 APPROVED 捕获了"是这类系统最贵的一类 bug。
+ *   - 判定不了就返回 unknown，不要猜成 failed。
+ */
+interface PaymentProviderAdapter {
+    readonly id: string;
+    /**
+     * 该渠道客观支持的结算币种；undefined 表示未声明限制。
+     * 这是供应商事实，不是产品策略——"我们只卖 USD"属于上层应用。
+     */
+    readonly supportedCurrencies?: readonly string[];
+    createPayment(input: CreatePaymentInput): Promise<PaymentSession>;
+    /** 授权与扣款分离的渠道用它完成扣款（PayPal APPROVED → capture） */
+    capture(providerRef: string, idempotencyKey: string): Promise<PaymentSession>;
+    /** 只读查询，供回跳后主动确认与定时对账使用 */
+    retrieve(providerRef: string): Promise<PaymentSession>;
+    refund(input: RefundInput): Promise<{
+        refundRef: string;
+        state: SettlementState;
+    }>;
+    cancel?(providerRef: string): Promise<PaymentSession>;
+    /** 验签并归一化；验签失败必须抛错，不得返回一个"未知"事件蒙混过去 */
+    parseWebhook(request: WebhookRequest): Promise<WebhookObservation>;
 }
-interface RefundResult {
+/** 该渠道能否处理这个币种；未声明限制时一律放行。 */
+declare function adapterSupportsCurrency(adapter: Pick<PaymentProviderAdapter, "supportedCurrencies">, currency: string): boolean;
+
+/**
+ * 十进制金额字符串与供应商最小单位之间的转换。
+ *
+ * 契约对外一律用十进制字符串（见 Money），但 Stripe 等渠道的 API 收最小单位整数。
+ * 转换只发生在适配器边界。用字符串补位而不是 `Math.round(x * 100)`，真正的收益有两点
+ * （不是"浮点一定算错"——对两位小数的常规金额，乘 100 再取整其实是可靠的）：
+ *   1. **精度超限会报错而不是静默取整**。`Math.round(1.005 * 100)` 得到 100，
+ *      悄悄吞掉半分钱；这里直接拒绝，让调用方去面对它本就不该产生的金额。
+ *   2. **零小数位币种不会被乘以 100**。JPY 的 500 就是 500，按两位小数处理会放大 100 倍。
+ */
+declare function currencyExponent(currency: string): number;
+/** "29.00" + USD → 2900；"500" + JPY → 500 */
+declare function toMinorUnits(amount: string, currency: string): number;
+/** 2900 + USD → "29.00"；500 + JPY → "500" */
+declare function fromMinorUnits(value: number, currency: string): string;
+
+/**
+ * 渠道适配器注册表。
+ *
+ * 取代旧的 PaymentService：那一版路由的是从未被任何适配器实现过的 PaymentProvider，
+ * 并且把 createPaymentIntent / confirmPayment 之类的业务动作也挂在自己身上。
+ * 这里只做注册与查找——编排（建单、履约、对账）属于上层应用，不属于注册表。
+ */
+declare class PaymentProviderRegistry {
+    private readonly logger;
+    private readonly adapters;
+    constructor(adapters?: readonly PaymentProviderAdapter[]);
+    register(adapter: PaymentProviderAdapter): void;
+    has(id: string): boolean;
+    get(id: string): PaymentProviderAdapter;
+    list(): PaymentProviderAdapter[];
+    /** 能处理该币种的渠道；"本产品卖不卖这个币种"由上层决定，不在这里过滤。 */
+    listForCurrency(currency: string): PaymentProviderAdapter[];
+}
+
+/** Read-only provider evidence; unknown must never be treated as an instruction to charge. */
+type PaymentSettlementState = 'paid' | 'unpaid' | 'unknown';
+
+interface PayPalPaymentTransportOptions {
+    clientId: string;
+    clientSecret: string;
+    mode: 'live' | 'sandbox';
+    fetcher?: typeof fetch;
+    logger?: {
+        warn: (message: string) => void;
+        error: (message: string) => void;
+    };
+}
+interface PayPalCaptureRefundRequest {
+    /**
+     * 省略表示全额退款——PayPal 的 refund 接口本就允许不传 amount。
+     * 原先声明为必填，导致调用方为了"全额退"必须自己算出金额再传回去，
+     * 一旦本地金额与供应商记录有出入就会退错数额。
+     */
+    amount?: {
+        value: string;
+        currency_code: string;
+    };
+    note_to_payer?: string;
+}
+interface PayPalCaptureRefundResponse {
+    id?: string;
+    status?: string;
+    message?: string;
+}
+interface PayPalOrderRepresentation {
+    id?: string;
+    status?: string;
+    links?: Array<{
+        rel?: string;
+        href?: string;
+    }>;
+    purchaseUnits?: Array<{
+        payments?: {
+            captures?: Array<{
+                id?: string;
+            }>;
+        };
+    }>;
+}
+interface PayPalOrderObservation<T extends PayPalOrderRepresentation = PayPalOrderRepresentation> {
+    raw: T;
+    id?: string;
+    approveUrl?: string;
+    captureId?: string;
+    settlement: PaymentSettlementState;
+}
+/** APPROVED means approval only, never evidence of a captured payment. */
+declare function observePayPalOrder<T extends PayPalOrderRepresentation>(raw: T): PayPalOrderObservation<T>;
+interface PayPalCaptureObservation {
+    raw: Record<string, unknown>;
     id: string;
-    paymentId: string;
-    amount: number;
-    status: 'pending' | 'succeeded' | 'failed';
-    reason?: string;
+    failureReason?: string;
 }
-interface WebhookEvent {
+type PayPalWebhookObservation = {
+    raw: Record<string, unknown>;
     type: string;
-    data: Record<string, unknown>;
-}
-interface SubscriptionPlan {
+    kind: 'capture-succeeded' | 'capture-failed';
+    capture: PayPalCaptureObservation;
+} | {
+    raw: Record<string, unknown>;
+    type: string;
+    kind: 'unknown';
+};
+interface PayPalMoneyReturnedObservation {
     id: string;
-    name: string;
-    amount: number;
+    captureId?: string;
+    orderId?: string;
+    amount: string;
     currency: string;
-    interval: 'day' | 'week' | 'month' | 'year';
-    intervalCount: number;
-    trialDays?: number;
-    features?: string[];
+    status: 'PENDING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
 }
-interface Subscription {
-    id: string;
-    planId: string;
-    customerId: string;
-    status: 'active' | 'past_due' | 'cancelled' | 'trialing' | 'paused';
-    currentPeriodStart: Date;
-    currentPeriodEnd: Date;
-    cancelAtPeriodEnd: boolean;
-}
-interface SubscriptionProvider {
-    createSubscription(customerId: string, planId: string): Promise<Subscription>;
-    cancelSubscription(subscriptionId: string, immediately?: boolean): Promise<Subscription>;
-    getSubscription(subscriptionId: string): Promise<Subscription>;
-    listSubscriptions(customerId: string): Promise<Subscription[]>;
-    changePlan(subscriptionId: string, newPlanId: string): Promise<Subscription>;
+/** Decode only after signature verification; this performs no authentication or network call. */
+declare function decodePayPalWebhookEvent(payload: string): PayPalWebhookObservation;
+/** Additive decoder: the original capture-event discriminated union stays compatible. */
+declare function decodePayPalMoneyReturnedEvent(payload: string): {
+    raw: Record<string, unknown>;
+    type: string;
+    kind: 'capture-refunded' | 'capture-reversed';
+    returned: PayPalMoneyReturnedObservation;
+} | null;
+/** SDK order transport plus the OAuth-backed REST endpoints absent from the current SDK integration. */
+declare class PayPalPaymentTransport {
+    private readonly options;
+    readonly orders: OrdersController;
+    private readonly baseUrl;
+    private readonly fetcher;
+    constructor(options: PayPalPaymentTransportOptions);
+    createOrder(input: Parameters<OrdersController['createOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    /** An explicit capture command; never invoked by getOrder or status observation. */
+    captureOrder(input: Parameters<OrdersController['captureOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    getOrder(input: Parameters<OrdersController['getOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
+    private getAccessToken;
+    verifyWebhookSignature(payload: string, headers: Record<string, string>, webhookId: string): Promise<boolean>;
+    refundCapture(captureId: string, request: PayPalCaptureRefundRequest, requestId?: string): Promise<PayPalCaptureRefundResponse>;
 }
 
 /**
- * 支付服务 — 管理多个 PaymentProvider 的注册和路由。
+ * PayPal Orders v2 适配器。
  *
- * 使用方式：
- *   paymentService.register(stripeProvider);
- *   paymentService.register(wechatPayProvider);
- *   await paymentService.createPaymentIntent('stripe', params);
+ * 只做协议转换与状态映射，不含任何产品策略。传输层沿用已在生产验证过的
+ * PayPalPaymentTransport，本适配器不重写它。
  */
-declare class PaymentService {
-    private readonly logger;
-    private readonly providers;
-    /** 注册支付提供商 */
-    register(provider: PaymentProvider): void;
-    /** 注销支付提供商 */
-    unregister(providerId: string): boolean;
-    /** 获取已注册的提供商列表 */
-    listProviders(): PaymentProvider[];
-    /** 获取指定提供商 */
-    getProvider(providerId: string): PaymentProvider;
-    /** 创建支付意图 */
-    createPaymentIntent(providerId: string, params: CreatePaymentParams): Promise<PaymentIntent>;
-    /** 确认支付 */
-    confirmPayment(providerId: string, intentId: string): Promise<PaymentResult>;
-    /** 退款 */
-    refund(providerId: string, paymentId: string, amount?: number, reason?: string): Promise<RefundResult>;
-    /** 查询支付状态 */
-    getPaymentStatus(providerId: string, intentId: string): Promise<PaymentStatus>;
-    /** 处理 Webhook */
-    handleWebhook(providerId: string, payload: unknown, signature: string): Promise<WebhookEvent>;
+interface PayPalAdapterOptions {
+    transport: PayPalPaymentTransport;
+    /** Webhook 验签用；缺失时 parseWebhook 必须拒绝，而不是放行 */
+    webhookId?: string;
+    brandName?: string;
+}
+/**
+ * PayPal REST 支持的 25 种结算币种。
+ * 来源：https://developer.paypal.com/api/rest/reference/currency-codes/
+ * 这是供应商事实；"本产品只卖哪几种"属于上层应用，不写在这里。
+ */
+declare const PAYPAL_SUPPORTED_CURRENCIES: readonly ["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"];
+/**
+ * PayPal 订单状态 → 中立状态。
+ *
+ * 关键约定：顶层 COMPLETED 还不足以判定已扣款，必须同时看到一条 COMPLETED 的
+ * capture；否则停在 authorized 继续观察。识别不了的状态一律 unknown，绝不猜成 failed。
+ */
+declare function observePayPalState(order: Order$1): SettlementState;
+declare function createPayPalAdapter(options: PayPalAdapterOptions): PaymentProviderAdapter;
+
+interface StripeAdapterOptions {
+    client: Stripe;
+    /** Webhook 验签密钥；缺失时 parseWebhook 必须拒绝 */
+    webhookSecret?: string;
+    /** 传给 Checkout 的支付方式配置（pmc_xxx），由上层按业务决定 */
+    paymentMethodConfiguration?: string;
+}
+/**
+ * Stripe Checkout 会话状态 → 中立状态。
+ * 识别不了的组合一律 unknown：Stripe 的异步支付方式（如银行转账）会长时间停在
+ * complete + unpaid，那不是失败。
+ */
+declare function observeStripeState(session: Stripe.Checkout.Session): SettlementState;
+declare function createStripeAdapter(options: StripeAdapterOptions): PaymentProviderAdapter;
+
+/**
+ * 渠道适配器契约套件。
+ *
+ * 多渠道抽象的价值不在接口长什么样，而在于**所有渠道遵守同一组安全性质**。
+ * 每接一个渠道都要跑这套；它抓的是那些只在生产环境、只在特定时序下才暴露的错误。
+ *
+ * 刻意不依赖任何测试框架：返回结构化结果，既能在 vitest/jest 里包一层，
+ * 也能被 node --test 或 CI 脚本直接调用。
+ */
+interface ContractCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+interface AdapterProbe {
+    /** 每次返回全新的适配器实例，以及它对供应商发起过的**写操作**记录 */
+    create(): {
+        adapter: PaymentProviderAdapter;
+        mutatingCalls: () => string[];
+    };
+    /** 该渠道支持的一个币种 */
+    supportedCurrency: string;
+    /** 该渠道不支持的一个币种；未声明限制时传 null */
+    unsupportedCurrency: string | null;
+    /** 一个签名无效的 webhook 请求 */
+    invalidWebhook: WebhookRequest;
+    /** 写操作端点名中代表"扣款"的片段，用于检测只读违规 */
+    captureCallNames?: readonly string[];
+}
+declare function checkPaymentAdapterContract(probe: AdapterProbe): Promise<ContractCheck[]>;
+
+/**
+ * 内存参考适配器。
+ *
+ * 两个用途：
+ *   1. 让接入方在不连真实网关的情况下测自己的编排逻辑。
+ *   2. 给 contract-suite 当基准——一个**正确**的适配器必须全过，
+ *      故意写坏的变体必须被逐条抓出来。没有这一步，契约套件只是一组永远
+ *      绿灯的断言，证明不了任何事。
+ */
+interface FakeAdapterOptions {
+    id?: string;
+    supportedCurrencies?: readonly string[];
+    /** 故意违约，用于验证 contract-suite 的检出能力 */
+    defects?: {
+        /** retrieve 里偷偷扣款——最贵的一类 bug */
+        retrieveCaptures?: boolean;
+        /** 忽略幂等键，每次都开新支付 */
+        ignoreIdempotency?: boolean;
+        /** 验签失败也不抛错，返回一个"未知"事件蒙混过去 */
+        acceptsBadSignature?: boolean;
+        /** 把中间态猜成 failed */
+        guessesPendingAsFailed?: boolean;
+        /** 金额按浮点处理 */
+        mangleAmount?: boolean;
+    };
 }
+declare function createFakeAdapter(options?: FakeAdapterOptions): {
+    adapter: PaymentProviderAdapter;
+    mutatingCalls: () => string[];
+};
 
 declare const ORDER_PERSISTENCE = "PAYMENT_ORDER_PERSISTENCE";
 /**
@@ -147,7 +451,12 @@ interface Order {
     providerId: string;
     paymentIntentId?: string;
     paymentId?: string;
-    amount: number;
+    /**
+     * 十进制字符串，与 Money.amount 同一表示。
+     * 原先是 number：一旦金额在 number 与字符串之间来回转换，"29.00" 会变成 29，
+     * 三位小数币种会被静默截断。整条链路只保留一种表示。
+     */
+    amount: string;
     currency: string;
     status: OrderStatus;
     metadata?: Record<string, string>;
@@ -159,7 +468,7 @@ interface Order {
 interface CreateOrderParams {
     orderId: string;
     providerId: string;
-    payment: CreatePaymentParams;
+    payment: CreatePaymentInput;
 }
 declare class OrderNotFoundError extends Error {
     readonly orderId: string;
@@ -167,14 +476,35 @@ declare class OrderNotFoundError extends Error {
 }
 /** Durable provider workflow. External calls never run inside a database transaction here. */
 declare class OrderService {
-    private readonly paymentService;
+    private readonly providers;
     private readonly orders;
-    constructor(paymentService: PaymentService, orders: OrderPersistence<Order>);
+    constructor(providers: PaymentProviderRegistry, orders: OrderPersistence<Order>);
     createOrder(params: CreateOrderParams): Promise<Order>;
     private initiatePayment;
-    confirmOrder(orderId: string): Promise<PaymentResult>;
-    refundOrder(orderId: string, amount?: number, reason?: string): Promise<RefundResult>;
-    retryOrder(orderId: string): Promise<Order>;
+    /**
+     * 扣款。幂等键由调用方给出——同一笔订单重试必须复用同一个键，否则渠道会认为是新支付。
+     * 判定不了的结果保持 confirming，交由只读对账解决，绝不在这里重复扣款。
+     */
+    confirmOrder(orderId: string, idempotencyKey: string): Promise<PaymentSession>;
+    /**
+     * 把渠道观察到的结算状态落到订单上。
+     * 迁移是否允许由 reconcile() 统一裁决，保证所有渠道遵守同一套安全性质
+     * （unknown 不覆盖已知状态、已收款不被迟到的失败回调回退）。
+     */
+    private applySettlement;
+    refundOrder(orderId: string, idempotencyKey: string, options?: {
+        money?: CreatePaymentInput['money'];
+        reason?: string;
+    }): Promise<{
+        refundRef: string;
+        state: SettlementState;
+    }>;
+    /**
+     * 重试失败订单。
+     * idempotencyKey 必须与上一次不同：沿用旧键会让渠道原样返回那笔已失败的支付，
+     * 看起来"重试了"其实什么都没发生。
+     */
+    retryOrder(orderId: string, idempotencyKey: string): Promise<Order>;
     cancelOrder(orderId: string): Promise<Order>;
     getOrder(orderId: string): Promise<Order>;
     listOrders(): Promise<Order[]>;
@@ -190,7 +520,8 @@ interface RecoveryEmailParams {
     userName: string;
     orderId: string;
     orderNumber?: string;
-    amount: number;
+    /** 十进制字符串，与 Order.amount / Money.amount 同一表示 */
+    amount: string;
     currency: string;
     errorReason: string;
     retryUrl: string;
@@ -258,9 +589,10 @@ declare class PaymentRecoveryService {
      */
     handleFailedPayment(orderId: string, errorCode?: string, errorMessage?: string): Promise<void>;
     /**
-     * 重试失败订单 — 将 failed → created 并重新发起支付
+     * 重试失败订单 — 将 failed → created 并重新发起支付。
+     * 幂等键由调用方给出且必须与上次不同，否则渠道会原样返回那笔已失败的支付。
      */
-    retryOrder(orderId: string): Promise<Order>;
+    retryOrder(orderId: string, idempotencyKey: string): Promise<Order>;
     getRecoveryAttempts(orderId: string): Promise<{
         count: number;
         lastAt: Date;
@@ -302,7 +634,7 @@ interface PaymentRecoverySentEvent {
 
 declare const PAYMENT_PROVIDERS = "PAYMENT_PROVIDERS";
 interface PaymentModuleOptions {
-    providers?: PaymentProvider[];
+    providers?: PaymentProviderAdapter[];
     orderPersistence: OrderPersistence<Order>;
     /** Required when using payment recovery mail; no process-memory default. */
     recoveryAttempts?: RecoveryAttemptStore;
@@ -317,9 +649,6 @@ declare class ZuckerPaymentModule {
     static forRootAsync(options: PaymentModuleAsyncOptions): DynamicModule;
 }
 
-/** Read-only provider evidence; unknown must never be treated as an instruction to charge. */
-type PaymentSettlementState = 'paid' | 'unpaid' | 'unknown';
-
 /** Construct the installed Stripe peer with the consumer's explicit API/transport configuration. */
 declare function createStripeClient(secretKey: string, options: Stripe.StripeConfig): Stripe;
 /** Verify raw webhook bytes using the installed SDK's timestamp/signature checks. */
@@ -338,7 +667,9 @@ interface StripeCheckoutObservation {
     settlement: PaymentSettlementState;
 }
 declare function observeStripeCheckoutSession(raw: Stripe.Checkout.Session): StripeCheckoutObservation;
-declare function createStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, params: Stripe.Checkout.SessionCreateParams): Promise<StripeCheckoutObservation>;
+declare function createStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, params: Stripe.Checkout.SessionCreateParams, 
+/** 传入 idempotencyKey 后，重试同一请求不会产生第二个 Session */
+options?: Stripe.RequestOptions): Promise<StripeCheckoutObservation>;
 declare function retrieveStripeCheckoutSession(client: Pick<Stripe, 'checkout'>, id: string): Promise<StripeCheckoutObservation>;
 interface StripePaymentIntentObservation {
     raw: Stripe.PaymentIntent;
@@ -352,83 +683,4 @@ interface StripePaymentIntentObservation {
 declare function observeStripePaymentIntent(raw: Stripe.PaymentIntent): StripePaymentIntentObservation;
 declare function retrieveStripePaymentIntent(client: Pick<Stripe, 'paymentIntents'>, id: string, params?: Stripe.PaymentIntentRetrieveParams): Promise<StripePaymentIntentObservation>;
 
-interface PayPalPaymentTransportOptions {
-    clientId: string;
-    clientSecret: string;
-    mode: 'live' | 'sandbox';
-    fetcher?: typeof fetch;
-    logger?: {
-        warn: (message: string) => void;
-        error: (message: string) => void;
-    };
-}
-interface PayPalCaptureRefundRequest {
-    amount: {
-        value: string;
-        currency_code: string;
-    };
-    note_to_payer?: string;
-}
-interface PayPalCaptureRefundResponse {
-    id?: string;
-    status?: string;
-    message?: string;
-}
-interface PayPalOrderRepresentation {
-    id?: string;
-    status?: string;
-    links?: Array<{
-        rel?: string;
-        href?: string;
-    }>;
-    purchaseUnits?: Array<{
-        payments?: {
-            captures?: Array<{
-                id?: string;
-            }>;
-        };
-    }>;
-}
-interface PayPalOrderObservation<T extends PayPalOrderRepresentation = PayPalOrderRepresentation> {
-    raw: T;
-    id?: string;
-    approveUrl?: string;
-    captureId?: string;
-    settlement: PaymentSettlementState;
-}
-/** APPROVED means approval only, never evidence of a captured payment. */
-declare function observePayPalOrder<T extends PayPalOrderRepresentation>(raw: T): PayPalOrderObservation<T>;
-interface PayPalCaptureObservation {
-    raw: Record<string, unknown>;
-    id: string;
-    failureReason?: string;
-}
-type PayPalWebhookObservation = {
-    raw: Record<string, unknown>;
-    type: string;
-    kind: 'capture-succeeded' | 'capture-failed';
-    capture: PayPalCaptureObservation;
-} | {
-    raw: Record<string, unknown>;
-    type: string;
-    kind: 'unknown';
-};
-/** Decode only after signature verification; this performs no authentication or network call. */
-declare function decodePayPalWebhookEvent(payload: string): PayPalWebhookObservation;
-/** SDK order transport plus the OAuth-backed REST endpoints absent from the current SDK integration. */
-declare class PayPalPaymentTransport {
-    private readonly options;
-    readonly orders: OrdersController;
-    private readonly baseUrl;
-    private readonly fetcher;
-    constructor(options: PayPalPaymentTransportOptions);
-    createOrder(input: Parameters<OrdersController['createOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
-    /** An explicit capture command; never invoked by getOrder or status observation. */
-    captureOrder(input: Parameters<OrdersController['captureOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
-    getOrder(input: Parameters<OrdersController['getOrder']>[0]): Promise<PayPalOrderObservation<_paypal_paypal_server_sdk.Order>>;
-    private getAccessToken;
-    verifyWebhookSignature(payload: string, headers: Record<string, string>, webhookId: string): Promise<boolean>;
-    refundCapture(captureId: string, request: PayPalCaptureRefundRequest): Promise<PayPalCaptureRefundResponse>;
-}
-
-export { type CreateOrderParams, type CreatePaymentParams, DatabaseOrderPersistence, ORDER_PERSISTENCE, type Order, type OrderFailedEvent, OrderNotFoundError, type OrderPersistence, OrderService, type OrderStatus, PAYMENT_PROVIDERS, type PayPalCaptureObservation, type PayPalCaptureRefundRequest, type PayPalCaptureRefundResponse, type PayPalOrderObservation, type PayPalOrderRepresentation, PayPalPaymentTransport, type PayPalPaymentTransportOptions, type PayPalWebhookObservation, type PaymentEventType, PaymentEvents, type PaymentIntent, type PaymentModuleAsyncOptions, type PaymentModuleOptions, type PaymentProvider, type PaymentRecoverySentEvent, PaymentRecoveryService, type PaymentResult, PaymentService, type PaymentSettlementState, type PaymentStatus, RECOVERY_ATTEMPT_STORE, RECOVERY_MAIL_SENDER, RECOVERY_URL_GENERATOR, RECOVERY_USER_LOOKUP, type RecoveryAttemptStore, type RecoveryEmailParams, type RecoveryMailSender, type RecoveryOptions, type RecoveryUrlGenerator, type RecoveryUserLookup, type RefundResult, type StripeCheckoutObservation, type StripePaymentIntentObservation, type Subscription, type SubscriptionPlan, type SubscriptionProvider, type WebhookEvent, ZuckerPaymentModule, createStripeCheckoutSession, createStripeClient, decodePayPalWebhookEvent, friendlyErrorReason, observePayPalOrder, observeStripeCheckoutSession, observeStripePaymentIntent, retrieveStripeCheckoutSession, retrieveStripePaymentIntent, stripeResourceId, verifyStripeWebhookEvent };
+export { type AdapterProbe, type ContractCheck, type CreateOrderParams, type CreatePaymentInput, DatabaseOrderPersistence, type FakeAdapterOptions, type Money, ORDER_PERSISTENCE, type Order, type OrderFailedEvent, OrderNotFoundError, type OrderPersistence, OrderService, type OrderStatus, PAYMENT_PROVIDERS, PAYPAL_SUPPORTED_CURRENCIES, type PayPalAdapterOptions, type PayPalCaptureObservation, type PayPalCaptureRefundRequest, type PayPalCaptureRefundResponse, type PayPalMoneyReturnedObservation, type PayPalOrderObservation, type PayPalOrderRepresentation, PayPalPaymentTransport, type PayPalPaymentTransportOptions, type PayPalWebhookObservation, type PaymentEventType, PaymentEvents, type PaymentModuleAsyncOptions, type PaymentModuleOptions, type PaymentNextAction, type PaymentProviderAdapter, PaymentProviderRegistry, type PaymentRecoverySentEvent, PaymentRecoveryService, type PaymentSession, type PaymentSettlementState, RECOVERY_ATTEMPT_STORE, RECOVERY_MAIL_SENDER, RECOVERY_URL_GENERATOR, RECOVERY_USER_LOOKUP, type RecoveryAttemptStore, type RecoveryEmailParams, type RecoveryMailSender, type RecoveryOptions, type RecoveryUrlGenerator, type RecoveryUserLookup, type RefundInput, SETTLEMENT_STATES, type SettlementDecision, type SettlementState, type StripeAdapterOptions, type StripeCheckoutObservation, type StripePaymentIntentObservation, type WebhookObservation, type WebhookRequest, 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 };