Overview

This section defines the operational meaning, lifecycle behavior, and expected merchant actions associated with each transaction state represented by the paymentStatus field.

While:

• C.1 – Transaction Meta Information Structure defines the structure of transaction responses
• C.2 – Field Semantics and Validation Rules defines validation and interpretation rules

This section defines:

• what each transaction state represents
• whether the state is final or transitional
• what actions merchant systems must take
• how edge cases must be handled

The objective is to ensure deterministic, safe, and consistent business behavior across all SPG integrations.

The transaction states defined in this section represent the business outcome layer and must be interpreted in conjunction with the technical processing layer defined by returnStatus.

Transaction State Model

The paymentStatus field represents the current lifecycle state of a transaction.

Supported values include:

• Success
• Pending
• Declined
• Error
• Timeout

Each state must be interpreted according to its defined operational semantics and not inferred solely from its label.

State Classification

Final States

• Success
• Declined
• Error
• Timeout

Non-Final States

• Pending

Operational Rule

• Final states → terminal
• Non-final states → transitional

Merchant systems must:

• never trigger irreversible actions on non-final states
• only act definitively on final states

1. Success

Meaning

The transaction has been successfully completed.

Characteristics

• Funds are:
  • authorized (AUTH)
  • captured (PURS / CAPTURE)
  • confirmed according to flow
• No further customer interaction required

State Type

Final

Merchant Actions

• Fulfill order
• Grant service access
• Record transaction as completed

Notes

• In two-step flows (AUTH → CAPTURE):
  • a Success state after authorization indicates successful authorization, not final settlement of funds
  • Capture may still be required to complete the financial transaction.

2. Pending

Meaning

The transaction is awaiting external action or confirmation.

Typical Scenarios

• Customer has not yet completed payment
• Awaiting user interaction (e.g., mobile approval)
• Awaiting external system confirmation

State Type

Non-final

Merchant Actions

• Do not fulfill order
• Wait for:
  • webhook notification
  • or status query update

Operational Handling

• Implement timeout/retry strategy
• Monitor transition to final state

3. Declined

Meaning

The transaction was rejected at business level.

Typical Causes

• Insufficient funds
• Authentication failure
• User rejection
• Risk controls / fraud prevention

State Type

Final

Merchant Actions

• Do not fulfill order
• Notify customer
• Allow retry with alternative method

Notes

• Often accompanied by meaningful statusDescription
• May occur:
  • before authorization
  • after authentication
  • after initial success (edge case)

4. Error

Meaning

A technical failure occurred during processing.

Typical Causes

• System errors
• Integration issues
• Communication failures
• Internal processing errors

State Type

Final

Merchant Actions

• Do not fulfill order
• Log error
• Retry operation if appropriate

Operational Handling

• Distinguish between:
  • transient errors → retry
  • persistent errors → manual intervention

5. Timeout

Meaning

The transaction was not completed within the allowed time window.

Typical Scenarios

• Customer did not complete action in time
• Payment session expired
• External confirmation not received

State Type

Final

Merchant Actions

• Do not fulfill order
• Allow user to restart payment

Notes

• Common in:
  • mobile approval flows
  • redirect-based payments

State Transitions

Typical Transition Patterns

Synchronous Flow

Pending → Success / Declined / Error

Asynchronous Flow

Pending → Success / Declined / Timeout

Abandoned Flow

Pending → Timeout

For a formal definition of allowed state transitions and transition constraints, refer to C.4 – Transaction State Transition Model.

Important Rules

• Transitions are not guaranteed to be linear
• Intermediate states may be skipped
• API responses may show non-final states; final-state webhooks normally communicate the definitive outcome

Edge Cases and Special Scenarios

1. Post-Authorization Refusal

Scenario

• Transaction initially appears successful
• Later rejected by cardholder or system

Example

• statusDescription:
  “After the operation was successful, was refused by the cardholder.”

Handling

• Merchant systems must confirm the final state via status inquiry
• Do not rely on intermediate success

2. Abandoned Transactions

Scenario

• Customer does not complete required action

Example

• statusDescription:
  “Card holder abandoned the transaction (push notification not accepted nor refused)”

Handling

• Treat as:
  • Timeout (final)
• Allow retry

3. Delayed Confirmation

Scenario

• Payment confirmed asynchronously

Handling

• Final-state webhook may arrive after the initial response
• Use Status Inquiry if webhook delivery or processing is uncertain, or if the current state must be retrieved explicitly

Channel Interpretation Rules

API Response

• Represents initial state
• May be Pending

Webhook Notification

• Normally communicates a final transaction state
• Must be processed asynchronously and idempotently

Status Query

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

For detailed specifications of the status inquiry mechanism, refer to E.2 – Status Inquiry / Get Status.

Operational Best Practices

Merchant systems must:

• Treat paymentStatus as the single source of truth for business outcome
• Never act on non-final states
• Implement:
  • webhook processing
  • status polling fallback
• Ensure idempotent handling of repeated events
• Log:
  • state transitions
  • statusDescription (for diagnostics)

State Handling Matrix

Summary

This section defines the operational meaning of transaction states and how they must drive merchant behavior.

Correct implementation ensures:

• safe handling of asynchronous flows
• correct distinction between intermediate and final states
• avoidance of premature fulfillment
• resilience to edge cases and delayed confirmations

This model must be consistently applied across all payment methods and integration models within SPG.