Class PaymentController

支付通道 HTTP 控制器：状态/客户/结账/退款/Webhook 端点，委托 PaymentService。

Remarks

非 webhook 属用户级（Stripe customer/checkout·不经租户仓储）→ 类级豁免租户墙（仍需会话）； webhook 方法级 @Public 自动兼豁免会话+租户墙。

Index

Methods

createCheckout createCustomer handleWebhook refund retrieveCheckout test

Methods

createCheckout

createCheckout(
    createCheckoutDto: {
        amount: number;
        currency: string;
        description?: string;
        metadata?: Record<string, string>;
    },
): Promise<PaymentCheckoutRef>
创建结账（收款意图）。
Parameters
- createCheckoutDto: {
      amount: number;
      currency: string;
      description?: string;
      metadata?: Record<string, string>;
  }
  结账创建入参。
Returns Promise<PaymentCheckoutRef>
归一化结账引用。
- Defined in apps/api/src/modules/payment/api/payment.controller.ts:128

createCustomer

createCustomer(
    createCustomerDto: {
        email: string;
        metadata?: Record<string, string>;
        name?: string;
    },
): Promise<PaymentCustomerRef>
创建支付客户。
Parameters
- createCustomerDto: { email: string; metadata?: Record<string, string>; name?: string }
  客户创建入参。
Returns Promise<PaymentCustomerRef>
归一化客户引用。
- Defined in apps/api/src/modules/payment/api/payment.controller.ts:109

handleWebhook

handleWebhook(
    request: RawBodyRequest<
        FastifyRequest<
            RouteGenericInterface,
            RawServerDefault,
            IncomingMessage,
            FastifySchema,
            FastifyTypeProviderDefault,
            unknown,
            FastifyBaseLogger,
            ResolveFastifyRequestType<
                FastifyTypeProviderDefault,
                FastifySchema,
                RouteGenericInterface,
            >,
        >,
    >,
    signature: string,
): Promise<{ received: boolean }>
处理支付 Webhook 事件（靠通道签名校验而非会话）。
Parameters
- request: RawBodyRequest<
      FastifyRequest<
          RouteGenericInterface,
          RawServerDefault,
          IncomingMessage,
          FastifySchema,
          FastifyTypeProviderDefault,
          unknown,
          FastifyBaseLogger,
          ResolveFastifyRequestType<
              FastifyTypeProviderDefault,
              FastifySchema,
              RouteGenericInterface,
          >,
      >,
  >
  携 rawBody 的原始请求。
- signature: string
  stripe-signature 头。
Returns Promise<{ received: boolean }>
已接收 ack（{ received: true }）。
- Defined in apps/api/src/modules/payment/api/payment.controller.ts:188

refund

refund(
    refundPaymentDto: {
        amount?: number;
        checkoutId: string;
        reason?: string;
    },
): Promise<PaymentRefundRef>
对结账退款。
Parameters
- refundPaymentDto: { amount?: number; checkoutId: string; reason?: string }
  退款入参。
Returns Promise<PaymentRefundRef>
归一化退款引用。
- Defined in apps/api/src/modules/payment/api/payment.controller.ts:166

retrieveCheckout

retrieveCheckout(id: string): Promise<PaymentCheckoutRef>
按 id 取回结账。
Parameters
- id: string
  结账（收款意图）ID。
Returns Promise<PaymentCheckoutRef>
归一化结账引用。
- Defined in apps/api/src/modules/payment/api/payment.controller.ts:147

test

test(): {
    available: PaymentProviderId[];
    selected: PaymentProviderId;
    status: string;
}
支付集成状态概览。

Returns { available: PaymentProviderId[]; selected: PaymentProviderId; status: string }
当前选中通道与可用通道。
- Defined in apps/api/src/modules/payment/api/payment.controller.ts:91