@munchi_oy/payments 1.6.10 → 1.10.0

package/dist/src/types/sdk.d.ts

@@ -59,5 +59,14 @@ export interface SDKOptions {
      */
     autoResetOnPaymentComplete?: AutoResetOptions;
     appToApp?: AppToAppConfig;
+    /**
+     * Routes POS Viva payments through the backend payment-session flow
+     * (VivaSessionStrategy) instead of the legacy v4 VivaStrategy. Kiosk/handheld
+     * leave this unset and stay on the legacy flow.
+     */
+    paymentSession?: PaymentSessionConfig;
+}
+export interface PaymentSessionConfig {
+    enabled: boolean;
 }
 //# sourceMappingURL=sdk.d.ts.map

package/dist/src/types/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/types/sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACnD,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACtD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACnD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAClD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AACvD,MAAM,MAAM,2BAA2B,GAAG,UAAU,GAAG,aAAa,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvD,aAAa,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;IAClD,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,0BAA0B,CAAC,EAAE,gBAAgB,CAAC;IAC9C,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/types/sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACnD,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACtD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACnD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAClD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AACvD,MAAM,MAAM,2BAA2B,GAAG,UAAU,GAAG,aAAa,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvD,aAAa,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;IAClD,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,0BAA0B,CAAC,EAAE,gBAAgB,CAAC;IAC9C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.6.10";
+export declare const VERSION = "1.10.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@munchi_oy/payments",
-  "version": "1.6.10",
+  "version": "1.10.0",
   "description": "Munchi Payments SDK - Payment processing utilities",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@types/jest": "^30.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "@munchi_oy/core": "1.9.11"
