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.

Transaction State Model

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

Supported values include:

• Success
• Pending
• InProcessing
• Declined
• Error
• Timeout

Each state must be interpreted according to its operational semantics, not solely by its name.

State Classification

Final States

• Success
• Declined
• Error
• Timeout

Non-Final States

• Pending
• InProcessing

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:
  • Success after AUTH ≠ funds captured
  • Capture may still be required depending on flow

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. InProcessing

Meaning

The transaction is being actively processed by SPG or external systems.

Typical Scenarios

• Ongoing authorization
• Communication with acquirer or payment network
• Internal SPG processing

State Type

Non-final

Merchant Actions

• Same as Pending:
  • no fulfillment
  • wait for final state

Notes

• Usually short-lived
• May transition to:
  • Success
  • Declined
  • Error

4. 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)

5. 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

6. 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

InProcessing → Success / Declined / Error

Asynchronous Flow

Pending → InProcessing → Success / Declined / Timeout

Abandoned Flow

Pending → Timeout

Important Rules

• Transitions are not guaranteed to be linear
• Intermediate states may be skipped
• Webhook and API may show different intermediate states

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

• Always confirm final state via status query
• 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

• Webhook may arrive after initial response
• Status query must be used for reconciliation

Channel Interpretation Rules

API Response

• Represents initial state
• May be:
  • Pending
  • InProcessing

Webhook Notification

• Represents state transition event
• Must be processed asynchronously

Status Query

• Represents authoritative state
• Must be used for:
  • reconciliation
  • final confirmation

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.