Overview

This section defines the functional semantics, validation rules, and constraints associated with the fields present in SPG transaction responses.

While C.1 Transaction Meta Information Structure describes the structure of the response model, this section defines:

• how each field must be interpreted
• how values must be validated
• how fields relate to each other
• how inconsistencies must be handled

The objective is to ensure that merchant systems can implement deterministic, robust, and unambiguous interpretation logic across all SPG integrations.

Field Classification

SPG fields can be classified into the following categories:

• Technical outcome fields
• Business outcome fields
• Identification fields
• Financial fields
• Contextual fields
• Extension fields

1. Technical Outcome Fields

returnStatus.statusCode

Semantics

Represents the technical result of the operation execution.

Validation Rules

• Must always be present in transaction-related responses
• Must be treated as a string and must not be interpreted as a numeric value
• "000" represents successful execution

Interpretation Rules

• Indicates whether the request was processed correctly by SPG
• Does not guarantee payment success

returnStatus.statusMsg

Semantics

Represents a high-level classification of the operation result.

Typical values:

• Success
• Pending
• Declined
• Error
• InProcessing

Validation Rules

• Must be present when returnStatus is present
• Must be treated as an enumeration-like string
• Must not be used as the sole decision driver

returnStatus.statusDescription

Semantics

Provides a human-readable, contextual description of the result.

Validation Rules

• May be present in:
  • status query responses
  • webhook notifications
  • operational responses
• Must be treated as free text
• Must not be used for programmatic branching

Interpretation Rules

• Provides additional detail for:
  • declined transactions
  • abandoned flows
  • timeouts
  • post-authorization refusals
• Should be:
  • logged
  • stored when relevant
  • used for support and diagnostics

2. Business Outcome Fields

paymentStatus

Semantics

Represents the current lifecycle state of the transaction.

Validation Rules

• Must always be present in transaction state responses
• Must be treated as a controlled enumeration
• Expected values include:
  • Success
  • Pending
  • InProcessing
  • Declined
  • Error
  • Timeout

Interpretation Rules

• This is the primary field for business logic
• Determines:
  • whether payment is completed
  • whether action is required
  • whether the state is final

Final vs Non-Final States

Final States

• Success
• Declined
• Error
• Timeout

Non-Final States

• Pending
• InProcessing

Validation Rule

• Merchant systems must treat non-final states as transitional
• Final states must be treated as terminal

Operational Rule

Only final states must trigger irreversible actions such as:

• order fulfillment
• settlement
• service activation

3. Cross-Field Consistency Rules

Rule 1 — statusCode vs paymentStatus

Constraint

• statusCode = "000" does not imply paymentStatus = Success

Example

• statusCode = "000" + paymentStatus = Declined → valid scenario

Rule

Merchant systems must always evaluate paymentStatus as the authoritative business outcome.

Rule 2 — statusMsg vs paymentStatus

Constraint

• statusMsg may not fully reflect the final transaction state

Rule

• paymentStatus must take precedence over statusMsg

Rule 3 – statusDescription usage

Constraint

• statusDescription is not normalized nor guaranteed stable

Rule

• Must not be used for:
  • business decisions
  • automated branching logic
• May be used for:
  • logging
  • debugging
  • operator visibility

Rule 4 – Channel Consistency

Constraint

The same transaction may produce different representations across:

• API response
• webhook notification
• status query

Rule

• Merchant systems must reconcile using:
  • transactionID
  • status query response as source of truth

4. Identification Fields

transactionID

Semantics

Unique SPG transaction identifier.

Validation Rules

• Must be present
• Must be treated as opaque string
• Must not be parsed or interpreted

Usage Rules

• Must be stored
• Must be used for:
  • status queries
  • capture/refund operations
  • reconciliation

merchant.transactionId

Semantics

Merchant-defined identifier.

Validation Rules

• Must be treated as opaque string
• May be used for correlation on merchant side

notificationID

Semantics

Unique identifier of webhook notification.

Validation Rules

• Must be present in webhook payloads
• Must be unique per notification

Usage Rules

• Must be used for:
  • idempotent processing
  • duplicate detection
  • logging

5. Financial Fields

amount.value

Validation Rules

• Must be numeric
• Must be treated as decimal
• Must not rely on locale formatting

amount.currency

Validation Rules

• Must follow ISO 4217 format (e.g., EUR)
• Must be treated as uppercase string

Consistency Rule

• Amount must remain consistent across:
  • authorization
  • capture
  • refund (within allowed constraints)

6. Contextual Fields

paymentMethod

Validation Rules

• Must be treated as enumeration
• Must determine:
  • expected extension blocks
  • flow behavior

paymentType

Validation Rules

• Must be treated as enumeration
• Must define:
  • operation context
  • expected lifecycle transitions

7. Extension Fields

General Rules

Extension fields:

• Must be treated as optional
• Must not be assumed present
• Must be validated before use

Validation Rule

If field exists → validate structure
If field does not exist → ignore safely

Examples

• paymentReference
• token
• mbwayMandate
• merchantInitiatedTransaction

8. Temporal Fields

transactionDateTime

Validation Rules

• Must follow ISO 8601 format
• Must be treated as UTC unless otherwise specified

Usage Rules

• Used for:
  • ordering events
  • reconciliation
  • audit trails

9. Error Handling Rules

Retry vs Non-Retry

Retryable

• Technical failures (Error, transient issues)

Non-Retryable

• Business outcomes (Declined)

Idempotency Rule

Merchant systems must ensure:

• duplicate requests do not produce duplicate effects
• webhook replays are safely handled

10. Channel-Specific Rules

API Responses

• Represent initial state
• May be non-final

Webhooks

• Represent state transitions
• Must be processed asynchronously

Status Query

• Must be treated as authoritative source of truth

11. Validation Checklist (Implementation-Oriented)

Merchant systems must:

• Validate presence of required fields
• Treat identifiers as opaque values
• Use paymentStatus as primary decision field
• Use statusCode only for technical validation
• Never rely on statusDescription for logic
• Validate optional fields defensively
• Reconcile webhook vs status API
• Ensure idempotent processing
• Handle non-final states correctly

Summary

This section defines the semantic contract and validation model for SPG transaction fields.

Correct implementation ensures:

• deterministic interpretation of responses
• robust handling of asynchronous flows
• elimination of ambiguity between technical and business outcomes
• safe and scalable payment processing logic

This model must be consistently applied across all SPG integrations, payment methods, and operational flows.