@plyaz/types 1.14.9 → 1.14.10

package/dist/api/index.js

@@ -557,6 +557,20 @@ var ERROR_CATEGORY = {
   Template: "template",
   /** Configuration-related error (e.g., invalid or missing configuration). */
   Configuration: "configuration",
+  /** Payment processing-related error (e.g., capture or settlement failure). */
+  Processing: "processing",
+  /** Fraud detection or prevention failure. */
+  Fraud: "fraud",
+  /** Compliance-related error (e.g., AML/KYC validation failure). */
+  Compliance: "compliance",
+  /** Limits or quota-related error (e.g., exceeded transaction limit). */
+  Limits: "limits",
+  /** System-level error (unexpected internal issue). */
+  System: "system",
+  /** Refund-related error (e.g., duplicate or failed refund). */
+  Refund: "refund",
+  /** Security-related error (e.g., encryption or signature failure). */
+  Security: "security",
   /** Unknown or unclassified error. */
   Unknown: "unknown"
 };
@@ -615,6 +629,13 @@ var INTERNAL_STATUS_CODES = {
   [ERROR_CATEGORY.Webhook]: "webhook",
   [ERROR_CATEGORY.Template]: "template",
   [ERROR_CATEGORY.Configuration]: "configuration",
+  [ERROR_CATEGORY.Processing]: "processing",
+  [ERROR_CATEGORY.Fraud]: "fraud",
+  [ERROR_CATEGORY.Compliance]: "compliance",
+  [ERROR_CATEGORY.Limits]: "limits",
+  [ERROR_CATEGORY.System]: "system",
+  [ERROR_CATEGORY.Refund]: "refund",
+  [ERROR_CATEGORY.Security]: "security",
   [ERROR_CATEGORY.Unknown]: "unknown"
 });
 var COMMON_OPERATIONS = {
@@ -738,6 +759,10 @@ var HTTP_STATUS = {
    * 409 Conflict - The request conflicts with the current state of the server
    */
   CONFLICT: 409,
+  /**
+   * 422 Unprocessable Entity - The request was well-formed but was unable to be followed due to semantic errors
+   */
+  UNPROCESSABLE_ENTITY: 422,
   /**
    * 429 Too Many Requests - The user has sent too many requests in a given amount of time
    */
@@ -984,7 +1009,86 @@ var ERROR_CODES = {
   DB_INVALID_SHELL_ARG: "DB_INVALID_SHELL_ARG",
   DB_INVALID_BETWEEN_OPERATOR: "DB_INVALID_BETWEEN_OPERATOR",
   DB_INVALID_IN_OPERATOR: "DB_INVALID_IN_OPERATOR",
-  DB_INVALID_COUNT: "DB_INVALID_COUNT"
+  DB_INVALID_COUNT: "DB_INVALID_COUNT",
+  // ===== Payments Package Errors =====
+  // Refund
+  PAYMENT_REFUND_FAILED: "payment.refund.failed",
+  PAYMENT_REFUND_NOT_FOUND: "payment.refund.not.found",
+  PAYMENT_REFUND_ALREADY_PROCESSED: "payment.refund.already.processed",
+  PAYMENT_REFUND_AMOUNT_INVALID: "payment.refund.amount.invalid",
+  PAYMENT_REFUND_VALIDATION_FAILED: "payment.refund.validation.failed",
+  PAYMENT_REFUND_TIMEOUT: "payment.refund.timeout",
+  // Provider
+  PAYMENT_PROVIDER_ERROR: "payment.provider.error",
+  PAYMENT_PROVIDER_UNAVAILABLE: "payment.provider.unavailable",
+  PAYMENT_PROVIDER_CONFIGURATION_INVALID: "payment.provider.configuration.invalid",
+  PAYMENT_PROVIDER_RESPONSE_INVALID: "payment.provider.response.invalid",
+  PAYMENT_PROVIDER_TIMEOUT: "payment.provider.timeout",
+  PAYMENT_PROVIDER_AUTH_FAILED: "payment.provider.auth.failed",
+  // Compliance
+  PAYMENT_COMPLIANCE_VIOLATION: "payment.compliance.violation",
+  PAYMENT_COMPLIANCE_CHECK_FAILED: "payment.compliance.check.failed",
+  PAYMENT_COMPLIANCE_LIMIT_EXCEEDED: "payment.compliance.limit.exceeded",
+  PAYMENT_COMPLIANCE_POLICY_MISSING: "payment.compliance.policy.missing",
+  // Processing
+  PAYMENT_PROCESSING_FAILED: "payment.processing.failed",
+  PAYMENT_PROCESSING_TIMEOUT: "payment.processing.timeout",
+  PAYMENT_PROCESSING_GATEWAY_ERROR: "payment.processing.gateway.error",
+  PAYMENT_PROCESSING_DUPLICATE: "payment.processing.duplicate",
+  PAYMENT_PROCESSING_UNEXPECTED_STATE: "payment.processing.unexpected.state",
+  // Security
+  PAYMENT_SECURITY_VIOLATION: "payment.security.violation",
+  PAYMENT_SECURITY_SIGNATURE_INVALID: "payment.security.signature.invalid",
+  PAYMENT_SECURITY_ENCRYPTION_FAILED: "payment.security.encryption.failed",
+  PAYMENT_SECURITY_FRAUD_DETECTED: "payment.security.fraud.detected",
+  PAYMENT_SECURITY_TOKEN_INVALID: "payment.security.token.invalid",
+  // Validation
+  PAYMENT_VALIDATION_FAILED: "payment.validation.failed",
+  PAYMENT_VALIDATION_AMOUNT_INVALID: "payment.validation.amount.invalid",
+  PAYMENT_VALIDATION_CURRENCY_UNSUPPORTED: "payment.validation.currency.unsupported",
+  PAYMENT_VALIDATION_METADATA_INVALID: "payment.validation.metadata.invalid",
+  PAYMENT_VALIDATION_MISSING_REQUIRED_FIELD: "payment.validation.field.required",
+  // Webhook
+  PAYMENT_WEBHOOK_SIGNATURE_INVALID: "payment.webhook.signature.invalid",
+  PAYMENT_WEBHOOK_PROCESSING_FAILED: "payment.webhook.processing.failed",
+  PAYMENT_WEBHOOK_VALIDATION_FAILED: "payment.webhook.validation.failed",
+  PAYMENT_WEBHOOK_EVENT_TYPE_UNSUPPORTED: "payment.webhook.event.type.unsupported",
+  PAYMENT_WEBHOOK_HANDLER_NOT_FOUND: "payment.webhook.handler.not.found",
+  // ===== Payment Adapter & Core Errors =====
+  PAYMENT_ADAPTER_INIT_FAILED: "payment.adapter.init.failed",
+  PAYMENT_ADAPTER_SHUTDOWN_ERROR: "payment.adapter.shutdown.error",
+  PAYMENT_ADAPTER_HMAC_COMPUTATION_FAILED: "payment.adapter.hmac.computation.failed",
+  PAYMENT_ADAPTER_MISSING_PROVIDER: "payment.adapter.missing.provider",
+  PAYMENT_ADAPTER_MISSING_ENVIRONMENT: "payment.adapter.missing.environment",
+  PAYMENT_ADAPTER_MISSING_CREDENTIALS: "payment.adapter.missing.credentials",
+  PAYMENT_ADAPTER_MISSING_WEBHOOK_URL: "payment.adapter.missing.webhook.url",
+  PAYMENT_ADAPTER_MISSING_UNREGISTER_ENDPOINT: "payment.adapter.missing.unregister.endpoint",
+  PAYMENT_ADAPTER_UNSUPPORTED_OPERATION: "payment.adapter.unsupported.operation",
+  PAYMENT_ADAPTER_RESPONSE_MAPPING_FAILED: "payment.adapter.response.mapping.failed",
+  // Idempotency & State Management
+  PAYMENT_IDEMPOTENCY_VIOLATION: "payment.idempotency.violation",
+  PAYMENT_IDEMPOTENCY_KEY_MISSING: "payment.idempotency.key.missing",
+  PAYMENT_IDEMPOTENCY_STORE_ERROR: "payment.idempotency.store.error",
+  // Routing & Strategy
+  PAYMENT_ROUTING_FAILED: "payment.routing.failed",
+  PAYMENT_ROUTING_CONFIGURATION_INVALID: "payment.routing.configuration.invalid",
+  PAYMENT_ROUTING_PROVIDER_UNAVAILABLE: "payment.routing.provider.unavailable",
+  PAYMENT_ROUTING_RETRY_EXCEEDED: "payment.routing.retry.exceeded",
+  // General Payment Framework Errors
+  PAYMENT_SYSTEM_NOT_INITIALIZED: "payment.system.not.initialized",
+  PAYMENT_CONTEXT_OPERATION_FAILED: "payment.context.operation.failed",
+  PAYMENT_INTERNAL_ERROR: "payment.internal.error",
+  PAYMENT_UNKNOWN_ERROR: "payment.unknown.error",
+  /**
+   * Thrown when an event could not be emitted due to internal state or creation errors.
+   * Typically non-retryable, indicates a logic or validation fault.
+   */
+  PAYMENT_EVENT_EMIT_FAILED: "PAYMENT_EVENT_EMIT_FAILED",
+  PAYMENT_EVENT_INVALID_TYPE: "PAYMENT_EVENT_INVALID_TYPE",
+  PAYMENT_EVENT_CREATION_FAILED: "PAYMENT_EVENT_CREATION_FAILED",
+  PAYMENT_EVENT_HANDLER_TIMEOUT: "PAYMENT_EVENT_HANDLER_TIMEOUT",
+  PAYMENT_EVENT_HANDLER_INVALID_RESULT: "PAYMENT_EVENT_HANDLER_INVALID_RESULT",
+  PAYMENT_EVENT_LIFECYCLE_FAILURE: "PAYMENT_EVENT_LIFECYCLE_FAILURE"
 };
 var API_ERROR_CODES = {
   CLIENT_INITIALIZATION_FAILED: ERROR_CODES.CLIENT_INITIALIZATION_FAILED,
@@ -2440,6 +2544,433 @@ var ERROR_DEFINITIONS = {
     category: ERROR_CATEGORY.Server,
     userMessage: "db.file.s3_upload_failed",
     severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  // ===== Payments Package Error Definitions =====
+  // ===== Refund Errors =====
+  [ERROR_CODES.PAYMENT_REFUND_FAILED]: {
+    code: ERROR_CODES.PAYMENT_REFUND_FAILED,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Refund,
+    userMessage: "errors.payment.refund.failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_REFUND_NOT_FOUND]: {
+    code: ERROR_CODES.PAYMENT_REFUND_NOT_FOUND,
+    status: HTTP_STATUS.NOT_FOUND,
+    category: ERROR_CATEGORY.Refund,
+    userMessage: "errors.payment.refund.not_found",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_REFUND_ALREADY_PROCESSED]: {
+    code: ERROR_CODES.PAYMENT_REFUND_ALREADY_PROCESSED,
+    status: HTTP_STATUS.CONFLICT,
+    category: ERROR_CATEGORY.Refund,
+    userMessage: "errors.payment.refund.already_processed",
+    severity: ERROR_SEVERITY.Low,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_REFUND_AMOUNT_INVALID]: {
+    code: ERROR_CODES.PAYMENT_REFUND_AMOUNT_INVALID,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.refund.amount_invalid",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_REFUND_VALIDATION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_REFUND_VALIDATION_FAILED,
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.refund.validation_failed",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_REFUND_TIMEOUT]: {
+    code: ERROR_CODES.PAYMENT_REFUND_TIMEOUT,
+    status: HTTP_STATUS.REQUEST_TIMEOUT,
+    category: ERROR_CATEGORY.Timeout,
+    userMessage: "errors.payment.refund.timeout",
+    severity: ERROR_SEVERITY.High,
+    retryable: true
+  },
+  // ===== Provider Errors =====
+  [ERROR_CODES.PAYMENT_PROVIDER_ERROR]: {
+    code: ERROR_CODES.PAYMENT_PROVIDER_ERROR,
+    status: HTTP_STATUS.BAD_GATEWAY,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.provider.generic",
+    severity: ERROR_SEVERITY.High,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_PROVIDER_UNAVAILABLE]: {
+    code: ERROR_CODES.PAYMENT_PROVIDER_UNAVAILABLE,
+    status: HTTP_STATUS.SERVICE_UNAVAILABLE,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.provider.unavailable",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_PROVIDER_CONFIGURATION_INVALID]: {
+    code: ERROR_CODES.PAYMENT_PROVIDER_CONFIGURATION_INVALID,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.provider.invalid_config",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_PROVIDER_RESPONSE_INVALID]: {
+    code: ERROR_CODES.PAYMENT_PROVIDER_RESPONSE_INVALID,
+    status: HTTP_STATUS.BAD_GATEWAY,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.provider.invalid_response",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_PROVIDER_TIMEOUT]: {
+    code: ERROR_CODES.PAYMENT_PROVIDER_TIMEOUT,
+    status: HTTP_STATUS.GATEWAY_TIMEOUT,
+    category: ERROR_CATEGORY.Timeout,
+    userMessage: "errors.payment.provider.timeout",
+    severity: ERROR_SEVERITY.High,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_PROVIDER_AUTH_FAILED]: {
+    code: ERROR_CODES.PAYMENT_PROVIDER_AUTH_FAILED,
+    status: HTTP_STATUS.UNAUTHORIZED,
+    category: ERROR_CATEGORY.Authentication,
+    userMessage: "errors.payment.provider.auth_failed",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  // ===== Compliance Errors =====
+  [ERROR_CODES.PAYMENT_COMPLIANCE_VIOLATION]: {
+    code: ERROR_CODES.PAYMENT_COMPLIANCE_VIOLATION,
+    status: HTTP_STATUS.FORBIDDEN,
+    category: ERROR_CATEGORY.Compliance,
+    userMessage: "errors.payment.compliance.violation",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_COMPLIANCE_CHECK_FAILED]: {
+    code: ERROR_CODES.PAYMENT_COMPLIANCE_CHECK_FAILED,
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    category: ERROR_CATEGORY.Compliance,
+    userMessage: "errors.payment.compliance.check_failed",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_COMPLIANCE_LIMIT_EXCEEDED]: {
+    code: ERROR_CODES.PAYMENT_COMPLIANCE_LIMIT_EXCEEDED,
+    status: HTTP_STATUS.TOO_MANY_REQUESTS,
+    category: ERROR_CATEGORY.Limits,
+    userMessage: "errors.payment.compliance.limit_exceeded",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_COMPLIANCE_POLICY_MISSING]: {
+    code: ERROR_CODES.PAYMENT_COMPLIANCE_POLICY_MISSING,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.compliance.policy_missing",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  // ===== Processing Errors =====
+  [ERROR_CODES.PAYMENT_PROCESSING_FAILED]: {
+    code: ERROR_CODES.PAYMENT_PROCESSING_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Processing,
+    userMessage: "errors.payment.processing.failed",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_PROCESSING_TIMEOUT]: {
+    code: ERROR_CODES.PAYMENT_PROCESSING_TIMEOUT,
+    status: HTTP_STATUS.GATEWAY_TIMEOUT,
+    category: ERROR_CATEGORY.Timeout,
+    userMessage: "errors.payment.processing.timeout",
+    severity: ERROR_SEVERITY.High,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_PROCESSING_GATEWAY_ERROR]: {
+    code: ERROR_CODES.PAYMENT_PROCESSING_GATEWAY_ERROR,
+    status: HTTP_STATUS.BAD_GATEWAY,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.processing.gateway_error",
+    severity: ERROR_SEVERITY.High,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_PROCESSING_DUPLICATE]: {
+    code: ERROR_CODES.PAYMENT_PROCESSING_DUPLICATE,
+    status: HTTP_STATUS.CONFLICT,
+    category: ERROR_CATEGORY.Processing,
+    userMessage: "errors.payment.processing.duplicate",
+    severity: ERROR_SEVERITY.Low,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_PROCESSING_UNEXPECTED_STATE]: {
+    code: ERROR_CODES.PAYMENT_PROCESSING_UNEXPECTED_STATE,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    userMessage: "errors.payment.processing.unexpected_state",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  // ===== Security Errors =====
+  [ERROR_CODES.PAYMENT_SECURITY_VIOLATION]: {
+    code: ERROR_CODES.PAYMENT_SECURITY_VIOLATION,
+    status: HTTP_STATUS.FORBIDDEN,
+    category: ERROR_CATEGORY.Security,
+    userMessage: "errors.payment.security.violation",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_SECURITY_SIGNATURE_INVALID]: {
+    code: ERROR_CODES.PAYMENT_SECURITY_SIGNATURE_INVALID,
+    status: HTTP_STATUS.UNAUTHORIZED,
+    category: ERROR_CATEGORY.Security,
+    userMessage: "errors.payment.security.invalid_signature",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_SECURITY_ENCRYPTION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_SECURITY_ENCRYPTION_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Security,
+    userMessage: "errors.payment.security.encryption_failed",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_SECURITY_FRAUD_DETECTED]: {
+    code: ERROR_CODES.PAYMENT_SECURITY_FRAUD_DETECTED,
+    status: HTTP_STATUS.FORBIDDEN,
+    category: ERROR_CATEGORY.Fraud,
+    userMessage: "errors.payment.security.fraud_detected",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_SECURITY_TOKEN_INVALID]: {
+    code: ERROR_CODES.PAYMENT_SECURITY_TOKEN_INVALID,
+    status: HTTP_STATUS.UNAUTHORIZED,
+    category: ERROR_CATEGORY.Authentication,
+    userMessage: "errors.payment.security.token_invalid",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  // ===== Validation Errors =====
+  [ERROR_CODES.PAYMENT_VALIDATION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_VALIDATION_FAILED,
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.validation.failed",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_VALIDATION_AMOUNT_INVALID]: {
+    code: ERROR_CODES.PAYMENT_VALIDATION_AMOUNT_INVALID,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.validation.amount_invalid",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_VALIDATION_CURRENCY_UNSUPPORTED]: {
+    code: ERROR_CODES.PAYMENT_VALIDATION_CURRENCY_UNSUPPORTED,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.validation.currency_unsupported",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_VALIDATION_METADATA_INVALID]: {
+    code: ERROR_CODES.PAYMENT_VALIDATION_METADATA_INVALID,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.validation.metadata_invalid",
+    severity: ERROR_SEVERITY.Low,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_VALIDATION_MISSING_REQUIRED_FIELD]: {
+    code: ERROR_CODES.PAYMENT_VALIDATION_MISSING_REQUIRED_FIELD,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.validation.required_field_missing",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  // ===== Webhook Errors =====
+  [ERROR_CODES.PAYMENT_WEBHOOK_SIGNATURE_INVALID]: {
+    code: ERROR_CODES.PAYMENT_WEBHOOK_SIGNATURE_INVALID,
+    status: HTTP_STATUS.UNAUTHORIZED,
+    category: ERROR_CATEGORY.Webhook,
+    userMessage: "errors.payment.webhook.signature_invalid",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_WEBHOOK_PROCESSING_FAILED]: {
+    code: ERROR_CODES.PAYMENT_WEBHOOK_PROCESSING_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Webhook,
+    userMessage: "errors.payment.webhook.processing_failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_WEBHOOK_VALIDATION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_WEBHOOK_VALIDATION_FAILED,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.webhook.validation_failed",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_WEBHOOK_EVENT_TYPE_UNSUPPORTED]: {
+    code: ERROR_CODES.PAYMENT_WEBHOOK_EVENT_TYPE_UNSUPPORTED,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Webhook,
+    userMessage: "errors.payment.webhook.unsupported_event_type",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_WEBHOOK_HANDLER_NOT_FOUND]: {
+    code: ERROR_CODES.PAYMENT_WEBHOOK_HANDLER_NOT_FOUND,
+    status: HTTP_STATUS.NOT_FOUND,
+    category: ERROR_CATEGORY.Webhook,
+    userMessage: "errors.payment.webhook.handler_not_found",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  // ===== Payment Adapter & Core Errors =====
+  [ERROR_CODES.PAYMENT_ADAPTER_INIT_FAILED]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_INIT_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.adapter.init_failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_SHUTDOWN_ERROR]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_SHUTDOWN_ERROR,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.adapter.shutdown_error",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_HMAC_COMPUTATION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_HMAC_COMPUTATION_FAILED,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Security,
+    userMessage: "errors.payment.adapter.hmac_computation_failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_MISSING_PROVIDER]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_MISSING_PROVIDER,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.adapter.missing_provider",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_MISSING_ENVIRONMENT]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_MISSING_ENVIRONMENT,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.adapter.missing_environment",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_MISSING_CREDENTIALS]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_MISSING_CREDENTIALS,
+    status: HTTP_STATUS.UNAUTHORIZED,
+    category: ERROR_CATEGORY.Authentication,
+    userMessage: "errors.payment.adapter.missing_credentials",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_MISSING_WEBHOOK_URL]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_MISSING_WEBHOOK_URL,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.adapter.missing_webhook_url",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_MISSING_UNREGISTER_ENDPOINT]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_MISSING_UNREGISTER_ENDPOINT,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.adapter.missing_unregister_endpoint",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_UNSUPPORTED_OPERATION]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_UNSUPPORTED_OPERATION,
+    status: HTTP_STATUS.NOT_IMPLEMENTED,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.adapter.unsupported_operation",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ADAPTER_RESPONSE_MAPPING_FAILED]: {
+    code: ERROR_CODES.PAYMENT_ADAPTER_RESPONSE_MAPPING_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.adapter.response_mapping_failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  // ===== Idempotency & State Management =====
+  [ERROR_CODES.PAYMENT_IDEMPOTENCY_VIOLATION]: {
+    code: ERROR_CODES.PAYMENT_IDEMPOTENCY_VIOLATION,
+    status: HTTP_STATUS.CONFLICT,
+    category: ERROR_CATEGORY.Processing,
+    userMessage: "errors.payment.idempotency.violation",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_IDEMPOTENCY_KEY_MISSING]: {
+    code: ERROR_CODES.PAYMENT_IDEMPOTENCY_KEY_MISSING,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.idempotency.key_missing",
+    severity: ERROR_SEVERITY.Low,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_IDEMPOTENCY_STORE_ERROR]: {
+    code: ERROR_CODES.PAYMENT_IDEMPOTENCY_STORE_ERROR,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Cache,
+    userMessage: "errors.payment.idempotency.store_error",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: true
+  },
+  // ===== Routing & Strategy =====
+  [ERROR_CODES.PAYMENT_ROUTING_FAILED]: {
+    code: ERROR_CODES.PAYMENT_ROUTING_FAILED,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Strategy,
+    userMessage: "errors.payment.routing.failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ROUTING_CONFIGURATION_INVALID]: {
+    code: ERROR_CODES.PAYMENT_ROUTING_CONFIGURATION_INVALID,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Configuration,
+    userMessage: "errors.payment.routing.configuration_invalid",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ROUTING_PROVIDER_UNAVAILABLE]: {
+    code: ERROR_CODES.PAYMENT_ROUTING_PROVIDER_UNAVAILABLE,
+    status: HTTP_STATUS.SERVICE_UNAVAILABLE,
+    category: ERROR_CATEGORY.Provider,
+    userMessage: "errors.payment.routing.provider_unavailable",
+    severity: ERROR_SEVERITY.High,
     retryable: true
   },
   // Misc
@@ -2490,6 +3021,96 @@ var ERROR_DEFINITIONS = {
     userMessage: "db.misc.invalid_count",
     severity: ERROR_SEVERITY.Medium,
     retryable: false
+  },
+  [ERROR_CODES.PAYMENT_ROUTING_RETRY_EXCEEDED]: {
+    code: ERROR_CODES.PAYMENT_ROUTING_RETRY_EXCEEDED,
+    status: HTTP_STATUS.TOO_MANY_REQUESTS,
+    category: ERROR_CATEGORY.Retry,
+    userMessage: "errors.payment.routing.retry_exceeded",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  // ===== General Payment Framework Errors =====
+  [ERROR_CODES.PAYMENT_SYSTEM_NOT_INITIALIZED]: {
+    code: ERROR_CODES.PAYMENT_SYSTEM_NOT_INITIALIZED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    userMessage: "errors.payment.system.not_initialized",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_CONTEXT_OPERATION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_CONTEXT_OPERATION_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    userMessage: "errors.payment.context.operation_failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_INTERNAL_ERROR]: {
+    code: ERROR_CODES.PAYMENT_INTERNAL_ERROR,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    userMessage: "errors.payment.internal_error",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_UNKNOWN_ERROR]: {
+    code: ERROR_CODES.PAYMENT_UNKNOWN_ERROR,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Unknown,
+    userMessage: "errors.payment.unknown_error",
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false
+  },
+  // ===== Event Lifecycle Errors =====
+  [ERROR_CODES.PAYMENT_EVENT_EMIT_FAILED]: {
+    code: ERROR_CODES.PAYMENT_EVENT_EMIT_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Processing,
+    userMessage: "errors.payment.event.emit_failed",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_EVENT_INVALID_TYPE]: {
+    code: ERROR_CODES.PAYMENT_EVENT_INVALID_TYPE,
+    status: HTTP_STATUS.BAD_REQUEST,
+    category: ERROR_CATEGORY.Validation,
+    userMessage: "errors.payment.event.invalid_type",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_EVENT_CREATION_FAILED]: {
+    code: ERROR_CODES.PAYMENT_EVENT_CREATION_FAILED,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    userMessage: "errors.payment.event.creation_failed",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_EVENT_HANDLER_TIMEOUT]: {
+    code: ERROR_CODES.PAYMENT_EVENT_HANDLER_TIMEOUT,
+    status: HTTP_STATUS.GATEWAY_TIMEOUT,
+    category: ERROR_CATEGORY.Timeout,
+    userMessage: "errors.payment.event.handler_timeout",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: true
+  },
+  [ERROR_CODES.PAYMENT_EVENT_HANDLER_INVALID_RESULT]: {
+    code: ERROR_CODES.PAYMENT_EVENT_HANDLER_INVALID_RESULT,
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    category: ERROR_CATEGORY.Processing,
+    userMessage: "errors.payment.event.handler_invalid_result",
+    severity: ERROR_SEVERITY.Medium,
+    retryable: false
+  },
+  [ERROR_CODES.PAYMENT_EVENT_LIFECYCLE_FAILURE]: {
+    code: ERROR_CODES.PAYMENT_EVENT_LIFECYCLE_FAILURE,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.Processing,
+    userMessage: "errors.payment.event.lifecycle_failure",
+    severity: ERROR_SEVERITY.High,
+    retryable: false
   }
 };