cabloy 5.1.127 → 5.1.129

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentCallback.ts

@@ -0,0 +1,99 @@
+import type { TableIdentity } from 'table-identity';
+
+import { BeanBase } from 'vona';
+import { Service } from 'vona-module-a-bean';
+
+import type { EntityPaymentSession } from '../entity/paymentSession.tsx';
+
+type TypePaymentCallbackPurpose = 'return' | 'cancel';
+
+interface IPaymentCallbackState {
+  paymentSessionId: TableIdentity;
+  providerName: string;
+  clientName: string;
+  environment: 'sandbox' | 'live';
+  purpose: TypePaymentCallbackPurpose;
+  continuationPath: string;
+}
+
+@Service()
+export class ServicePaymentCallback extends BeanBase {
+  async createUrls(session: EntityPaymentSession) {
+    const continuationPath = await this._getContinuationPath(session);
+    return {
+      returnUrl: await this._createUrl(session, 'return', continuationPath),
+      cancelUrl: await this._createUrl(session, 'cancel', continuationPath),
+    };
+  }
+
+  async consume(
+    purpose: TypePaymentCallbackPurpose,
+    token: string | undefined,
+  ): Promise<IPaymentCallbackState> {
+    const path = `/pay/payment-callback/${purpose}`;
+    const state = (await this.bean.jwt.get('oauthstate').verify(token, { path })) as
+      | IPaymentCallbackState
+      | undefined;
+    if (
+      !state ||
+      state.purpose !== purpose ||
+      !this._isSafeContinuationPath(state.continuationPath)
+    ) {
+      this.app.throw(401, 'payment callback state is invalid');
+    }
+    const session = await this.scope.model.paymentSession.getById(state.paymentSessionId);
+    if (
+      !session ||
+      session.providerName !== state.providerName ||
+      session.clientName !== state.clientName ||
+      session.environment !== state.environment
+    ) {
+      this.app.throw(404, 'payment session not found');
+    }
+    return state;
+  }
+
+  private async _createUrl(
+    session: EntityPaymentSession,
+    purpose: TypePaymentCallbackPurpose,
+    continuationPath: string,
+  ) {
+    const path = `/pay/payment-callback/${purpose}`;
+    const continuationPathWithResult = `${continuationPath}?providerResult=${purpose}`;
+    const state = await this.bean.jwt.get('oauthstate').sign(
+      {
+        paymentSessionId: session.id,
+        providerName: session.providerName,
+        clientName: session.clientName,
+        environment: session.environment,
+        purpose,
+        continuationPath: continuationPathWithResult,
+      },
+      { path, expiresIn: '15m' },
+    );
+    this._assertTrustedOrigin();
+    const url = new URL(this.app.util.getAbsoluteUrlByApiPath(path));
+    url.searchParams.set('state', state);
+    return url.toString();
+  }
+
+  private async _getContinuationPath(session: EntityPaymentSession) {
+    const scene = this.bean.payScene.get(session.payScene as never);
+    const continuationPath = await scene.getPaymentCallbackPath(session);
+    if (!this._isSafeContinuationPath(continuationPath)) {
+      this.app.throw(500, 'payment scene returned an invalid callback continuation path');
+    }
+    return continuationPath;
+  }
+
+  private _assertTrustedOrigin() {
+    const { protocol, host } = this.app.config.server.serve;
+    if (!protocol || !host) {
+      this.app.throw(503, 'payment callbacks require configured server serve protocol and host');
+    }
+  }
+
+  private _isSafeContinuationPath(value: unknown): value is string {
+    return typeof value === 'string' && value.startsWith('/') && !value.startsWith('//');
+  }
+}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentSession.ts

@@ -20,6 +20,7 @@ export interface IPaymentSessionCreateCommand {
   amountMinor: number;
   currency: string;
   correlationId: string;
+  providerCandidateKey?: string;
 }
 
 @Service()