+    "@munchi_oy/core": "1.9.38"
   },
   "scripts": {
     "test": "jest",

package/src/MunchiPaymentSDK.ts

@@ -4,13 +4,16 @@ import { version } from "../package.json";
 import { PaymentErrorCode, PaymentSDKError } from "./error";
 import type { IPaymentStrategy } from "./strategies/IPaymentStrategy";
 import { StrategyExecutionMode } from "./strategies/IPaymentStrategy";
+import { ManualSessionStrategy } from "./strategies/ManualSessionStrategy";
 import { NetsStrategy } from "./strategies/NetsStrategy";
 import { VivaAppToAppStrategy } from "./strategies/VivaAppToAppStrategy";
+import { VivaSessionStrategy } from "./strategies/VivaSessionStrategy";
 import { VivaStrategy } from "./strategies/VivaStrategy";
 import { WorldlineStrategy } from "./strategies/WorldlineStrategy";
 import {
   type IMessagingAdapter,
   type IMunchiPaymentSDK,
+  type ManualPaymentRequest,
   PaymentInteractionState,
   type PaymentResult,
   type PaymentTerminalConfig,
@@ -18,8 +21,14 @@ import {
   type PaymentRequest as SdkPaymentRequest,
   SdkPaymentStatus,
   type TransactionOptions,
+  type VoidRequest,
 } from "./types/payment";
-import type { AppToAppConfig, ILogger, SDKOptions } from "./types/sdk";
+import type {
+  AppToAppConfig,
+  ILogger,
+  PaymentSessionConfig,
+  SDKOptions,
+} from "./types/sdk";
 
 type StateListener = (state: PaymentInteractionState) => void;
 
@@ -36,6 +45,8 @@ export class MunchiPaymentSDK implements IMunchiPaymentSDK {
   private _autoResetTimer: ReturnType<typeof setTimeout> | undefined;
   private autoResetOptions: SDKOptions["autoResetOnPaymentComplete"];
   private appToAppConfig: AppToAppConfig | undefined;
+  private paymentSessionConfig: PaymentSessionConfig | undefined;
+  private manualStrategy: ManualSessionStrategy;
 
   private static readonly TERMINAL_STATES = [
     PaymentInteractionState.SUCCESS,
@@ -61,6 +72,8 @@ export class MunchiPaymentSDK implements IMunchiPaymentSDK {
     this.timeoutMs = options.timeoutMs || 30000;
     this.autoResetOptions = options.autoResetOnPaymentComplete;
     this.appToAppConfig = options.appToApp;
+    this.paymentSessionConfig = options.paymentSession;
+    this.manualStrategy = new ManualSessionStrategy(axios, config);
     this.strategy = strategy ?? this.resolveStrategy(config);
   }
 
@@ -200,6 +213,9 @@ export class MunchiPaymentSDK implements IMunchiPaymentSDK {
             this.appToAppConfig,
           );
         }
+        if (this.paymentSessionConfig?.enabled) {
+          return new VivaSessionStrategy(this.axios, this.messaging, config);
+        }
         return new VivaStrategy(this.axios, this.messaging, config);
 
       default:
@@ -645,4 +661,118 @@ export class MunchiPaymentSDK implements IMunchiPaymentSDK {
       return errorResult;
     }
   };
+
+  public recordManualPayment = async (
+    params: ManualPaymentRequest,
+    options?: TransactionOptions,
+  ): Promise<PaymentResult> => {
+    const callbacks = options ?? {};
+    this.logger?.info("Recording manual payment", {
+      orderRef: params.orderRef,
+    });
+    this._currentSessionId = undefined;
+    this._cancellationIntent = false;
+
+    if (!MunchiPaymentSDK.RESTING_STATES.includes(this._currentState)) {
+      return this.generateErrorResult(
+        params.orderRef,
+        PaymentErrorCode.UNKNOWN,
+        "A transaction is already in progress",
+      );
+    }
+
+    this.transitionTo(PaymentInteractionState.CONNECTING);
+    this.safeFireCallback(() =>
+      callbacks.onConnecting?.({
+        orderRef: params.orderRef,
+        refPaymentId: undefined,
+      }),
+    );
+
+    try {
+      const result = await this.manualStrategy.recordPayment(params);
+      this.settleSingleShot(result, params.orderRef, callbacks);
+      return result;
+    } catch (error) {
+      this.logger?.error("Manual payment failed", error);
+      return this.failSingleShot(
+        params.orderRef,
+        error,
+        "Manual payment failed",
+        callbacks,
+      );
+    }
+  };
+
+  public voidManualPayment = async (
+    params: VoidRequest,
+    options?: TransactionOptions,
+  ): Promise<PaymentResult> => {
+    const callbacks = options ?? {};
+    this.logger?.info("Voiding manual payment", { orderRef: params.orderRef });
+    this._currentSessionId = params.sessionId;
+    this._cancellationIntent = false;
+
+    if (!MunchiPaymentSDK.RESTING_STATES.includes(this._currentState)) {
+      return this.generateErrorResult(
+        params.orderRef,
+        PaymentErrorCode.UNKNOWN,
+        "A transaction is already in progress",
+      );
+    }
+
+    this.transitionTo(PaymentInteractionState.CONNECTING);
+
+    try {
+      const result = await this.manualStrategy.voidPayment(params);
+      this.settleSingleShot(result, params.orderRef, callbacks);
+      return result;
+    } catch (error) {
+      this.logger?.error("Manual void failed", error);
+      return this.failSingleShot(
+        params.orderRef,
+        error,
+        "Void failed",
+        callbacks,
+      );
+    }
+  };
+
+  private settleSingleShot(
+    result: PaymentResult,
+    orderRef: string,
+    callbacks: TransactionOptions,
+  ): void {
+    if (result.success) {
+      this.transitionTo(PaymentInteractionState.SUCCESS);
+      this.safeFireCallback(() => callbacks.onSuccess?.(result));
+    } else if (result.status === SdkPaymentStatus.CANCELLED) {
+      this.transitionTo(PaymentInteractionState.FAILED);
+      this.safeFireCallback(() =>
+        callbacks.onCancelled?.({
+          orderRef,
+          refPaymentId: this._currentSessionId,
+        }),
+      );
+    } else {
+      this.transitionTo(PaymentInteractionState.FAILED);
+      this.safeFireCallback(() => callbacks.onError?.(result));
+    }
+  }
+
+  private failSingleShot(
+    orderRef: string,
+    error: unknown,
+    fallbackMessage: string,
+    callbacks: TransactionOptions,
+  ): PaymentResult {
+    const errorResult = this.generateErrorResult(
+      orderRef,
+      PaymentErrorCode.NETWORK_ERROR,
+      error instanceof Error ? error.message : fallbackMessage,
+    );
+    this.transitionTo(PaymentInteractionState.FAILED);
+    this.safeFireCallback(() => callbacks.onError?.(errorResult));
+    return errorResult;
+  }
 }

package/src/strategies/ManualSessionStrategy.ts

@@ -0,0 +1,93 @@
+import {
+  type CreateManualSessionDto,
+  PaymentSessionApi,
+  PaymentSessionStatus,
+} from "@munchi_oy/core";
+import type { AxiosInstance } from "axios";
+
+import { PaymentErrorCode, PaymentSDKError } from "../error";
+import {
+  type ManualPaymentRequest,
+  type PaymentResult,
+  type PaymentTerminalConfig,
+  SdkPaymentStatus,
+  type VoidRequest,
+} from "../types/payment";
+import { mapSessionResult } from "./sessionResult";
+
+export class ManualSessionStrategy {
+  private sessionApi: PaymentSessionApi;
+
+  constructor(
+    axios: AxiosInstance,
+    private config: PaymentTerminalConfig,
+  ) {
+    this.sessionApi = new PaymentSessionApi(undefined, "", axios);
+  }
+
+  async recordPayment(request: ManualPaymentRequest): Promise<PaymentResult> {
+    try {
+      const payload: CreateManualSessionDto = {
+        businessId: Number(this.config.storeId),
+        orderId: request.orderRef,
+        amount: request.amountCents,
+        paymethod: request.paymethod,
+        provider: this.config.provider,
+      };
+      if (request.tipAmount !== undefined) {
+        payload.tipAmount = request.tipAmount;
+      }
+      if (request.splitContext !== undefined) {
+        payload.splitContext = request.splitContext;
+      }
+      if (request.metadata !== undefined) {
+        payload.metadata = request.metadata;
+      }
+
+      const { data } = await this.sessionApi.recordManualPayment(payload);
+      return mapSessionResult(data, request.orderRef);
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to record manual payment",
+        error,
+      );
+    }
+  }
+
+  async voidPayment(request: VoidRequest): Promise<PaymentResult> {
+    try {
+      const { data } = await this.sessionApi.voidManualPayment({
+        sessionId: request.sessionId,
+      });
+
+      const isVoided =
+        data.status === PaymentSessionStatus.Voided ||
+        data.status === PaymentSessionStatus.Voiding;
+
+      const result: PaymentResult = {
+        success: isVoided,
+        status: isVoided ? SdkPaymentStatus.SUCCESS : SdkPaymentStatus.FAILED,
+        orderId: request.orderRef,
+        transactionId: data.providerTransactionId ?? data.sessionId,
+      };
+
+      if (!isVoided) {
+        if (data.errorCode) {
+          result.errorCode = data.errorCode;
+        }
+        if (data.errorMessage) {
+          result.errorMessage = data.errorMessage;
+        }
+      }
+
+      return result;
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to void manual payment",
+        error,
+      );
+    }
+  }
+}

