zibri 2.2.0 → 2.3.0

package/src/plugin/payment/providers/pay-pal/pay-pal-client.ts

@@ -1,8 +1,10 @@
-import { PayPalProviderOptions } from './pay-pal.payment-provider';
-import { inject, ZIBRI_DI_TOKENS } from '../../../../di';
-import { Property } from '../../../../entity';
-import { KnownHeader, MimeType } from '../../../../http';
-import { HttpClientInterface } from '../../../../http-client';
+import { PayPalPaymentProviderOptions } from './pay-pal.payment-provider';
+import { ZIBRI_DI_TOKENS } from '../../../../di/default/zibri-di-tokens.default';
+import { inject } from '../../../../di/inject.function';
+import { Property } from '../../../../entity/decorators/property.decorator';
+import { KnownHeader } from '../../../../http/known-header.enum';
+import { MimeType } from '../../../../http/mime-type.enum';
+import { HttpClientInterface } from '../../../../http-client/http-client.interface';
 
 /**
  * The intent of the new payment.
@@ -315,7 +317,7 @@ export class PayPalClient {
     private token?: PayPalAccessToken;
     private readonly http: HttpClientInterface;
 
-    constructor(private readonly options: PayPalProviderOptions) {
+    constructor(private readonly options: PayPalPaymentProviderOptions) {
         this.baseUrl = options.env === 'live' ? 'https://api-m.paypal.com' : 'https://api-m.sandbox.paypal.com';
         this.http = inject(ZIBRI_DI_TOKENS.HTTP_CLIENT);
     }
@@ -336,7 +338,7 @@ export class PayPalClient {
                 [KnownHeader.AUTHORIZATION]: `Basic ${auth}`,
                 [KnownHeader.CONTENT_TYPE]: MimeType.FORM_URL_ENCODED
             },
-            responseBody: AuthResp
+            responseBody: { type: MimeType.JSON, modelClass: AuthResp, allowAdditionalProperties: true }
         })).body;
 
         this.token = {
@@ -424,6 +426,24 @@ export class PayPalClient {
         })).body;
     }
 
+    /**
+     * Authorizes an AUTHORIZE-intent order that the buyer has already approved.
+     * Must be called before confirmPaymentReservation can read the authorization id.
+     * @param orderId - The id of the approved order to authorize.
+     * @returns The authorized order, including purchase_units[].payments.authorizations.
+     */
+    async authorizeOrder(orderId: string): Promise<GetOrderResp> {
+        const token: string = await this.getAccessToken();
+        const url: string = `${this.baseUrl}/v2/checkout/orders/${encodeURIComponent(orderId)}/authorize`;
+
+        return (await this.http.post(url, {}, {
+            responseBody: GetOrderResp,
+            headers: {
+                Authorization: `Bearer ${token}`
+            }
+        })).body;
+    }
+
     /**
      * Cancels the existing authorization with the given id.
      * @param authorizationId - The id of the authorization to cancel.

package/src/plugin/payment/providers/pay-pal/pay-pal.payment-provider.test.ts

@@ -0,0 +1,280 @@
+import assert from 'node:assert';
+
+import { afterAll, beforeAll, describe, expect, it } from '@jest/globals';
+// eslint-disable-next-line eslintImport/no-unassigned-import
+import 'dotenv/config';
+
+import { PayPalPaymentData, PayPalPaymentProvider, PayPalPaymentProviderPaymentData, PayPalValidatedPaymentData } from './pay-pal.payment-provider';
+import { defaultTestServerProviders } from '../../../../__testing__/test-server/providers';
+import { StartedTestServer, startTestServer } from '../../../../__testing__/test-server/start-test-server.function';
+import { Repository } from '../../../../data-source/repository';
+import { repositoryTokenFor } from '../../../../di/decorators/inject-repository.decorator';
+import { inject } from '../../../../di/inject.function';
+import { defineProvider } from '../../../../di/models/di-provider.model';
+import { isHttpClientError } from '../../../../http-client/http-client.error';
+import { CurrencyCode } from '../../../../localization/models/currency-code.model';
+import { UUIDUtilities } from '../../../../utilities/uuid.utilities';
+import { KnownPaymentMethod, PaymentMethod } from '../../models/payment-method.model';
+import { PaymentPluginOptionsInput } from '../../models/payment-plugin-options-input.model';
+import { PaymentStatus } from '../../models/payment-status.enum';
+import { Payment } from '../../models/payment.model';
+import { ZibriPaymentPlugin } from '../../payment.plugin';
+import { DefaultPaymentProviderArray, ZIBRI_PAYMENT_PLUGIN_DI_TOKENS } from '../../payment.tokens';
+import { PaymentServiceInterface } from '../../services/payment-service.interface';
+
+async function getSandboxToken(clientId: string, clientSecret: string): Promise<string> {
+    const auth: string = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+    const res: Response = await fetch('https://api-m.sandbox.paypal.com/v1/oauth2/token', {
+        method: 'POST',
+        headers: {
+            Authorization: `Basic ${auth}`,
+            'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        body: 'grant_type=client_credentials'
+    });
+    if (!res.ok) {
+        throw new Error(`Sandbox auth failed: ${await res.text()}`);
+    }
+    const { access_token } = await res.json() as { access_token: string };
+    return access_token;
+}
+
+// TODO: this currently doesn't work.
+async function simulateBuyerApproval(merchantToken: string, orderId: string, returnUrl: string, cancelUrl: string): Promise<void> {
+    const res: Response = await fetch(
+        `https://api-m.sandbox.paypal.com/v2/checkout/orders/${orderId}/confirm-payment-source`,
+        {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${merchantToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                payment_source: {
+                    // eslint-disable-next-line cspell/spellchecker
+                    paypal: {
+                        experience_context: {
+                            payment_method_preference: 'IMMEDIATE_PAYMENT_REQUIRED',
+                            return_url: returnUrl,
+                            cancel_url: cancelUrl
+                        }
+                    }
+                }
+            })
+        }
+    );
+
+    const body: string = await res.text();
+    // eslint-disable-next-line no-console
+    console.debug('simulateBuyerApproval', { ok: res.ok, status: res.status, body });
+    if (!res.ok) {
+        throw new Error(`Buyer approval failed (${res.status}): ${body}`);
+    }
+}
+
+// ── Test suite ────────────────────────────────────────────────────────────────
+
+describe('PayPalPaymentProvider (sandbox)', () => {
+    let paymentService: PaymentServiceInterface<[KnownPaymentMethod.PAY_PAL], [PayPalPaymentProvider]>;
+    let paymentRepository: Repository<Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData>>;
+
+    let sandboxToken: string;
+    let testServer: StartedTestServer;
+
+    // eslint-disable-next-line cspell/spellchecker
+    const clientId: string | undefined = process.env['PAYPAL_CLIENT_ID'];
+    // eslint-disable-next-line cspell/spellchecker
+    const clientSecret: string | undefined = process.env['PAYPAL_CLIENT_SECRET'];
+
+    if (!clientId || !clientSecret) {
+        throw new Error('clientId or clientSecret not available');
+    }
+
+    const METHOD: KnownPaymentMethod = KnownPaymentMethod.PAY_PAL;
+    const AMOUNT: number = 9.99;
+    const CURRENCY: CurrencyCode = 'EUR';
+    const URLS: Required<Pick<PayPalPaymentData, 'cancelUrl' | 'returnUrl'>> = { returnUrl: 'https://example.com/return', cancelUrl: 'https://example.com/cancel' };
+
+    beforeAll(async () => {
+        testServer = await startTestServer({
+            plugins: [new ZibriPaymentPlugin()],
+            providers: [
+                ...defaultTestServerProviders,
+                defineProvider({
+                    token: ZIBRI_PAYMENT_PLUGIN_DI_TOKENS.OPTIONS_INPUT,
+                    useFactory: () => {
+                        const res: PaymentPluginOptionsInput<
+                            [KnownPaymentMethod.PAY_PAL],
+                            [PayPalPaymentProvider]
+                        > = {
+                            paymentMethods: [KnownPaymentMethod.PAY_PAL],
+                            paymentProviders: [
+                                new PayPalPaymentProvider('PayPal', {
+                                    clientId,
+                                    clientSecret,
+                                    env: 'sandbox'
+                                })
+                            ],
+                            providerNameForMethod: {
+                                [KnownPaymentMethod.PAY_PAL]: 'PayPal'
+                            }
+                        };
+                        return res as PaymentPluginOptionsInput<PaymentMethod[], DefaultPaymentProviderArray>;
+                    }
+                })
+            ]
+        });
+        paymentService = inject<PaymentServiceInterface<[KnownPaymentMethod.PAY_PAL], [PayPalPaymentProvider]>>(ZIBRI_PAYMENT_PLUGIN_DI_TOKENS.PAYMENT_SERVICE);
+        paymentRepository = inject(repositoryTokenFor(Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData>));
+        sandboxToken = await getSandboxToken(clientId, clientSecret);
+    });
+
+    afterAll(async () => {
+        await testServer.shutdown();
+    });
+
+    describe('validatePaymentData', () => {
+        it('accepts valid data', () => {
+            expect(() => paymentService.validatePaymentData(METHOD, { amount: AMOUNT, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate() })).not.toThrow();
+        });
+
+        it('rejects amount <= 0', () => {
+            expect(() => paymentService.validatePaymentData(METHOD, { amount: 0, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate() })).toThrow('amount must be > 0');
+        });
+
+        it('rejects missing currencyCode', () => {
+            expect(() => paymentService.validatePaymentData(METHOD, { amount: AMOUNT, currencyCode: '', transactionId: UUIDUtilities.generate() })).toThrow('currencyCode required');
+        });
+    });
+
+    // ── Direct payment: startPayment → confirmPayment ───────────────────────
+
+    describe.only('startPayment + confirmPayment', () => {
+        it.only('creates a CAPTURE-intent order and captures it after buyer approval', async () => {
+            const data: PayPalValidatedPaymentData = await paymentService.validatePaymentData(METHOD, {
+                amount: AMOUNT, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate(), ...URLS
+            });
+
+            const payment: Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData> = await paymentService.startPayment(METHOD, data);
+
+            expect(payment.status).toBe(PaymentStatus.CREATED);
+            expect(payment.data?.orderId).toBeTruthy();
+            expect(payment.data?.approvalUrl).toMatch(/paypal\.com/);
+
+            assert(payment.data?.orderId);
+
+            await simulateBuyerApproval(sandboxToken, payment.data.orderId, URLS.returnUrl, URLS.cancelUrl);
+            await paymentService.confirmPayment(payment);
+
+            const confirmedPayment: Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData> = await paymentRepository.findById(payment.id);
+            if (isHttpClientError(confirmedPayment.error)) {
+                // eslint-disable-next-line no-console
+                console.debug('confirmedPayment.error.responseData.body:\n', confirmedPayment.error.responseData?.body);
+            }
+
+            expect(confirmedPayment.status).toBe(PaymentStatus.PAID);
+            expect(confirmedPayment.data?.captureId).toBeTruthy();
+            expect(confirmedPayment.error).toBeUndefined();
+        });
+    });
+
+    // ── Cancel before buyer approves ────────────────────────────────────────
+
+    describe('cancelPayment (status: CREATED)', () => {
+        it('cancels locally without calling PayPal when the order was never approved', async () => {
+            const data: PayPalValidatedPaymentData = await paymentService.validatePaymentData(METHOD, {
+                amount: AMOUNT, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate()
+            });
+
+            const payment: Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData> = await paymentService.startPayment(METHOD, data);
+            expect(payment.status).toBe(PaymentStatus.CREATED);
+
+            await paymentService.cancelPayment(payment);
+
+            expect(payment.status).toBe(PaymentStatus.CANCELLED);
+            expect(payment.error).toBeUndefined();
+            // no PayPal call needed — just a local state change
+        });
+    });
+
+    // ── Reservation: startPaymentReservation → confirmPaymentReservation
+    //                → collectPaymentFromReservation ─────────────────────────
+
+    describe('startPaymentReservation + confirmPaymentReservation + collectPaymentFromReservation', () => {
+        it('creates an AUTHORIZE-intent order, reserves funds, then collects payment', async () => {
+            const data: PayPalValidatedPaymentData = await paymentService.validatePaymentData(METHOD, {
+                amount: AMOUNT, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate(), ...URLS
+            });
+
+            const payment: Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData> = await paymentService.startPaymentReservation(METHOD, data);
+
+            expect(payment.status).toBe(PaymentStatus.CREATED);
+            expect(payment.data?.orderId).toBeTruthy();
+
+            assert(payment.data?.orderId);
+
+            // Simulate buyer completing the approval redirect
+            await simulateBuyerApproval(sandboxToken, payment.data.orderId, URLS.returnUrl, URLS.cancelUrl);
+
+            // confirmPaymentReservation must call POST .../authorize (the BUG-2 fix)
+            await paymentService.confirmPaymentReservation(payment);
+
+            expect(payment.status).toBe(PaymentStatus.RESERVED);
+            expect(payment.data.authorizationId).toBeTruthy();
+            expect(payment.error).toBeUndefined();
+
+            // Collect the reserved funds
+            await paymentService.collectPaymentFromReservation(payment);
+
+            expect(payment.status).toBe(PaymentStatus.PAID);
+            expect(payment.data.captureId).toBeTruthy();
+            expect(payment.error).toBeUndefined();
+        });
+    });
+
+    // ── Cancel a reserved authorization (void) ──────────────────────────────
+
+    describe('cancelPayment (status: RESERVED)', () => {
+        it('voids the PayPal authorization and marks payment as CANCELLED', async () => {
+            const data: PayPalValidatedPaymentData = await paymentService.validatePaymentData(METHOD, {
+                amount: AMOUNT, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate(), ...URLS
+            });
+
+            const payment: Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData> = await paymentService.startPaymentReservation(METHOD, data);
+
+            assert(payment.data?.orderId);
+            await simulateBuyerApproval(sandboxToken, payment.data.orderId, URLS.returnUrl, URLS.cancelUrl);
+            await paymentService.confirmPaymentReservation(payment);
+
+            expect(payment.status).toBe(PaymentStatus.RESERVED);
+
+            await paymentService.cancelPayment(payment);
+
+            expect(payment.status).toBe(PaymentStatus.CANCELLED);
+            expect(payment.error).toBeUndefined();
+        });
+    });
+
+    // ── Refund ──────────────────────────────────────────────────────────────
+
+    describe('refundPayment', () => {
+        it('refunds a captured payment and marks it REFUNDED', async () => {
+            const data: PayPalValidatedPaymentData = await paymentService.validatePaymentData(METHOD, {
+                amount: AMOUNT, currencyCode: CURRENCY, transactionId: UUIDUtilities.generate(), ...URLS
+            });
+
+            const payment: Payment<KnownPaymentMethod.PAY_PAL, PayPalPaymentProviderPaymentData> = await paymentService.startPayment(METHOD, data);
+
+            assert(payment.data?.orderId);
+            await simulateBuyerApproval(sandboxToken, payment.data.orderId, URLS.returnUrl, URLS.cancelUrl);
+            await paymentService.confirmPayment(payment);
+
+            expect(payment.status).toBe(PaymentStatus.PAID);
+
+            await paymentService.refundPayment(payment);
+
+            expect(payment.status).toBe(PaymentStatus.REFUNDED);
+            expect(payment.error).toBeUndefined();
+        });
+    });
+});

package/src/plugin/payment/providers/pay-pal/pay-pal.payment-provider.ts

@@ -1,13 +1,16 @@
-import { AuthorizationCaptureResp, CaptureOrderResp, GetOrderResp, PayPalCapture, PayPalClient, RefundCaptureResp } from './pay-pal-client';
-import { Repository } from '../../../../data-source';
-import { inject, repositoryTokenFor } from '../../../../di';
-import { KnownPaymentMethod, Payment, PaymentStatus } from '../../models';
 import { PaymentProviderInterface } from '../payment-provider.interface';
+import { AuthorizationCaptureResp, CaptureOrderResp, GetOrderResp, PayPalCapture, PayPalClient, RefundCaptureResp } from './pay-pal-client';
+import { Repository } from '../../../../data-source/repository';
+import { repositoryTokenFor } from '../../../../di/decorators/inject-repository.decorator';
+import { inject } from '../../../../di/inject.function';
+import { KnownPaymentMethod } from '../../models/payment-method.model';
+import { PaymentStatus } from '../../models/payment-status.enum';
+import { Payment } from '../../models/payment.model';
 
 /**
  * The environment of the pay-pal client.
  */
