Document Status	IN PROGRESS
Document Owner(s)	de Sousa Santos, Rodrigo
Reviewers	Raphael Ferreira Gomes Szekely, Szabolcs Augusto Romao, Vinicius Garozzo de Sobral, Wellington Capovilla, Evandro Felipe Rooke

Context

Iberia proposes the inclusion of new error messages in the error detailing flow, following the established processes in stories:

Story: IBFEC-2647
- Solution: [Solution] Detailed payment error messages
Story: IBFEC-2856
- Solution: [Solution] Detailed Error Message when the user cancel the payment transaction using payment link

The objective is to enhance error communication between the backend and frontend.

✅ Proposed Solution

To address these issues, we propose the creation of new error classes in the backend that will be sent to the frontend. This implementation will include specific error codes for different scenarios, such as payment cancellations, instead of using generic codes. This change will allow the frontend to display more informative and contextualized error messages, improving clarity and the overall user experience.

Backend

After the solution approval, will need to update the below documents with new classes, code errors, and any important things.

Paycomet errors: https://docs.paycomet.com/en/recursos/codigos-de-error
Iberia errors list: Sheet
Payment code errors: /wiki/spaces/RWLAPPwiki/pages/4858741214
Payment mappers: /wiki/spaces/RWLAPPwiki/pages/5001150489

Description errors

