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

Understanding response semantics is critical to ensure:

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

Canonical Response Structure

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

POST <ROOT_URL>/api/v2/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

returnStatus

statusCode

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

statusMsg

• Human-readable description of the result

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

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

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 two-layer model:

Layer 1 – Technical Result

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

Layer 2 – Transaction State

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

Important:

• The response to POST /api/v2/payments does not represent the final transaction state
• Final state must always be confirmed via:
  • Webhooks
  • Status inquiry

Additional Clarification:

• The absence of paymentStatus in the initial response is expected and does not indicate an incomplete response
• Transaction state is established only after payment execution and subsequent status validation

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 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 authoritative transaction state

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

Key Takeaways

• Responses must be interpreted using a two-level 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.