-type PayPalEnv = 'sandbox' | 'live';
+export type PayPalEnv = 'sandbox' | 'live';
 
 /**
  * The supported methods of the PayPalPaymentProvider.
@@ -17,7 +20,7 @@ type SupportedMethods = [KnownPaymentMethod.PAY_PAL];
 /**
  * The data for creating a new payment.
  */
-type PayPalPaymentData = {
+export type PayPalPaymentData = {
     /**
      * The amount of the payment.
      */
@@ -43,12 +46,12 @@ type PayPalPaymentData = {
 /**
  * The validated payment data.
  */
-type PayPalValidatedPaymentData = PayPalPaymentData;
+export type PayPalValidatedPaymentData = PayPalPaymentData;
 
 /**
  * The payment data stored by the provider.
  */
-type PayPalProviderPaymentData = {
+export type PayPalPaymentProviderPaymentData = {
     /**
      * The id of the order.
      */
@@ -64,13 +67,17 @@ type PayPalProviderPaymentData = {
     /**
      * The id of the payment capture.
      */
-    captureId?: string
+    captureId?: string,
+    /**
+     * The id of the refund.
+     */
+    refundId?: string
 };
 
 /**
  * The payment reservation data.
  */
-type PayPalProviderReservationPaymentData = PayPalProviderPaymentData;
+type PayPalProviderReservationPaymentData = PayPalPaymentProviderPaymentData;
 
 /**
  * Maps payment methods to their payment data.
@@ -99,7 +106,7 @@ type ProviderPaymentDataMap = {
     /**
      * The provider payment data for the PayPal payment method.
      */
-    PAY_PAL: PayPalProviderPaymentData
+    PAY_PAL: PayPalPaymentProviderPaymentData
 };
 
 /**
@@ -145,7 +152,7 @@ type ReservationSupport = {
 /**
  * Options for configuring the PayPalPaymentProvider.
  */
-export type PayPalProviderOptions = {
+export type PayPalPaymentProviderOptions = {
     /**
      * The clientId needed to authenticate with the api.
      */
@@ -174,11 +181,21 @@ export class PayPalPaymentProvider implements PaymentProviderInterface<
     ReservationSupport
 > {
     // eslint-disable-next-line jsdoc/require-jsdoc
-    readonly cancellationSupported: CancellationSupport = { PAY_PAL: true };
+    declare readonly __supportedMethods: SupportedMethods;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    declare readonly __paymentDataMap: PaymentDataMap;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    declare readonly __validatedDataMap: ValidatedPaymentDataMap;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    declare readonly __providerPaymentDataMap: ProviderPaymentDataMap;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    declare readonly __providerReservationPaymentDataMap: ProviderReservationPaymentDataMap;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    declare readonly __cancellationSupportMap: CancellationSupport;
     // eslint-disable-next-line jsdoc/require-jsdoc
-    readonly refundSupported: RefundSupport = { PAY_PAL: true };
+    declare readonly __refundSupportMap: RefundSupport;
     // eslint-disable-next-line jsdoc/require-jsdoc
-    readonly reservationSupported: ReservationSupport = { PAY_PAL: true };
+    declare readonly __reservationSupportMap: ReservationSupport;
 
     /**
      * Client that encapsulates the PayPal API.
@@ -187,7 +204,7 @@ export class PayPalPaymentProvider implements PaymentProviderInterface<
 
     constructor(
         readonly name: string,
-        options: PayPalProviderOptions
+        options: PayPalPaymentProviderOptions
     ) {
         this.client = new PayPalClient(options);
     }
@@ -297,7 +314,7 @@ export class PayPalPaymentProvider implements PaymentProviderInterface<
         }
 
         try {
-            const resp: GetOrderResp = await this.client.getOrder(payment.data.orderId);
+            const resp: GetOrderResp = await this.client.authorizeOrder(payment.data.orderId);
 
             let foundAuthId: string | undefined;
             for (const pu of resp.purchase_units ?? []) {

package/src/plugin/payment/providers/payment-provider.interface.ts

@@ -1,54 +1,117 @@
-import { AnyObject } from '../../../entity';
-import { Payment, PaymentMethod } from '../models';
+import { AnyObject } from '../../../entity/any-object.model';
+import { PaymentMethod } from '../models/payment-method.model';
+import { Payment } from '../models/payment.model';
 
 /**
- * Interface for a payment provider.
+ * A payment provider interface with loose typing for use in DI.
  */
-export interface PaymentProviderInterface<
-    SupportedMethods extends readonly PaymentMethod[],
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    PaymentDataForMethod extends Record<SupportedMethods[number], AnyObject & { transactionId: string }>,
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    ValidatedPaymentDataForMethod extends Record<SupportedMethods[number], AnyObject & { transactionId: string }>,
-    ProviderPaymentDataForMethod extends Record<SupportedMethods[number], AnyObject>,
-    ProviderReservationPaymentDataForMethod extends Record<SupportedMethods[number], AnyObject>,
-    CancellationSupport extends Record<SupportedMethods[number], boolean>,
-    RefundSupport extends Record<SupportedMethods[number], boolean>,
-    ReservationSupport extends Record<SupportedMethods[number], boolean>
-> {
+export interface AnyPaymentProviderInterface {
     /**
      * The unique name of the provider, used to differentiate between them.
      */
     readonly name: string,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __supportedMethods: readonly PaymentMethod[],
+    // eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+    readonly __paymentDataMap: Record<string, any>,
+    // eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+    readonly __validatedDataMap: Record<string, any>,
+    // eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+    readonly __providerPaymentDataMap: Record<string, any>,
+    // eslint-disable-next-line jsdoc/require-jsdoc, typescript/no-explicit-any
+    readonly __providerReservationPaymentDataMap: Record<string, any>,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __cancellationSupportMap: Record<string, boolean>,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __refundSupportMap: Record<string, boolean>,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __reservationSupportMap: Record<string, boolean>,
     /**
-     * A map that defines which payment methods support cancellation.
+     * Validates the given payment data for the given method.
      */
-    readonly cancellationSupported: CancellationSupport,
+    // eslint-disable-next-line typescript/no-explicit-any
+    validatePaymentData: (method: any, data: any) => any,
     /**
-     * A map that defines which payment methods support refunding.
+     * Starts a new payment with the given method and data.
      */
-    readonly refundSupported: RefundSupport,
+    // eslint-disable-next-line typescript/no-explicit-any
+    startPayment: (method: any, data: any) => any,
     /**
-     * A map that defines which payment methods support reservation.
+     * Starts a new payment reservation with the given method and data.
      */
-    readonly reservationSupported: ReservationSupport,
+    // eslint-disable-next-line typescript/no-explicit-any
+    startPaymentReservation: (method: any, data: any) => any,
     /**
-     * Validates the given payment data for the given method.
+     * Confirms The given payment reservation. This does NOT move any money yet, it just reserves the funds.
      */
+    // eslint-disable-next-line typescript/no-explicit-any
+    confirmPaymentReservation: (payment: any) => any,
+    /**
+     * Confirms and finishes a payment.
+     */
+    // eslint-disable-next-line typescript/no-explicit-any
+    confirmPayment: (payment: any) => any,
+    /**
+     * Collects payment from the given payment reservation.
+     */
+    // eslint-disable-next-line typescript/no-explicit-any
+    collectPaymentFromReservation: (payment: any) => any,
+    /**
+     * Cancels the given payment.
+     */
+    // eslint-disable-next-line typescript/no-explicit-any
+    cancelPayment: (payment: any) => any,
+    /**
+     * Refunds the given payment.
+     */
+    // eslint-disable-next-line typescript/no-explicit-any
+    refundPayment: (payment: any) => any
+}
+
+/**
+ * Interface for a payment provider.
+ */
+export interface PaymentProviderInterface<
+    SupportedMethods extends readonly PaymentMethod[],
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    PaymentDataForMethod extends Record<SupportedMethods[number], AnyObject & { transactionId: string }>,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    ValidatedPaymentDataForMethod extends Record<SupportedMethods[number], AnyObject & { transactionId: string }>,
+    ProviderPaymentDataForMethod extends Record<SupportedMethods[number], AnyObject>,
+    ProviderReservationPaymentDataForMethod extends Record<SupportedMethods[number], AnyObject>,
+    CancellationSupport extends Record<SupportedMethods[number], boolean>,
+    RefundSupport extends Record<SupportedMethods[number], boolean>,
+    ReservationSupport extends Record<SupportedMethods[number], boolean>
+> extends AnyPaymentProviderInterface {
+    // phantom carriers — never set at runtime, only for type inference
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __supportedMethods: SupportedMethods,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __paymentDataMap: PaymentDataForMethod,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __validatedDataMap: ValidatedPaymentDataForMethod,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __providerPaymentDataMap: ProviderPaymentDataForMethod,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __providerReservationPaymentDataMap: ProviderReservationPaymentDataForMethod,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __cancellationSupportMap: CancellationSupport,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __refundSupportMap: RefundSupport,
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly __reservationSupportMap: ReservationSupport,
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
     validatePaymentData: <M extends SupportedMethods[number]>(
         method: M,
         data: PaymentDataForMethod[M]
     ) => ValidatedPaymentDataForMethod[M] | Promise<ValidatedPaymentDataForMethod[M]>,
-    /**
-     * Starts a new payment with the given method and data.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     startPayment: <M extends SupportedMethods[number]>(
         method: M,
         data: ValidatedPaymentDataForMethod[M]
     ) => Payment<M, ProviderPaymentDataForMethod[M]> | Promise<Payment<M, ProviderPaymentDataForMethod[M]>>,
-    /**
-     * Starts a new payment reservation with the given method and data.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     startPaymentReservation: <
         M extends {
             [K in SupportedMethods[number]]: ReservationSupport[K] extends true ? K : never
@@ -57,31 +120,23 @@ export interface PaymentProviderInterface<
         method: M,
         data: ValidatedPaymentDataForMethod[M]
     ) => Payment<M, ProviderReservationPaymentDataForMethod[M]> | Promise<Payment<M, ProviderReservationPaymentDataForMethod[M]>>,
-    /**
-     * Confirms The given payment reservation. This does NOT move any money yet, it just reserves the funds.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     confirmPaymentReservation: <
         M extends {
             [K in SupportedMethods[number]]: ReservationSupport[K] extends true ? K : never
         }[SupportedMethods[number]]
     >(payment: Payment<M, ProviderReservationPaymentDataForMethod[M]>) => void | Promise<void>,
-    /**
-     * Confirms and finishes a payment.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     confirmPayment: <M extends SupportedMethods[number]>(
         payment: Payment<M, ProviderPaymentDataForMethod[M]>
     ) => void | Promise<void>,
-    /**
-     * Collects payment from the given payment reservation.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     collectPaymentFromReservation: <
         M extends {
             [K in SupportedMethods[number]]: ReservationSupport[K] extends true ? K : never
         }[SupportedMethods[number]]
     >(payment: Payment<M, ProviderReservationPaymentDataForMethod[M]>) => void | Promise<void>,
-    /**
-     * Cancels the given payment.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     cancelPayment: <
         M extends {
             [K in SupportedMethods[number]]: CancellationSupport[K] extends true ? K : ReservationSupport[K] extends true ? K : never
@@ -89,9 +144,7 @@ export interface PaymentProviderInterface<
     >(
         payment: Payment<M, ProviderPaymentDataForMethod[M]> | Payment<M, ProviderReservationPaymentDataForMethod[M]>
     ) => void | Promise<void>,
-    /**
-     * Refunds the given payment.
-     */
+    // eslint-disable-next-line jsdoc/require-jsdoc
     refundPayment: <
         M extends {
             [K in SupportedMethods[number]]: RefundSupport[K] extends true ? K : never