Payment method	Paycomet Code	Public Message (Logs/Amplitude)	Error Code	Lokalise key description error modal: `error.payment.X.XXX` title error modal: `error.payment.X.XXX.title` label button modal: `error.payment.X.XXX.cta`	Severity	Class Error	Parent class	Documentation
Card	100	Expired credit card	`PAYMENT.2.100.003`	`error.payment.2.100.103` `error.payment.2.100.103.tilte` `error.payment.2.100.103.cta`	2	ExpiredCardError	CardError2	Represents an error when the card has expired
Card	105	Insufficient funds	`PAYMENT.2.100.004`	`error.payment.2.100.104` `error.payment.2.100.104.title` `error.payment.2.100.104.cta`	2	NoFundsCardError	CardError2	Represents an error when the card does not have enough funds in order to perform the payment
Card	127	Invalid parameter	`PAYMENT.4.009`	`error.payment.4.009` `error.payment.4.009.title` `error.payment.4.009.cta`	4	DataExternalValidationError	ExternalValidationError2	Represents an error when there is an invalid parameter
Card	137	Credit card not valid	`PAYMENT.2.100.006`	`error.payment.2.100.106` `error.payment.2.100.106.title` `error.payment.2.100.106.cta`	2	DeclinedCardError	CardError2	Represents an error when the card declined for various reasons
Card	141	Invalid amount	`PAYMENT.2.100.007`	`error.payment.2.100.107` `error.payment.2.100.107.title` `error.payment.2.100.107.cta`	2	InvalidAmountError	NoFundsCardError	Represents an error when the amount is zero or not valid
Card	143	Authentification error	`PAYMENT.4.001.001`	`error.payment.4.001.001` `error.payment.4.001.001.title` `error.payment.4.001.001.cta`	4	AuthenticationError	AuthSecurityError2	Represents errors related to security and authentication within the payment system. Invalid access tokens, and other related security and authentication problems.
Card	195	Requires SCA authentication	`PAYMENT.4.001.002`	`error.payment.4.001.002` `error.payment.4.001.002.title` `error.payment.4.001.002.cta`	4	ScaAuthenticationError	AuthSecurityError2	Represents an error a Strong Customer Authentication error. SCA (Strong Customer Authentication) is a requirement of the European directive PSD2 (Revised Payment Services Directive) aimed at enhancing the security of online financial transactions
Card	500	General external error	`PAYMENT.4.006`	`error.payment.4.006` `error.payment.4.006.title` `error.payment.4.006.cta`	4	ExternalError2	PspError2	General, unspecified payment error.
Card	506	Confirmation data not valid	`PAYMENT.4.006.001`	`error.payment.4.006.001` `error.payment.4.006.001.title` `error.payment.4.006.00.cta`	4	ConfirmationDataNotValidError	ExternalError2	Represents an error when confirmation data is not valid
Card	510	Refund is not possible	`PAYMENT.4.010.001`	`error.payment.4.010.001` `error.payment.4.010.001.title` `error.payment.4.010.001.cta`	4	RefundNotPossibleError	OperationDeniedError	Represents an error when the refund is not possible
Card	535	General external error	`PAYMENT.4.006`	`error.payment.4.006` `error.payment.4.006.title` `error.payment.4.006.cta`	4	ExternalError2	PspError2	General, unspecified payment error.
Card	549	General external error	`PAYMENT.4.006`	`error.payment.4.006` `error.payment.4.006.title` `error.payment.4.006.cta`	4	ExternalError2	PspError2	General, unspecified payment error.
Card	555	Could not find the previous operation	`PAYMENT.4.009.001`	`error.payment.4.009.001` `error.payment.4.009.001.title` `error.payment.4.009.001.cta`	4	CouldNotFindPreviousOperationError	DataExternalValidationError	Represents an error when could not find the previous operation
Card	569	Denied operation	`PAYMENT.4.010`	`error.payment.4.010` `error.payment.4.010.title` `error.payment.4.010.cta`	4	OperationDeniedError	ExternalValidationError2	Represents an error when the operation cannot be performed
Card	1019	Operation timeout exceeded	`PAYMENT.4.011`	`error.payment.4.011` `error.payment.4.011.title` `error.payment.4.011.cta`	4	TimeOutConnectionError	ConnectionError2	Represents an error when there is a timeout
Card	1026	Duplicated external reference	`PAYMENT.4.006.002`	`error.payment.4.006.002` `error.payment.4.006.002.title` `error.payment.4.006.002.cta`	4	DuplicatedExternalReferenceError	ExternalError2	Represents an error when there is a duplicated external reference
Card	1038	Field DS_MERCHANT_AMOUNT incorrect	`PAYMENT.4.009`	`error.payment.4.009` `error.payment.4.009.title` `error.payment.4.009.cta`	4	DataExternalValidationError	ExternalValidationError2	Represents an error when the field DS_MERCHANT_AMOUNT is incorrect
Card	1099	General external error	`PAYMENT.4.006`	`error.payment.4.006` `error.payment.4.006.title` `error.payment.4.006.cta`	4	ExternalError2	PspError2	General, unspecified payment error.
Card	1186	Maximum limit not allowed	`PAYMENT.2.102.004`	`error.payment.2.102.004` `error.payment.2.102.004.title` `error.payment.2.102.004.cta`	2	CardLimitExceededError	PaymentRestrictionError2	Represents an error when the card amount/number of transaction limit has been exceeded
Card	1191	Day / IP address limit (all cards) not allowed	`PAYMENT.2.102.004`	`error.payment.2.102.004` `error.payment.2.102.004.title` `error.payment.2.102.004.cta`	2	CardLimitExceededError	PaymentRestrictionError2	Represents an error when the card amount/number of transaction limit has been exceeded
Card	1194	Card brands not allowed	`PAYMENT.2.100.002`	`error.payment.2.100.002` `error.payment.2.100.002.title` `error.payment.2.100.002.cta`	2	CardTypeNotAllowedError	CardError2	Represents an error when the card type (type/brand/etc.) is not allowed for this transaction
Card	1197	Card country issuer not allowed	`PAYMENT.2.102.005`	`error.payment.2.102.005` `error.payment.2.102.005.title` `error.payment.2.102.005.cta`	2	CardCountryNotAllowed	PaymentRestrictionError2	Represents an error when the card / issuing bank country is not allowed for the transaction
Card	1254	Commerce with secure cardholder and cardholder without secure purchase key	`PAYMENT.4.001.003`	`error.payment.4.001.003` `error.payment.4.001.003.title` `error.payment.4.001.003.cta`	4	CardholderSecurePurchaseKeyError	AuthSecurityError2	Represents an error when there is a commerce with secure cardholder and cardholder without secure purchase key
Card	1326	Denial by security controls on the processor	`PAYMENT.2.002`	`error.payment.2.002` `error.payment.2.002.title` `error.payment.2.002.cta`	2	FraudError	ExternalError2	Represents errors generated when a transaction is suspected of being fraudulent. This class extends `ExternalError` to encapsulate fraud-related issues, including abnormal user behavior, suspicious transaction patterns, and other indicators of potential fraud. It is designed to aid in the identification and management of transactions that may pose a risk to the payment system
Card	1327	3DS authentication process error	`PAYMENT.2.101.003`	`error.payment.2.101.003` `error.payment.2.101.003.title` `error.payment.2.101.003.cta`	2	ThreeDsChallengeFailedError	PaymentProcessingError2	Represents an error when the 3DS Challenge failed
Payment Link	1417	PayPal - The instrument presented has been declined. Please select another one.	`PAYMENT.2.100.005`	`error.payment.2.100.105` `error.payment.2.100.105.title` `error.payment.2.100.105.cta`	2	DeclinedCardError	CardError2	Represents an error when the card declined for various reasons

