Context

Currently, when a user cancels a payment via a popup, the backend returns a generic error known as PAYMENT_ERROR. This results in a frontend message that does not accurately reflect the reason for the cancellation. The generic nature of this error prevents customization of the message, meaning that any changes would mislead users about the nature of other errors sharing the same code.

To improve user communication, it is crucial for the backend to return a specific cancellation code. This aligns with the new error detail model established in the RFC-056 and /wiki/spaces/IN/pages/4550328658.

Implementing this will ensure that users receive accurate messages regarding payment cancellations.

This will ensure that the correct message (backend to frontend - Graphql to Whitelabel) regarding payment cancellations is presented to the user.

{
  "level": 30,
  "level_label": "info",
  "time": 1727697392706,
  "brand": "plk",
  "stage": "dev",
  "name": "sls-rbi-dev-plk-orders-order-mutated-event",
  "region": "ES",
  "awsRequestId": "10991d85-1069-5934-97a2-42f18441f643",
  "x-correlation-trace-id": "Root=1-66fa91f0-65e75dec77174e9bdc6e26c8;Parent=411e9b430adb915f;Sampled=0;Lineage=2:9dbad0c9:0",
  "x-correlation-id": "10991d85-1069-5934-97a2-42f18441f643",
  "isTestOrder": false,
  "platform": "web",
  "posOrderId": "3151c4e5-9b37-48ac-8b3b-1f610b972b32",
  "posVendor": "PARTNER",
  "rbiOrderId": "25f33541-7f42-4081-8ce6-5d660952de2d",
  "region": "ES",
  "serviceMode": "TAKEOUT",
  "storeId": "005484",
  "userId": "33e0e0ff-ad43-47de-ac83-18196fc8c7c5",
  "newStatus": "PAYMENT_ERROR",
  "previousStatus": "PRICE_SUCCESSFUL",
  "msg": "Transitioning order status PRICE_SUCCESSFUL to PAYMENT_ERROR"
}

✅ Proposed Solution

Instead of solely returning the generic PAYMENT_ERROR, the backend will provide a specific cancellation code.

This enhancement will allow the frontend to display more informative and contextually appropriate error messages, thus improving clarity and the overall user experience.

Backend

The cancel code will be 2.005 for all processing popup cancellations.

After the solution is approved, it will add the code error on: /wiki/spaces/RWLAPPwiki/pages/4858741214

The Strategies solution: /wiki/spaces/TRX/pages/4464050308

Workflow

intl-packages

• Create a new constants error:

  • path: intl-packages/packages/psp-base/src/errors/psp-error-2/psp-error-2.ts

    const GenericRbiPaymentErrorCodes = {
      ...
      OPERATION_CANCELLED_ERROR: '2.005',
      ...
    } as const;
    
    const SpecificRbiPaymentErrorCodes = {
      BIZUM_OPERATION_CANCELLED_ERROR: '2.005.001',
      ...
      PAYPAL_OPERATION_CANCELLED_ERROR: '2.005.002',
      ...
    } as const;

• Create a new classes:

  • OperationCancelledError generic class:

    • path: intl-packages/packages/psp-base/src/errors/psp-error-2/generic/operation-cancelled-error.ts

      export class OperationCancelledError extends ExternalValidationError2 {
        ...
        constructor(params?: TPspError2) {
          const {
            httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
            message = 'Operation cannot be completed/continued as it has been cancelled.',
            metadata,
            responseBody,
            rbiErrorCode = RbiPaymentErrorCodes.OPERATION_CANCELLED_ERROR,
          } = params ?? {};
          super({ ...params, httpStatus, message, metadata, rbiErrorCode, responseBody });
        }
      }

  • BizumCancellationPaymentError specialized class:

    • path: intl-packages/packages/psp-base/src/errors/psp-error-2/bizum-operation-cancelled-error.ts

      export class BizumCancellationPaymentError extends OperationCancelledError {
        ...
        constructor(params?: TPspError2) {
          const {
            httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
            metadata,
            rbiErrorCode = RbiPaymentErrorCodes.BIZUM_OPERATION_CANCELLED_ERROR,
          } = params ?? {};
          super({ ...params, httpStatus, metadata, rbiErrorCode });
        }
      }

  • PaypalCancellationPaymentError specialized class:

    • path: intl-packages/packages/psp-base/src/errors/psp-error-2/

      paypal-operation-cancelled-error.ts

      export class PaypalCancellationPaymentError extends OperationCancelledError {
        ...
        constructor(params?: TPspError2) {
          const {
            httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
            metadata,
            rbiErrorCode = RbiPaymentErrorCodes.PAYPAL_OPERATION_CANCELLED_ERROR,
          } = params ?? {};
          super({ ...params, httpStatus, metadata, rbiErrorCode });
        }
      }

intl-psp-paycomet-service

• Mapper the errors on PspErrorMap

  • path: intl-psp-paycomet-service/src/errors/paycomet-error-map.ts

    export const errorMap: PspErrorMap = new Map([
      ...
      [
        142,
        {
          classNameRef: OperationCancelledError,
          info: 'Operation canceled.',
        },
      ],
      ...
      [
        1342,
        {
          classNameRef: BizumCancellationPaymentError,
          info: 'Bizum. Transaction cancelled. The user does not wish to continue.',
        },
      ],
      ...
      [
        1425,
        {
          classNameRef: PaypalCancellationPaymentError,
          info: 'PayPal. Transaction cancelled. The user does not wish to continue.',
        },
      ],
    ]);

Frontend

After backend changes, will need to handle the error.

Translation

• Create a new keys to translate the error message:

  {
    ...
    "error.payment.2.005.title": "Purchase cancelled",
    "error.payment.2.005.cta": "Go Back to Checkout",
    "error.payment.2.005": "Your purchase has been successfully cancelled.",
    ...
  }

Change error validation

• Change the validation on isCanceledOperation

  • path: intl-whitelabel-app/workspaces/frontend/src/hooks/use-paycomet-pay-link-popup/utils.ts

  • before:

    export const isCanceledOperation = (e: MessageEvent) => {
      const isCanceledOperation =
        e.data &&
        typeof e.data === 'object' &&
        Object.values(CanceledCodeOperationType).includes(e.data?.body?.code);
    
      return !!(e.data === ClosedWindowType.CLOSED || isCancelation);
    };

  • after:

    export const isCanceledOperation = (e: MessageEvent) => {
      const isCancelation =
        e.data &&
        typeof e.data === 'object' && <FF_FLAG> &&
        Object.values(CanceledCodeOperationType).includes(e.data?.body?.code);
    
      return !!(e.data === ClosedWindowType.CLOSED || isCancelation);
    };

Potential Challenges

N/A

💰 Cost

🎛️ Configuration

📈 Metrics

N/A

🗓️ Delivery Plan

🧑‍🚒 QA Plan

N/A

⚠️ Call-outs