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.

The semantics and validation rules defined in this section must always be applied in the context of the structural model defined in C.1 – Transaction Meta Information Structure.

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

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
  • 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

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

These consistency rules must be interpreted within the multi-layer response model, where:

• returnStatus represents the technical processing layer
• paymentStatus represents the business outcome layer

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, not guaranteed stable, and must not be relied upon for deterministic processing.

Rule

• Must not be used for:
  • business decisions
  • automated branching logic
• Must only be used for:
  • logging
  • debugging
  • diagnostic purposes

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 Inquiry response retrieves the current transaction state when explicit status retrieval or reconciliation is required

For a complete reconciliation strategy across asynchronous flows, refer to C.7 – State Reconciliation: Query vs Webhook.

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 a webhook notification. This field is only present in webhook payloads.

Validation Rules

• Must only be expected 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 a decimal numeric value without locale-dependent formatting
• 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 or transient processing issues)

Non-Retryable

• Business outcomes (Declined)

Idempotency Rule

Merchant systems must ensure:

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

These rules must be applied in conjunction with the error payload structure and handling guidelines defined in C.6 – Error Payloads and Handling Guidelines.

10. Channel-Specific Rules

API Responses

• Represent initial state
• May be non-final

Webhooks

• Normally communicate final transaction states
• Must be processed asynchronously and idempotently

Status Query

• Retrieves the current transaction state
• Must be used when explicit status retrieval or recovery is required

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
• Use Status Inquiry when explicit verification or recovery is required
• 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.