Created classes:

AuthSecurityError
ExternalError
FraudError
PspError
ExternalValidationError

Classes will be created:

InvalidAmountError
AuthenticationError
CardCountryNotAllowed
CardLimitExceededError
DeclinedCardError
CardTypeNotAllowedError
CardholderSecurePurchaseKeyError
ConfirmationDataNotValidError
CouldNotFindPreviousOperationError
DataExternalValidationError
DeclinedCardError
DuplicatedExternalReferenceError
ExpiredCardError
NoFundsCardError
OperationDeniedError
RefundNotPossibleError
ScaAuthenticationError
TimeOutConnectionError
ThreeDsChallengeFailedError

intl-packages

Rename the class:
- From: OperationCancelledError
- To: OperationCancelledFailedError

Will be created new classes in the path:
- intl-packages/packages/psp-base/src/errors/psp-error-2/

InvalidAmountError details

import { HttpStatus } from '@nestjs/common';
import { RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';
import { NoFundsCardError } from './no-founds-card-error';

export class InvalidAmountError extends NoFundsCardError {
  /**
   * Represents an error when the amount is zero or not valid.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.INVALID_AMOUNT_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

AuthenticationError details

import { HttpStatus } from '@nestjs/common';
import { AuthSecurityError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class AuthenticationError extends AuthSecurityError2 {
  /**
   * Represents an error when the user cannot be authenticated.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.AUTHENTICATION_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

CardCountryNotAllowed details

import { HttpStatus } from '@nestjs/common';
import { PaymentRestrictionError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class CardCountryNotAllowed extends PaymentRestrictionError2 {
  /**
   * Represents an error when the card / issuing bank country is not allowed for the transaction.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.CARD_COUNTRY_NOT_ALLOWED_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

CardLimitExceededError details

import { HttpStatus } from '@nestjs/common';
import { PaymentRestrictionError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class CardLimitExceededError extends PaymentRestrictionError2 {
  /**
   * Represents an error when the card amount/number of transaction limit has been exceeded.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.CARD_LIMIT_EXCEEDED_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

DeclinedCardError details

import { HttpStatus } from '@nestjs/common';
import { CardError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class DeclinedCardError extends CardError2 {
  /**
   * Represents an error when the card declined for various reasons.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.DECLINED_CARD_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

CardTypeNotAllowedError details

import { HttpStatus } from '@nestjs/common';
import { CardError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class CardTypeNotAllowedError extends CardError2 {
  /**
   * Represents an error when the card type (type/brand/etc.) is not allowed for this transaction.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.CARD_TYPE_NOT_ALLOWED_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

CardholderSecurePurchaseKeyError details

import { HttpStatus } from '@nestjs/common';
import { AuthSecurityError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class CardholderSecurePurchaseKeyError extends AuthSecurityError2 {
  /**
   * Represents an error when there is a commerce with secure
   * cardholder and cardholder without secure purchase key.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.CARDHOLDER_SECURE_PURCHASE_KEY_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

ConfirmationDataNotValidError details

import { HttpStatus } from '@nestjs/common';
import { ExternalError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class ConfirmationDataNotValidError extends ExternalError2 {
  /**
   * Represents an error when confirmation data not valid.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.CONFIRMATION_DATA_NOT_VALID_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

CouldNotFindPreviousOperationError details

import { HttpStatus } from '@nestjs/common';
import { RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';
import { DataExternalValidationError } from './data-external-validation-error';

export class CouldNotFindPreviousOperationError extends DataExternalValidationError {
  /**
   * Represents an error when could not find the previous operation.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.COULD_NOT_FIND_PREVIOUS_OPERATION_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

DataExternalValidationError details

import { HttpStatus } from '@nestjs/common';
import { ExternalValidationError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class DataExternalValidationError extends ExternalValidationError2 {
  /**
   * Represents an error when the data sent to the PSP is not correct.
   * It might have missing or incorrect parameters.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.DATA_EXTERNAL_VALIDATION_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

DeclinedCardError details

import { HttpStatus } from '@nestjs/common';
import { CardError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class DeclinedCardError extends CardError2 {
  /**
   * Represents an error when the card declined for various reasons.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.DECLINED_CARD_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

DuplicatedExternalReferenceError details

import { HttpStatus } from '@nestjs/common';
import { ExternalError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class DuplicatedExternalReferenceError extends ExternalError2 {
  /**
   * Represents an error when there is a duplicated external reference.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.DUPLICATED_EXTERNAL_REFERENCE_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

ExpiredCardError details

import { HttpStatus } from '@nestjs/common';
import { CardError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class ExpiredCardError extends CardError2 {
  /**
   * Represents an error when the card has expired.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.EXPIRED_CARD_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

NoFundsCardError details

import { HttpStatus } from '@nestjs/common';
import { CardError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class NoFundsCardError extends CardError2 {
  /**
   * Represents an error when the card does not have enough funds in order to perform the payment.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.NO_FUNDS_CARD_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

OperationDeniedError details

import { HttpStatus } from '@nestjs/common';
import { ExternalValidationError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class OperationDeniedError extends ExternalValidationError2 {
  /**
   * Represents an error when the operation cannot be performed.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.OPERATION_DENIED_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

RefundNotPossibleError details

import { HttpStatus } from '@nestjs/common';
import { RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';
import { OperationDeniedError } from './operation-denied-error';

export class RefundNotPossibleError extends OperationDeniedError {
  /**
   * Represents an error when the refund is not possible.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.REFUND_NOT_POSSIBLE_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

ScaAuthenticationError details

import { HttpStatus } from '@nestjs/common';
import { AuthSecurityError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class ScaAuthenticationError extends AuthSecurityError2 {
  /**
   * Represents an error a Strong Customer Authentication error.
   *
   * SCA (Strong Customer Authentication) is a requirement of the European directive
   * PSD2 (Revised Payment Services Directive) aimed at enhancing the security of
   * online financial transactions. SCA mandates that, for authenticating a payment,
   * payment service providers must use at least
   * two of the following three authentication factors:
   * - Something you know: such as a password or PIN.
   * - Something you have: like a mobile phone, security token, or debit/credit card.
   * - Something you are: such as biometrics, like fingerprints or facial recognition.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.SCA_AUTHENTICATION_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

ThreeDsChallengeFailedError details

import { HttpStatus } from '@nestjs/common';
import { PaymentProcessingError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class ThreeDsChallengeFailedError extends PaymentProcessingError2 {
  /**
   * Represents an error when the 3DS Challenge failed.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.THREE_DS_CHALLENGE_FAILED_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

TimeOutConnectionError details

import { HttpStatus } from '@nestjs/common';
import { ConnectionError2, RbiPaymentErrorCodes, TPspError2 } from '../psp-error-2';

export class TimeOutConnectionError extends ConnectionError2 {
  /**
   * Represents an error when there is a timeout.
   *
   * @param params - The error parameters.
   * @param [params.httpStatus] - The HTTP status code to be returned in the response.
   * @param [params.message] - A human-readable message that provides details about the payment processing issue.
   * @param [params.metadata] - Optional metadata that may include additional context or details about the error.
   * @param [params.originalError] - The original error that caused this error.
   */
  constructor(params?: TPspError2) {
    const {
      httpStatus = HttpStatus.UNPROCESSABLE_ENTITY,
      metadata,
      rbiErrorCode = RbiPaymentErrorCodes.TIME_OUT_CONNECTION_ERROR,
    } = params ?? {};
    super({ ...params, httpStatus, metadata, rbiErrorCode });
  }
}

Export the classes:
- path: intl-packages/packages/psp-base/src/errors/psp-error-2/index.ts
Will create the new error codes:
- path: intl-packages/packages/psp-base/src/errors/psp-error-2/psp-error-2.ts
  - Code Errors:

GenericRbiPaymentErrorCodes details

const GenericRbiPaymentErrorCodes = {
  ...
  DATA_EXTERNAL_VALIDATION_ERROR: '4.009',
  OPERATION_DENIED_ERROR: '4.010',
  TIME_OUT_CONNECTION_ERROR: '4.011',
} as const;

SpecificRbiPaymentErrorCodes details

const SpecificRbiPaymentErrorCodes = {
  ...
  INVALID_AMOUNT_ERROR: '2.100.107',
  AUTHENTICATION_ERROR: '4.001.001',
  EXPIRED_CARD_ERROR: '2.100.102',
  NO_FUNDS_CARD_ERROR: '2.100.103',
  DECLINED_CARD_ERROR: '2.100.104',
  DECLINED_CARD_ERROR: '2.100.105',
  CARD_LIMIT_EXCEEDED_ERROR: '2.102.004',
  CARD_TYPE_NOT_ALLOWED_ERROR: '2.100.002',
  CARD_COUNTRY_NOT_ALLOWED_ERROR: '2.102.005',
  SCA_AUTHENTICATION_ERROR: '4.001.002',
  THREE_DS_CHALLENGE_FAILED_ERROR: '2.101.003',
  CONFIRMATION_DATA_NOT_VALID_ERROR: '4.006.001',
  REFUND_NOT_POSSIBLE_ERROR: '4.010.001',
  COULD_NOT_FIND_PREVIOUS_OPERATION_ERROR: '4.009.001',
  DUPLICATED_EXTERNAL_REFERENCE_ERROR: '4.006.002',
  CARDHOLDER_SECURE_PURCHASE_KEY_ERROR: '4.001.003',
} as const;

intl-psp-paycomet-service

We will need to map the error code:
- path: intl-psp-paycomet-service/src/errors/paycomet-error-map.ts

errorMap detailed

export const errorMap: PspErrorMap = new Map([
  ...
  [
    100,
    {
      classNameRef: ExpiredCardError,
      info: 'Expired credit card',
    },
  ],
  [
    105,
    {
      classNameRef: NoFundsCardError,
      info: 'Insufficient funds',
    },
  ],
  [
    127,
    {
      classNameRef: InvalidParameterError,
      info: 'Invalid parameter',
    },
  ],
  [
    137,
    {
      classNameRef: DeclinedCardError,
      info: 'Credit card not valid',
    },
  ],
  [
    141,
    {
      classNameRef: AmountNotValidError,
      info: 'Amount zero or not valid',
    },
  ],
  [
    143,
    {
      classNameRef: AuthenticationError,
      info: 'Authentification error',
    },
  ],
  [
    195,
    {
      classNameRef: ScaAuthenticationError,
      info: 'Requires SCA authentication',
    },
  ],
  [
    500,
    {
      classNameRef: PspError2,
      info: 'General PSP error',
    },
  ],
  [
    506,
    {
      classNameRef: ConfirmationDataNotValidError,
      info: 'Confirmation data not valid',
    },
  ],
  [
    510,
    {
      classNameRef: RefundNotPossibleError,
      info: 'Refund is not possible',
    },
  ],
  [
    535,
    {
      classNameRef: PspError2,
      info: 'General PSP error',
    },
  ],
  [
    549,
    {
      classNameRef: PspError2,
      info: 'General PSP error',
    },
  ],
  [
    555,
    {
      classNameRef: CouldNotFindPreviousOperationError,
      info: 'Could not find the previous operation',
    },
  ],
  [
    569,
    {
      classNameRef: OperationDeniedError,
      info: 'Denied operation',
    },
  ],
  [
    1019,
    {
      classNameRef: TimeOutConnectionError,
      info: 'Operation timeout exceeded',
    },
  ],
  [
    1026,
    {
      classNameRef: DuplicatedExternalReferenceError,
      info: 'Duplicated external reference',
    },
  ],
  [
    1038,
    {
      classNameRef: DataExternalValidationError,
      info: 'Field DS_MERCHANT_AMOUNT incorrect',
    },
  ],
  [
    1099,
    {
      classNameRef: PspError2,
      info: 'General PSP error',
    },
  ],
  [
    1186,
    {
      classNameRef: CardLimitExceededError,
      info: 'Maximum limit not allowed',
    },
  ],
  [
    1191,
    {
      classNameRef: CardLimitExceededError,
      info: 'Day / IP address limit (all cards) not allowed',
    },
  ],
  [
    1194,
    {
      classNameRef: CardTypeNotAllowedError,
      info: 'Card brands not allowed',
    },
  ],
  [
    1197,
    {
      classNameRef: CardCountryNotAllowed,
      info: 'Denied. Filter: Card country issuer not allowed',
    },
  ],
  [
    1254,
    {
      classNameRef: CardholderSecurePurchaseKeyError,
      info: 'Commerce with secure cardholder and cardholder without secure purchase key',
    },
  ],
  [
    1326,
    {
      classNameRef: FraudError2,
      info: 'Denial by security controls on the processor',
    },
  ],
  [
    1327,
    {
      classNameRef: ThreeDsChallengeFailedError,
      info: '3DS authentication process error',
    },
  ],
  [
    1417,
    {
      classNameRef: DeclinedCardError,
      info: 'PayPal - The instrument presented has been declined. Please select another one.',
    },
  ],
]);

Check the possibility of mapping errors where classes have already been created.
- e.g.:

Error Messages

Paycomet	Key	Description	Modal Title	Modal Message	Modal CTA
100	`PAYMENT.2.100.003`	Expired Card - Represents an error when the card has expired	“Expired Card”	“Your card has expired. Please change your payment method in order to complete the transaction.”	“Change Payment Method”
105	`PAYMENT.2.100.004`	Insufficient Credit to make charge - Represents an error when the card does not have enough funds in order to perform the payment	“Payment Failed”	“Your payment couldn't be processed due to an issue with your payment method. Please review your payment method or choose a different one to complete your purchase.”	“Change Payment Method”
127	`PAYMENT.4.009`	Invalid Parameter - Represents an error when there is an invalid parameter	“Payment Failed"	“Something went wrong with this  payment. Please try again later."	"Go Back and Try Again Later”
137	`PAYMENT.2.100.006`	Invalid Card - Represents an error when the card declined for various reasons	“Invalid Card”	“You card was declined by the issuer. Please, change your payment method and try again.”	“Change Payment Method”
141	`PAYMENT.2.100.007`	Zero or Invalid Quantity - Represents an error when the amount is zero or not valid	“Payment Failed”	“Something went wrong with this  payment. Please try again.”	“Go Back and Try Again”
142	?	Operation Cancelled	“Operation Cancelled”	“This transaction has been cancelled. Please go back and try again.”	“Go Back and Try Again”
143	`PAYMENT.4.001.001`	Authentication error - Represents errors related to security and authentication within the payment system. Invalid access tokens, and other related security and authentication problems.	“Authentication Error”	“Something went wrong with this  payment. Please try again.”	“Go Back and Try Again”
195	`PAYMENT.4.001.002`	Requires SCA Authentication - Represents an error a Strong Customer Authentication error. SCA (Strong Customer Authentication) is a requirement of the European directive PSD2 (Revised Payment Services Directive) aimed at enhancing the security of online financial transactions	“Payment Declined"	“Your payment has been declined. A multi-factor authentication is required by the issuer of your payment method in order to proceed.”	“Go Back”
500	`PAYMENT.4.006`	Unexpected Error - General, unspecified payment error.	“Payment Failed”	“Something went wrong with this  payment. Please try again later.”	“Go Back and Try Again Later”
506	`PAYMENT.4.006.001`	Invalid Confirmation Data - Represents an error when confirmation data is not valid	“Invalid Confirmation Data”	“It seems the system could not validate the data entered. Please go back and try again.”	“Go Back and Try Again”
510	`PAYMENT.4.010.001`	Return is not possible - Represents an error when the refund is not possible	“Payment Timed Out”	“Something went wrong with this  payment. Please try again.”	“Go Back and Try Again”
535	`PAYMENT.4.006`	General, unspecified payment error.	“Payment Failed”	“Something went wrong with this  payment. Please try again later.”	“Go Back and Try Again”
549	`PAYMENT.4.006`	General, unspecified payment error.	“Payment Failed”	“Something went wrong with this  payment. Please try again later.”	“Go Back and Try Again”
569	`PAYMENT.4.010`	Operation Rejected (Denied by the issuer) - Represents an error when the operation cannot be performed	“Payment Declined”	“Your payment was declined by your card issuer. Please select another payment method in order to proceed.”	"Change Payment Method”
1019	`PAYMENT.4.011`	Request Timed Out - Represents an error when there is a timeout	“Request Timed Out”	“Looks like the server is taking to long to respond, please try again.”	“Go Back and Try Again”
1026	`PAYMENT.4.006.002`	Duplicate external reference - Represents an error when there is a duplicated external reference	“Duplicated Payment”	“Duplicate transaction detected. It seems this payment has already been processed. Please check your order history or try again in a moment.”	“Go Back and Try Again”
1038	`PAYMENT.4.009`	Incorrect DS_MERCHANT_AMOUNT field - Represents an error when the field DS_MERCHANT_AMOUNT is incorrect	“Payment Failed”	“Something went wrong with this  payment. Please go back and try again.”	“Go Back and Try Again”
1099	`PAYMENT.4.006`	Unexpected error (Error when processing the transaction) - General, unspecified payment error	“Unexpected error"	“Something went wrong with this  payment. Please try again later.”	"Review Card Details”
1186	`PAYMENT.2.102.004`	Maximum limit per transaction not allowed (Default 1000 Euros) - Represents an error when the card amount/number of transaction limit has been exceeded	“Payment Declined"	“ Your payment was declined due to security reasons. Please review your order and try again.”	"Go Back”
1194	`PAYMENT.2.100.002`	Card Brand not allowed - Represents an error when the card type (type/brand/etc.) is not allowed for this transaction	“Payment Failed”	“It seems the card brand you're using is not supported. Please return and select a different payment method to complete your transaction.”	“Change Payment Method”
1254	`PAYMENT.4.001.003`	Attempt to process a secure payment, and the card does not allow it. - Represents an error when there is a commerce with secure cardholder and cardholder without secure purchase key	“Payment Failed”	“The payment couldn’t be processed because your card doesn’t support secure authentication methods. Please go back and try another payment method.”	“Change Payment Method”
1326	`PAYMENT.2.002`	Represents errors generated when a transaction is suspected of being fraudulent. This class extends `ExternalError` to encapsulate fraud-related issues, including abnormal user behavior, suspicious transaction patterns, and other indicators of potential fraud. It is designed to aid in the identification and management of transactions that may pose a risk to the payment system	“Payment Declined”	“Your payment was declined due to security reasons. Please select a new payment method and try again.”	"Change Payment Method”
1327	`PAYMENT.2.101.003`	Denied by security reasons - Represents an error when the 3DS Challenge failed	“Payment Declined"	“Your payment was declined due to security reasons. Please select a new payment method and try again.”	"Change Payment Method”
1417	`PAYMENT.2.100.005`	PayPal - The instrument presented has been declined. Please select another one. - Represents an error when the card declined for various reasons	“Payment Declined”	“Your payment was declined by Paypal. Please review your payment method or select a new one.”	“Go Back”
1425	`?`	Paypal - Operation Canceled by the user	“Transaction Cancelled"	“Your transaction was canceled on PayPal. If you wish to complete your purchase, please try again or choose a different payment method”	"Go Back”