Overview

This section defines the canonical structure of responses returned by the SIBS Payment Gateway (SPG), focusing on how responses must be interpreted, validated, and persisted.

While requests define how transactions are initiated, responses define:

• The immediate outcome of an operation
• The identifiers required for subsequent steps
• The initial state of the transaction lifecycle
• The asynchronous progression of transaction processing and validation

Understanding response semantics is critical to ensure:

• Correct transaction handling
• Reliable state management
• Consistent reconciliation across systems

For the corresponding request structure and API interaction model, see A.3 – API Requests and F.2.1 – Generic Request Structure.

Canonical Response Structure

Below is a generic example of a response returned after a successful request to:

POST <ROOT_URL>/payments

{
    "returnStatus": {
        "statusCode": "000",                     // Technical result of the API call
        "statusMsg": "Success"
    },
    "transactionID": "s2ExampleTx123456789",   // SPG unique transaction identifier
    "merchant": {
        "merchantTransactionId": "ORDER-001"     // Echoed merchant identifier
    },
    "paymentMethodList": [
        "CARD",
        "MBWAY"
    ],
    "execution": {
        "startTime": "2026-04-16T10:15:30.050Z",
        "endTime": "2026-04-16T10:15:30.210Z"
    }
}

Top-Level Structure

A typical response includes:

• returnStatus → Technical result of the API operation
• transactionID → Primary identifier for all subsequent interactions
• merchant → Echo of merchant identifiers
• Additional contextual blocks depending on the operation

Not all fields are present in every response. The structure varies depending on:

• The endpoint
• The payment method
• The stage of the transaction lifecycle
• The type of operation being executed

returnStatus

statusCode

• "000" indicates successful processing of the API request
• Other values indicate errors or validation issues

Detailed status code semantics and operational error interpretation guidance are available in:

• C.5 – Status Codes and Error Codes Mapping
• C.6 – Error Payloads and Handling Guidelines

statusMsg

• Human-readable description of the result

statusDescription

• Additional contextual detail about the operational result of the request.
• May provide:
  • Detailed validation context
  • Operational outcome clarification
  • Acquirer or payment-method-specific information

Important:

• returnStatus reflects the technical result of the API call, not the final outcome of the payment
• A successful statusCode ("000") does not guarantee that the payment is completed or successful
• statusDescription should be interpreted together with:
  • returnStatus.statusCode
  • paymentStatus
• Subsequent webhook notifications
• Status inquiry responses

transactionID

• Unique identifier generated by SPG
• Required for:
  • All subsequent API operations
  • Status inquiries
  • Correlation with webhook notifications

Important:

• Must be persisted immediately after receipt and used as the primary SPG identifier for all subsequent operations and status inquiries. Merchant-defined identifiers must not be used as substitutes.
• Acts as the primary reference across the entire transaction lifecycle

merchant.merchantTransactionId

• Echo of the value provided in the request
• Used for:
  • Internal reconciliation
  • Cross-system correlation

Important:

• Should be stored together with transactionID
• Enables mapping between SPG transactions and merchant systems

paymentMethodList

• Lists the payment methods enabled for the transaction
• Derived from the original request and merchant configuration

This list represents the payment methods configured and available for execution within the transaction context.

Important:

• Defines what can be executed in subsequent steps
• Does not indicate that any payment has been performed

execution block

startTime / endTime

• Timestamps representing processing duration within SPG

Usage:

• Monitoring and diagnostics
• Performance analysis

Note:

• Not required for transaction processing logic

Response Interpretation Model

Responses must be interpreted using a layered validation and transaction-state model:

Layer 1 – Technical Result

• Determined by returnStatus
• Indicates:
  • Whether the request was accepted
  • Whether validation passed

The HTTP response code reflects the transport-level result of the request, while returnStatus.statusCode provides the technical classification of the operation at API level.

An HTTP success response (e.g., 200 OK) does not guarantee that the API operation was successful. The returnStatus.statusCode must always be evaluated to determine the actual result of the request.

Similarly, successful API processing does not necessarily indicate that the payment itself was authorized, captured, completed, or financially successful.

Layer 2 – Transaction State

• Determined by:
  • paymentStatus (when present in subsequent responses or status inquiries)
  • Webhook notifications
  • Status endpoint (GET <ROOT_URL>/payments/{transactionID}/status)

Important:

• The response to POST <ROOT_URL>/payments does not represent the final transaction state
• Final state may be determined via:
  • Webhooks
  • Status inquiry

Additional Clarification:

• The absence of paymentStatus in the initial response is expected and does not indicate an incomplete or invalid response
• paymentStatus is associated with transaction execution and lifecycle progression rather than checkout creation itself
• Transaction state is only established after payment execution and subsequent validation steps.

Additional transaction monitoring and validation guidance is available in E. Notifications and Transaction Status.

Persistence Requirements

After receiving a response, the following data must be persisted:

• transactionID
• merchantTransactionId
• Relevant timestamps (optional but recommended)

Important:

Failure to persist transactionID will prevent:

• Execution of payment operations
• Status validation
• Webhook correlation

Common Pitfalls

1. Misinterpreting statusCode as payment result

• "000" only confirms request success
• Does not indicate payment success

2. Not persisting transactionID

• Leads to inability to:
  • Continue the flow
  • Query status
  • Process webhooks correctly

3. Assuming synchronous completion

• Some methods:
  • Require user interaction
  • Are asynchronous by design

4. Ignoring subsequent state validation

• Relying only on initial response
• Not using:
  • Webhooks
  • Status endpoint

Execution Context

This response corresponds to:

• Step 1 – Create Checkout (see F.1 – End-to-End Integration Examples)

It provides:

• The identifiers required for subsequent steps
• The initial confirmation that the transaction has been created

Subsequent operations will:

• Use the transactionID
• Produce additional responses with extended data structures

Relationship with Other Responses

Different API operations return extended response structures, including:

• Payment execution responses → may include paymentStatus
• Webhook notifications → provide asynchronous state updates
• Status inquiry responses → provide the latest transaction state available through the query API
• Inquiry Details responses → provide extended operational metadata, tokenization context, recurring payment information, authentication details, and additional transaction lifecycle attributes

This section defines the baseline structure upon which those responses are built.

Key Takeaways

• Responses must be interpreted using a layered validation and transaction-state model:
  • Technical (returnStatus)
  • Transactional (paymentStatus and subsequent validation)
• transactionID is the central identifier for all operations
• Initial responses do not represent final transaction outcomes
• Correct persistence and interpretation of response data is essential for:
  • Reliable transaction processing
  • Consistent reconciliation
  • Robust production integrations

This section establishes the foundation for all response handling logic in SPG integrations.