package/src/strategies/VivaSessionStrategy.ts

@@ -0,0 +1,367 @@
+import {
+  type InitiateVivaSessionDto,
+  PaymentFailureCode,
+  PaymentSessionApi,
+  PaymentSessionStatus,
+  type PaymentSessionViewDto,
+  type PaymentStatusDto,
+  type ReverseSessionDto,
+  SimplePaymentStatus,
+  type TransactionDto,
+} from "@munchi_oy/core";
+import type { AxiosInstance } from "axios";
+
+import { PaymentErrorCode, PaymentSDKError } from "../error";
+import {
+  type IMessagingAdapter,
+  type PaymentInteractionState,
+  PaymentInteractionState as InteractionState,
+  type PaymentRequest,
+  type PaymentResult,
+  type PaymentTerminalConfig,
+  type RefundRequest,
+  SdkPaymentStatus,
+} from "../types/payment";
+import type { IPaymentStrategy } from "./IPaymentStrategy";
+import { mapSessionResult, pendingResult } from "./sessionResult";
+
+export class VivaSessionStrategy implements IPaymentStrategy {
+  private static readonly POLLING_DURATION_MS = 180000;
+  private static readonly POLLING_INTERVAL_MS = 1000;
+  private static readonly VERIFY_DURATION_MS = 30000;
+  private static readonly INITIAL_POLL_DELAY_MS = 10000;
+
+  private sessionApi: PaymentSessionApi;
+  private abortController: AbortController | null = null;
+  private idempotencyKey: string | null = null;
+  private idempotencyOrderRef: string | null = null;
+  private currentClientToken: string | null = null;
+
+  constructor(
+    axios: AxiosInstance,
+    private messaging: IMessagingAdapter,
+    private config: PaymentTerminalConfig,
+  ) {
+    this.sessionApi = new PaymentSessionApi(undefined, "", axios);
+  }
+
+  async processPayment(
+    request: PaymentRequest,
+    onStateChange: (state: PaymentInteractionState, detail?: { sessionId?: string }) => void,
+  ): Promise<PaymentResult> {
+    this.abortController = new AbortController();
+    if (
+      this.idempotencyKey === null ||
+      this.idempotencyOrderRef !== request.orderRef
+    ) {
+      this.idempotencyKey = this.generateIdempotencyKey();
+      this.idempotencyOrderRef = request.orderRef;
+    }
+    this.currentClientToken = null;
+
+    onStateChange(InteractionState.CONNECTING);
+
+    const payload: InitiateVivaSessionDto = {
+      amount: request.amountCents,
+      businessId: Number(this.config.storeId),
+      orderId: request.orderRef,
+    };
+    if (request.splitContext !== undefined) {
+      payload.splitContext = request.splitContext;
+    }
+
+    try {
+      const { data } = await this.sessionApi.initiateVivaSession(
+        payload,
+        this.idempotencyKey,
+      );
+      this.currentClientToken = data.clientToken;
+      const signal = this.abortController.signal;
+
+      if (signal.aborted) {
+        throw new Error("Aborted");
+      }
+
+      onStateChange(InteractionState.REQUIRES_INPUT, { sessionId: data.sessionId });
+
+      const terminal = await this.waitForCompletion(
+        data.clientToken,
+        data.sessionId,
+        request,
+        signal,
+      );
+
+      if (terminal) {
+        return this.finalize(terminal);
+      }
+
+      await this.armCancel(data.clientToken);
+      return pendingResult(request.orderRef);
+    } catch (err) {
+      if (err instanceof PaymentSDKError) throw err;
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to create Viva payment session",
+        err,
+      );
+    }
+  }
+
+  async verifyFinalStatus(
+    request: PaymentRequest,
+    _sessionId: string,
+  ): Promise<PaymentResult> {
+    if (!this.currentClientToken) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "No active payment session to verify",
+      );
+    }
+
+    const terminal = await this.pollUntilTerminal(
+      this.currentClientToken,
+      request,
+      undefined,
+      VivaSessionStrategy.VERIFY_DURATION_MS,
+    );
+
+    return this.finalize(terminal ?? pendingResult(request.orderRef));
+  }
+
+  async cancelTransaction(
+    _onStateChange: (state: PaymentInteractionState) => void,
+  ): Promise<boolean> {
+    if (!this.currentClientToken) {
+      return false;
+    }
+
+    try {
+      await this.sessionApi.cancelVivaSession(this.currentClientToken);
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to cancel Viva payment session",
+        error,
+      );
+    }
+
+    this.abortController?.abort();
+    return true;
+  }
+
+  async refundTransaction(
+    request: RefundRequest,
+    _onStateChange: (state: PaymentInteractionState, detail?: { sessionId?: string }) => void,
+  ): Promise<PaymentResult> {
+    try {
+      const payload: ReverseSessionDto = {
+        sessionId: request.originalTransactionId,
+        amount: request.amountCents,
+      };
+
+      const { data } = await this.sessionApi.refundVivaSession(payload);
+
+      const isRefunded =
+        data.status === PaymentSessionStatus.Refunded ||
+        data.status === PaymentSessionStatus.Refunding;
+
+      const result: PaymentResult = {
+        success: isRefunded,
+        status: isRefunded ? SdkPaymentStatus.SUCCESS : SdkPaymentStatus.FAILED,
+        orderId: request.orderRef,
+        transactionId: data.providerTransactionId ?? data.sessionId,
+      };
+
+      if (!isRefunded) {
+        if (data.errorCode) result.errorCode = data.errorCode;
+        if (data.errorMessage) result.errorMessage = data.errorMessage;
+      }
+
+      return result;
+    } catch (error) {
+      throw new PaymentSDKError(
+        PaymentErrorCode.NETWORK_ERROR,
+        "Failed to refund Viva transaction",
+        error,
+      );
+    }
+  }
+
+  abort(): void {
+    this.abortController?.abort();
+  }
+
+  private async pollUntilTerminal(
+    clientToken: string,
+    request: PaymentRequest,
+    signal: AbortSignal | undefined,
+    durationMs: number,
+  ): Promise<PaymentResult | undefined> {
+    const deadline = Date.now() + durationMs;
+
+    while (Date.now() < deadline) {
+      if (signal?.aborted) {
+        throw new Error("Aborted");
+      }
+
+      let data: PaymentSessionViewDto | undefined;
+      try {
+        data = (await this.sessionApi.getPaymentSession(clientToken)).data;
+      } catch (error) {
+        if (error instanceof Error && error.message === "Aborted") throw error;
+      }
+
+      if (signal?.aborted) {
+        throw new Error("Aborted");
+      }
+
+      if (data) {
+        const result = mapSessionResult(data, request.orderRef);
+        if (result.status !== SdkPaymentStatus.PENDING) {
+          return result;
+        }
+      }
+
+      await this.delay(VivaSessionStrategy.POLLING_INTERVAL_MS, signal);
+    }
+
+    return undefined;
+  }
+
+  private waitForCompletion(
+    clientToken: string,
+    sessionId: string,
+    request: PaymentRequest,
+    signal: AbortSignal,
+  ): Promise<PaymentResult | undefined> {
+    const channelName = `viva.${this.config.channel.toLowerCase()}.requests.${sessionId}`;
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+
+      const cleanup = () => {
+        settled = true;
+        if (typeof unsubscribe === "function") unsubscribe();
+        clearTimeout(pollTimer);
+        signal.removeEventListener("abort", onAbort);
+      };
+
+      const onAbort = () => {
+        cleanup();
+        reject(new Error("Aborted"));
+      };
+      signal.addEventListener("abort", onAbort);
+
+      const unsubscribe = this.messaging.subscribe<PaymentStatusDto>(
+        channelName,
+        "payment:status-changed",
+        (data: PaymentStatusDto) => {
+          if (settled) return;
+          if (data.status === SimplePaymentStatus.Pending) return;
+          cleanup();
+          resolve(this.mapStatusDto(data, request));
+        },
+      );
+
+      const pollTimer = setTimeout(() => {
+        if (settled) return;
+        this.pollUntilTerminal(
+          clientToken,
+          request,
+          signal,
+          VivaSessionStrategy.POLLING_DURATION_MS,
+        ).then(
+          (result) => {
+            if (settled) return;
+            cleanup();
+            resolve(result);
+          },
+          (error) => {
+            if (settled) return;
+            cleanup();
+            reject(error);
+          },
+        );
+      }, VivaSessionStrategy.INITIAL_POLL_DELAY_MS);
+    });
+  }
+
+  private mapStatusDto(
+    data: PaymentStatusDto,
+    request: PaymentRequest,
+  ): PaymentResult {
+    const isSuccess = data.status === SimplePaymentStatus.Success;
+
+    const result: PaymentResult = {
+      success: isSuccess,
+      status: isSuccess ? SdkPaymentStatus.SUCCESS : SdkPaymentStatus.FAILED,
+      orderId: request.orderRef,
+      errorCode:
+        data.error?.code || (isSuccess ? "" : PaymentFailureCode.SystemUnknown),
+      errorMessage:
+        data.error?.message ||
+        (isSuccess ? "" : "Transaction failed without error details"),
+    };
+
+    if (data.transactionId) {
+      result.transactionId = data.transactionId;
+    }
+    if (data.error?.referenceError) {
+      result.errorReference = data.error.referenceError;
+    }
+    if (data.transaction) {
+      result.transaction = data.transaction as unknown as TransactionDto;
+    }
+
+    return result;
+  }
+
+  private finalize(result: PaymentResult): PaymentResult {
+    if (result.status !== SdkPaymentStatus.PENDING) {
+      this.idempotencyKey = null;
+      this.idempotencyOrderRef = null;
+    }
+    return result;
+  }
+
+  private armCancel(clientToken: string): Promise<void> {
+    return this.sessionApi.cancelVivaSession(clientToken).then(
+      () => undefined,
+      () => undefined,
+    );
+  }
+
+  private generateIdempotencyKey(): string {
+    const cryptoRef = (
+      globalThis as { crypto?: { randomUUID?: () => string } }
+    ).crypto;
+
+    if (cryptoRef?.randomUUID) {
+      return cryptoRef.randomUUID();
+    }
+
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+      const random = (Math.random() * 16) | 0;
+      const value = char === "x" ? random : (random & 0x3) | 0x8;
+      return value.toString(16);
+    });
+  }
+
+  private delay(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      const onAbort = () => {
+        clearTimeout(timeout);
+        resolve();
+      };
+      if (signal) {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      const timeout = setTimeout(() => {
+        if (signal) {
+          signal.removeEventListener("abort", onAbort);
+        }
+        resolve();
+      }, ms);
+    });
+  }
+}