@@ -150,15 +151,37 @@ export class ServicePaymentSession extends BeanBase {
       return { session, changed: false };
     }
     if (['succeeded', 'failed', 'cancelled', 'expired'].includes(session.state)) {
+      if (
+        session.state === 'expired' &&
+        options.state === 'succeeded' &&
+        options.providerCaptureId
+      ) {
+        const finalizedAt = new Date();
+        await this.scope.model.paymentSession.updateById(session.id, {
+          providerPaymentId: options.providerPaymentId,
+          providerCaptureId: options.providerCaptureId,
+        });
+        await this.scope.model.paymentAudit.insert({
+          paymentSessionId: session.id,
+          webhookInboxId: options.webhookInboxId,
+          fromState: 'expired',
+          toState: 'expired',
+          correlationId: session.correlationId,
+          source: 'webhook.lateCapture',
+          occurredAt: finalizedAt,
+        });
+        return {
+          session: { ...session, ...options },
+          changed: true,
+          ignoredReason: 'late successful capture requires compensation',
+        };
+      }
       return {
         session,
         changed: false,
         ignoredReason: `terminal payment state ${options.state} ignored after ${session.state}`,
       };
     }
-    if (session.expiresAt <= new Date()) {
-      this.app.throw(409, 'payment session is expired');
-    }
     const finalizedAt = new Date();
     await this.scope.model.paymentSession.updateById(session.id, {
       state: options.state,

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/providerOperation.ts

@@ -7,7 +7,12 @@ import { Core } from 'vona-module-a-core';
 
 import type { EntityPaymentSession } from '../entity/paymentSession.tsx';
 import type { EntityProviderOperation } from '../entity/providerOperation.tsx';
-import type { IPayProviderPaymentSnapshot } from '../types/payment.ts';
+import type {
+  IPayProviderPaymentInput,
+  IPayProviderPaymentSnapshot,
+  IPayProviderRefundInput,
+  TypeProviderOperationKind,
+} from '../types/payment.ts';
 
 const ClaimLeaseMilliseconds = 60_000;
 const MaxAttempts = 10;
@@ -20,9 +25,29 @@ export class ServiceProviderOperation extends BeanBase {
       async () => {
         const operation = await this.ensureStart(paymentSessionId);
         await this.execute(operation.id);
-        const session = await this.scope.model.paymentSession.getById(paymentSessionId);
-        if (!session) this.app.throw(404, 'payment session not found');
-        return session;
+        return await this._getSession(paymentSessionId);
+      },
+    );
+  }
+
+  async confirm(paymentSessionId: TableIdentity): Promise<EntityPaymentSession> {
+    return await this.scope.redlock.lock(
+      `pay.providerOperation.confirm.${paymentSessionId}`,
+      async () => {
+        const operation = await this.ensureConfirm(paymentSessionId);
+        if (operation) await this.execute(operation.id);
+        return await this._getSession(paymentSessionId);
+      },
+    );
+  }
+
+  async reconcile(paymentSessionId: TableIdentity): Promise<EntityPaymentSession> {
+    return await this.scope.redlock.lock(
+      `pay.providerOperation.query.${paymentSessionId}`,
+      async () => {
+        const operation = await this.ensureQuery(paymentSessionId);
+        await this.execute(operation.id);
+        return await this._getSession(paymentSessionId);
       },
     );
   }
@@ -31,7 +56,6 @@ export class ServiceProviderOperation extends BeanBase {
   async ensureStart(paymentSessionId: TableIdentity): Promise<EntityProviderOperation> {
     const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
     if (!session) this.app.throw(404, 'payment session not found');
-
     const existing = await this.scope.model.providerOperation.getForUpdate({
       paymentSessionId: session.id,
       kind: 'start',
@@ -50,23 +74,62 @@ export class ServiceProviderOperation extends BeanBase {
       source: 'providerOperation.start',
       occurredAt: now,
     });
-    return await this.scope.model.providerOperation.insert({
+    return await this._insertOperation(session, 'start', `${session.correlationId}:start`, now);
+  }
+
+  @Core.transaction()
+  async ensureConfirm(
+    paymentSessionId: TableIdentity,
+  ): Promise<EntityProviderOperation | undefined> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (['succeeded', 'failed', 'cancelled', 'expired'].includes(session.state)) return undefined;
+    if (!session.providerOrderId) this.app.throw(409, 'payment session has no provider order');
+    if (session.providerCaptureId || session.state === 'processing') {
+      return await this._ensureQueryLocked(session);
+    }
+    const existing = await this.scope.model.providerOperation.getForUpdate({
       paymentSessionId: session.id,
-      kind: 'start',
-      state: 'created',
-      idempotencyKey: `${session.correlationId}:start`,
-      correlationId: session.correlationId,
-      attemptCount: 0,
-      nextAttemptAt: new Date(now.getTime() - 1_000),
+      kind: 'confirm',
     });
+    if (existing && !['succeeded', 'failed'].includes(existing.state)) return existing;
+    return await this._insertOperation(
+      session,
+      'confirm',
+      `${session.correlationId}:confirm`,
+      new Date(),
+    );
+  }
+
+  @Core.transaction()
+  async ensureQuery(paymentSessionId: TableIdentity): Promise<EntityProviderOperation> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (!session.providerOrderId && !session.providerCaptureId) {
+      this.app.throw(409, 'payment session has no provider resource to reconcile');
+    }
+    return await this._ensureQueryLocked(session);
+  }
+
+  private async _ensureQueryLocked(session: EntityPaymentSession) {
+    const existing = await this.scope.model.providerOperation.getForUpdate({
+      paymentSessionId: session.id,
+      kind: 'query',
+    });
+    if (existing && !['succeeded', 'failed'].includes(existing.state)) return existing;
+    return await this._insertOperation(
+      session,
+      'query',
+      `${session.correlationId}:query`,
+      new Date(),
+    );
   }
 
   async execute(providerOperationId: TableIdentity) {
     const operation = await this.claim(providerOperationId);
     if (!operation) return undefined;
     try {
-      const session = await this.scope.model.paymentSession.getById(operation.paymentSessionId);
-      if (!session) this.app.throw(404, 'payment session not found');
+      const session = await this._getSession(operation.paymentSessionId);
       const { provider, clientOptions } = this.bean.payProvider.resolveByName(
         session.providerName,
         session.clientName,
@@ -74,50 +137,11 @@ export class ServiceProviderOperation extends BeanBase {
       if (clientOptions.environment !== session.environment) {
         this.app.throw(500, 'payment session provider environment is inconsistent');
       }
-      const isReconciliation =
-        operation.state === 'reconciliation_required' ||
-        operation.state === 'claimed' ||
-        operation.state === 'submitted';
       await this.markSubmitted(operation.id, operation.claimToken!);
       if (operation.kind === 'refund') {
-        const refundOperationId = operation.refundOperationId;
-        if (!refundOperationId) this.app.throw(500, 'refund provider operation is not linked');
-        const refund = await this.scope.model.refundOperation.getById(refundOperationId);
-        if (!refund) this.app.throw(404, 'refund operation not found');
-        if (!session.providerCaptureId)
-          this.app.throw(409, 'payment session has no provider capture');
-        const input = {
-          paymentSessionId: session.id,
-          refundOperationId: refund.id,
-          businessReference: refund.businessReference,
-          idempotencyKey: operation.idempotencyKey,
-          amountMinor: refund.amountMinor,
-          currency: refund.currency,
-          providerCaptureId: session.providerCaptureId,
-        };
-        const snapshot =
-          isReconciliation && provider.queryRefund
-            ? await provider.queryRefund(input, clientOptions)
-            : await provider.createRefund(input, clientOptions);
-        await this.scope.service.refundOperation.settleProviderSnapshot(
-          operation.id,
-          operation.claimToken!,
-          snapshot,
-        );
-        return snapshot;
+        return await this._executeRefund(operation, session, provider, clientOptions);
       }
-      const input = {
-        paymentSessionId: session.id,
-        businessReference: session.businessReference,
-        idempotencyKey: operation.idempotencyKey,
-        amountMinor: session.amountMinor,
-        currency: session.currency,
-        providerOrderId: session.providerOrderId,
-      };
-      const snapshot =
-        operation.state === 'reconciliation_required'
-          ? await provider.queryPayment(input, clientOptions)
-          : await provider.startPayment(input, clientOptions);
+      const snapshot = await this._executePayment(operation, session, provider, clientOptions);
       await this.settlePaymentSnapshot(operation.id, operation.claimToken!, snapshot);
       return snapshot;
     } catch (error) {
@@ -126,6 +150,72 @@ export class ServiceProviderOperation extends BeanBase {
     }
   }
 
+  private async _executePayment(
+    operation: EntityProviderOperation,
+    session: EntityPaymentSession,
+    provider: ReturnType<typeof this.bean.payProvider.resolveByName>['provider'],
+    clientOptions: ReturnType<typeof this.bean.payProvider.resolveByName>['clientOptions'],
+  ) {
+    const callbackUrls =
+      operation.kind === 'start' && clientOptions.capabilities.redirectCheckout
+        ? await this.scope.service.paymentCallback.createUrls(session)
+        : undefined;
+    const input: IPayProviderPaymentInput = {
+      paymentSessionId: session.id,
+      businessReference: session.businessReference,
+      idempotencyKey: operation.idempotencyKey,
+      amountMinor: session.amountMinor,
+      currency: session.currency,
+      providerOrderId: session.providerOrderId,
+      ...callbackUrls,
+    };
+    if (operation.kind === 'start') {
+      return session.providerOrderId
+        ? await provider.queryPayment(input, clientOptions)
+        : await provider.startPayment(input, clientOptions);
+    }
+    if (operation.kind === 'confirm') {
+      return session.providerCaptureId
+        ? await provider.queryPayment(input, clientOptions)
+        : await provider.confirmPayment(input, clientOptions);
+    }
+    if (operation.kind === 'query') return await provider.queryPayment(input, clientOptions);
+    this.app.throw(500, `unsupported payment provider operation: ${operation.kind}`);
+  }
+
+  private async _executeRefund(
+    operation: EntityProviderOperation,
+    session: EntityPaymentSession,
+    provider: ReturnType<typeof this.bean.payProvider.resolveByName>['provider'],
+    clientOptions: ReturnType<typeof this.bean.payProvider.resolveByName>['clientOptions'],
+  ) {
+    const refundOperationId = operation.refundOperationId;
+    if (!refundOperationId) this.app.throw(500, 'refund provider operation is not linked');
+    const refund = await this.scope.model.refundOperation.getById(refundOperationId);
+    if (!refund) this.app.throw(404, 'refund operation not found');
+    if (!session.providerCaptureId) this.app.throw(409, 'payment session has no provider capture');
+    const input: IPayProviderRefundInput = {
+      paymentSessionId: session.id,
+      refundOperationId: refund.id,
+      businessReference: refund.businessReference,
+      idempotencyKey: operation.idempotencyKey,
+      amountMinor: refund.amountMinor,
+      currency: refund.currency,
+      providerCaptureId: session.providerCaptureId,
+      providerRefundId: refund.providerRefundId,
+    };
+    const snapshot =
+      refund.providerRefundId && provider.queryRefund
+        ? await provider.queryRefund(input, clientOptions)
+        : await provider.createRefund(input, clientOptions);
+    await this.scope.service.refundOperation.settleProviderSnapshot(
+      operation.id,
+      operation.claimToken!,
+      snapshot,
+    );
+    return snapshot;
+  }
+
   @Core.transaction()
   async claim(id: TableIdentity) {
     const operation = await this.scope.model.providerOperation.getByIdForUpdate(id);
@@ -161,7 +251,6 @@ export class ServiceProviderOperation extends BeanBase {
     });
     return {
       ...operation,
-      state: operation.state,
       claimedAt: now,
       claimToken,
       claimExpiresAt,
@@ -207,14 +296,18 @@ export class ServiceProviderOperation extends BeanBase {
       return session;
     }
 
+    const nextAction = snapshot.nextAction ?? session.nextAction;
+    const providerPaymentId = snapshot.providerPaymentId ?? session.providerPaymentId;
+    const providerOrderId = snapshot.providerOrderId ?? session.providerOrderId;
+    const providerCaptureId = snapshot.providerCaptureId ?? session.providerCaptureId;
     if (isTerminalPaymentState(snapshot.state)) {
       const finalizedAt = new Date();
       await this.scope.model.paymentSession.updateById(session.id, {
         state: snapshot.state,
-        nextAction: snapshot.nextAction,
-        providerPaymentId: snapshot.providerPaymentId,
-        providerOrderId: snapshot.providerOrderId,
-        providerCaptureId: snapshot.providerCaptureId,
+        nextAction,
+        providerPaymentId,
+        providerOrderId,
+        providerCaptureId,
         finalizedAt,
       });
       await this.scope.model.paymentAudit.insert({
@@ -223,7 +316,7 @@ export class ServiceProviderOperation extends BeanBase {
         fromState: session.state,
         toState: snapshot.state,
         correlationId: session.correlationId,
-        source: 'providerOperation',
+        source: `providerOperation.${operation.kind}`,
         occurredAt: finalizedAt,
       });
       await this.scope.service.outbox.enqueue(session.id, 'payment.outcome.v1', {
@@ -232,17 +325,17 @@ export class ServiceProviderOperation extends BeanBase {
         businessReference: session.businessReference,
         providerName: session.providerName,
         state: snapshot.state,
-        providerCaptureId: snapshot.providerCaptureId,
+        providerCaptureId,
         amountMinor: session.amountMinor,
         currency: session.currency,
       });
     } else {
       await this.scope.model.paymentSession.updateById(session.id, {
         state: snapshot.state,
-        nextAction: snapshot.nextAction,
-        providerPaymentId: snapshot.providerPaymentId,
-        providerOrderId: snapshot.providerOrderId,
-        providerCaptureId: snapshot.providerCaptureId,
+        nextAction,
+        providerPaymentId,
+        providerOrderId,
+        providerCaptureId,
       });
       await this.scope.model.paymentAudit.insert({
         paymentSessionId: session.id,
@@ -250,14 +343,23 @@ export class ServiceProviderOperation extends BeanBase {
         fromState: session.state,
         toState: snapshot.state,
         correlationId: session.correlationId,
-        source: 'providerOperation',
+        source: `providerOperation.${operation.kind}`,
         occurredAt: new Date(),
       });
     }
-    await this._complete(operation, {
-      providerResourceId: snapshot.providerCaptureId ?? snapshot.providerOrderId,
-    });
-    return { ...session, ...snapshot };
+    if (snapshot.state === 'processing' && ['confirm', 'query'].includes(operation.kind)) {
+      await this._scheduleReconciliation(operation, providerCaptureId ?? providerOrderId);
+    } else {
+      await this._complete(operation, { providerResourceId: providerCaptureId ?? providerOrderId });
+    }
+    return {
+      ...session,
+      ...snapshot,
+      nextAction,
+      providerPaymentId,
+      providerOrderId,
+      providerCaptureId,
+    };
   }
 
   @Core.transaction()
@@ -298,10 +400,7 @@ export class ServiceProviderOperation extends BeanBase {
   async queueDue(limit = 100) {
     const now = new Date();
     const due = await this.scope.model.providerOperation.select({
-      where: {
-        state: ['created', 'reconciliation_required'],
-        nextAttemptAt: { _lte_: now },
-      },
+      where: { state: ['created', 'reconciliation_required'], nextAttemptAt: { _lte_: now } },
       orders: [
         ['nextAttemptAt', 'asc'],
         ['id', 'asc'],
@@ -309,10 +408,7 @@ export class ServiceProviderOperation extends BeanBase {
       limit,
     });
     const expiredClaims = await this.scope.model.providerOperation.select({
-      where: {
-        state: ['claimed', 'submitted'],
-        claimExpiresAt: { _lte_: now },
-      },
+      where: { state: ['claimed', 'submitted'], claimExpiresAt: { _lte_: now } },
       orders: [
         ['claimExpiresAt', 'asc'],
         ['id', 'asc'],
@@ -320,12 +416,48 @@ export class ServiceProviderOperation extends BeanBase {
       limit: Math.max(0, limit - due.length),
     });
     const operations = [...due, ...expiredClaims];
-    for (const operation of operations) {
-      await this.execute(operation.id);
-    }
+    for (const operation of operations) await this.execute(operation.id);
     return operations.length;
   }
 
+  private async _insertOperation(
+    session: EntityPaymentSession,
+    kind: Exclude<TypeProviderOperationKind, 'refund'>,
+    idempotencyKey: string,
+    now: Date,
+  ) {
+    return await this.scope.model.providerOperation.insert({
+      paymentSessionId: session.id,
+      kind,
+      state: 'created',
+      idempotencyKey,
+      correlationId: session.correlationId,
+      attemptCount: 0,
+      nextAttemptAt: new Date(now.getTime() - 1_000),
+    });
+  }
+
+  private async _getSession(paymentSessionId: TableIdentity) {
+    const session = await this.scope.model.paymentSession.getById(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+    return session;
+  }
+
+  private async _scheduleReconciliation(
+    operation: EntityProviderOperation,
+    providerResourceId?: string,
+  ) {
+    await this.scope.model.providerOperation.updateById(operation.id, {
+      state: 'reconciliation_required',
+      providerResourceId,
+      claimToken: undefined,
+      claimExpiresAt: undefined,
+      nextAttemptAt: new Date(Date.now() + 5_000),
+      errorCode: undefined,
+      errorSummary: undefined,
+    });
+  }
+
   private async _complete(
     operation: EntityProviderOperation,
     options: { providerResourceId?: string },

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/refundOperation.ts

@@ -27,12 +27,20 @@ export class ServiceRefundOperation extends BeanBase {
       command.paymentSessionId,
     );
     if (!session) this.app.throw(404, 'payment session not found');
-    if (session.state !== 'succeeded' || !session.providerCaptureId) {
+    const isLateCaptureCompensation = command.businessReference.startsWith('late-capture:');
+    if (
+      (session.state !== 'succeeded' &&
+        !(session.state === 'expired' && isLateCaptureCompensation)) ||
+      !session.providerCaptureId
+    ) {
       this.app.throw(409, 'payment session is not refundable');
     }
     if (session.currency !== command.currency) this.app.throw(409, 'refund currency conflicts');
     const scene = this.bean.payScene.getOptions(session.payScene as never);
     if (!scene.refund?.enabled) this.app.throw(409, 'payment scene refunds are disabled');
+    if (isLateCaptureCompensation && command.amountMinor !== session.amountMinor) {
+      this.app.throw(422, 'late capture compensation must refund the full captured amount');
+    }
     if (!scene.refund.allowPartial && command.amountMinor !== session.amountMinor) {
       this.app.throw(422, 'payment scene does not allow partial refunds');
     }
@@ -143,8 +151,10 @@ export class ServiceRefundOperation extends BeanBase {
         amountMinor: refund.amountMinor,
         currency: refund.currency,
       });
+      await this._completeProviderOperation(providerOperation, snapshot.providerRefundId);
+    } else {
+      await this._scheduleReconciliation(providerOperation, snapshot.providerRefundId);
     }
-    await this._completeProviderOperation(providerOperation, snapshot.providerRefundId);
     return { ...refund, ...snapshot, finalizedAt };
   }
 
@@ -202,6 +212,21 @@ export class ServiceRefundOperation extends BeanBase {
     };
   }
 
+  private async _scheduleReconciliation(
+    providerOperation: { id: TableIdentity },
+    providerResourceId?: string,
+  ) {
+    await this.scope.model.providerOperation.updateById(providerOperation.id, {
+      state: 'reconciliation_required',
+      providerResourceId,
+      claimToken: undefined,
+      claimExpiresAt: undefined,
+      nextAttemptAt: new Date(Date.now() + 5_000),
+      errorCode: undefined,
+      errorSummary: undefined,
+    });
+  }
+
   private async _completeProviderOperation(
     providerOperation: { id: TableIdentity },
     providerResourceId?: string,

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/types/payScene.ts

@@ -2,12 +2,14 @@ import type { TableIdentity } from 'table-identity';
 import type { OmitNever, VonaContext } from 'vona';
 import type { ServiceOnion } from 'vona-module-a-onion';
 
+import type { EntityPaymentSession } from '../entity/paymentSession.tsx';
 import type { IPaymentOutcomeEvent, IRefundOutcomeEvent } from './payment.ts';
 import type { IPayProviderRecord } from './payProvider.ts';
 
 export interface IPaySceneExecute {
   onPaymentOutcome(event: IPaymentOutcomeEvent): Promise<void>;
   onRefundOutcome(event: IRefundOutcomeEvent): Promise<void>;
+  getPaymentCallbackPath(session: EntityPaymentSession): Promise<string>;
 }
 
 export interface IPaySceneRecord {}
@@ -27,6 +29,7 @@ export interface IPaySceneResolveProviderInput {
   businessReference: string;
   amountMinor: number;
   currency: string;
+  providerCandidateKey?: string;
   providers: readonly IPaySceneProviderCandidate[];
 }
 
@@ -35,8 +38,14 @@ export type TypePaySceneResolveProvider = (
   input: IPaySceneResolveProviderInput,
 ) => string | Promise<string>;
 
+export type TypePaySceneIsProviderAvailable = (
+  ctx: VonaContext,
+  input: IPaySceneResolveProviderInput & { candidate: IPaySceneProviderCandidate },
+) => boolean | Promise<boolean>;
+
 export interface IDecoratorPaySceneOptions {
   providers?: readonly IPaySceneProviderCandidate[];
+  isProviderAvailable?: TypePaySceneIsProviderAvailable;
   resolveProvider?: TypePaySceneResolveProvider;
   currencies?: readonly string[];
   captureMode?: 'automatic' | 'manual';

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/types/payment.ts

@@ -70,6 +70,7 @@ export interface IPayProviderRefundInput extends IPayMoney {
   businessReference: string;
   idempotencyKey: string;
   providerCaptureId: string;
+  providerRefundId?: string;
 }
 
 export interface IPayProviderPaymentSnapshot {
@@ -113,6 +114,10 @@ export interface IPayProviderExecute<
     input: IPayProviderPaymentInput,
     clientOptions: TClientOptions,
   ): Promise<IPayProviderPaymentSnapshot>;
+  confirmPayment(
+    input: IPayProviderPaymentInput,
+    clientOptions: TClientOptions,
+  ): Promise<IPayProviderPaymentSnapshot>;
   queryPayment(
     input: IPayProviderPaymentInput,
     clientOptions: TClientOptions,

package/vona/src/suite-vendor/a-pay/modules/pay-mock/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-pay-mock",
-  "version": "5.0.3",
+  "version": "5.0.4",
   "description": "",
   "keywords": [
     "Vona Module"