Overview

While SPG provides a unified API-level error model, error behavior and interpretation vary significantly depending on the payment method being used.

This section defines the payment method-specific characteristics of error domains, highlighting how different payment methods:

• produce different types of errors
• expose different failure conditions
• require different handling strategies

These differences must be considered together with:

• the API-level model (see C.5.1 API-Level Status Codes)
• the error categorization and responsibility model (see C.5.2 Error Code Categories and Responsibility Model)
• the operational error codes (see C.5.3 Legacy / Detailed Error Codes)

MB WAY

MB WAY errors are strongly influenced by user interaction and mobile device behavior.

Characteristics

• dependent on user approval in the mobile app
• sensitive to time constraints (short authorization window)
• strongly tied to alias validation and device state
• includes mandate-based flows (authorized payments)

Common Error Patterns

• invalid or non-existent alias
• alias duplication or format issues
• user rejection or non-confirmation
• timeout during authorization
• duplicate transaction attempts

Handling Implications

• user-related errors must not be retried automatically
• alias-related errors require validation and correction
• timeout scenarios may require retry with user awareness
• duplicate scenarios require transaction reconciliation

Operational Considerations

• flows are inherently asynchronous
• final outcome must be validated via status inquiry or webhook
• mandate-related errors require lifecycle-aware handling

Multibanco Reference

Multibanco errors are primarily related to reference generation and lifecycle management.

Characteristics

• based on generation of payment references
• strongly dependent on parameter validation
• involves delayed user payment (asynchronous completion)

Common Error Patterns

• invalid entity or reference configuration
• invalid amount, currency, or time window
• reference already paid or cancelled
• reference not found

Handling Implications

• parameterization errors must be corrected before retry
• lifecycle errors require reconciliation (paid, expired, cancelled)
• reference generation must be validated before presenting to user

Operational Considerations

• payment completion occurs outside the system
• requires status monitoring or webhook processing
• reference lifecycle must be explicitly managed

Card Payments

Card payment errors are influenced by issuer decisions and authentication flows.

Characteristics

• dependent on card issuer authorization
• includes fraud checks and risk evaluation
• may involve strong customer authentication (e.g., 3DS)
• supports multi-step flows (AUTH, CAPTURE, REFUND)

Common Error Patterns

• insufficient funds
• invalid card details (number, expiry, CVV)
• card status issues (expired, blocked, cancelled)
• issuer declines
• authentication failures

Handling Implications

• issuer declines must not be retried automatically
• validation errors must be corrected before retry
• authentication failures require user re-interaction
• multi-step operations require state validation before execution

Operational Considerations

• supports both synchronous and asynchronous flows
• requires handling of authorization lifecycle
• reconciliation between AUTH and CAPTURE is critical

Authorized Payments / Recurring Operations

Recurring and authorized payment flows introduce stateful and lifecycle-dependent error conditions.

Characteristics

• dependent on prior authorization or mandate
• involve repeated or scheduled operations
• strongly tied to transaction and mandate state

Common Error Patterns

• invalid or missing authorization context
• expired or cancelled authorization
• invalid token or identification
• operation not allowed due to state

Handling Implications

• must validate authorization state before execution
• must not retry blindly without verifying context
• requires reconciliation with mandate or token lifecycle

Operational Considerations

• highly sensitive to state consistency
• requires strict correlation between operations
• errors often indicate incorrect lifecycle handling or state misalignment

Cross-Method Differences

Although all payment methods share the same API-level structure, their behavior differs significantly.

Dimension	MB WAY	Multibanco	Card
User Interaction	High	Low (offline)	Medium
Synchrony	Asynchronous	Asynchronous	Mixed
Error Source	User / Device	Configuration / Lifecycle	Issuer / Network
Retry Behavior	User-driven	Lifecycle-dependent	Context-dependent
State Sensitivity	Medium	High	High

These differences must be considered when designing integration logic.

Handling Strategy Alignment

Error handling must adapt to the payment method while remaining consistent with the global model:

• apply C.5.2 Error Code Categories and Responsibility Model categorization and responsibility rules
• use C.5.3 Legacy / Detailed Error Codes operational codes for detailed diagnosis
• use C.5.1 API-Level Status Codes API-level codes for initial classification

At the same time:

• avoid applying uniform retry strategies across methods
• account for method-specific timing, lifecycle, and dependencies
• ensure that transaction state is always validated before further actions

Implementation Considerations

Merchant systems must:

• implement payment method-aware error handling logic
• adapt retry and validation strategies per method
• ensure proper synchronization with transaction state
• handle asynchronous completion consistently
• integrate error handling with webhook and status mechanisms

Failure to consider payment method differences may result in:

• incorrect retries
• invalid transaction flows
• inconsistent user experience
• reconciliation issues

Final Consideration

Payment method-specific error domains represent the behavioral layer of SPG error handling.

They complement:

• C.5.1 API-Level Status Codes → API-level response structure
• C.5.2 Error Code Categories and Responsibility Model → error categorization and responsibility
• C.5.3 Legacy / Detailed Error Codes → detailed operational diagnostics

A correct implementation requires combining all these layers while adapting behavior to the specific characteristics of each payment method.

This ensures accurate, reliable, and production-ready handling of all SPG payment scenarios.