Overview

The Status Inquiry response provides the current structured representation of a transaction, including its latest transaction state available through the query API, processing result, and associated metadata.

This structure is consistent across payment methods, combining mandatory core fields with optional extension blocks depending on the payment method and transaction context.

Response Model Overview

The response is composed of the following logical components:

• Result and Status Information
• Core Transaction Data
• Contextual Metadata
• Optional Extension Blocks

Top-Level Structure

A typical response follows this structure:

{
    "returnStatus": { ... },
    "paymentStatus": "...",
    "paymentMethod": "...",
    "transactionID": "...",
    "transactionDateTime": "...",
    "amount": { ... },
    "merchant": { ... },

    // Optional blocks
    "token": { ... },
    "paymentReference": { ... },
    "mbwayMandate": { ... },
    "merchantInitiatedTransaction": { ... }
}

Core Fields

returnStatus

Represents the technical result of the operation.

Important:

• statusCode = "000" indicates a successful operation
• This does not necessarily mean that the payment was successful

paymentStatus

Represents the business state of the transaction.

This is the primary field for business decision-making.

paymentMethod

Identifies the payment method used.

Typical values include:

• CARD
• MBWAY
• REFERENCE
• MANDATE

transactionID

Unique identifier assigned by SIBS.

• Corresponds to the transactionID associated with the transaction lifecycle
• Serves as the primary identifier across all transaction operations

transactionDateTime

Timestamp of the latest known transaction state.

• Format: ISO 8601
• Represents the most recent state transition recorded by SIBS

amount

Transaction amount details.

merchant

Merchant-related information.

Optional Extension Blocks

Additional blocks may be present depending on the payment method and transaction type.

Integrators must not assume their presence and must implement defensive parsing to handle missing blocks gracefully.

token

Present in tokenization scenarios.

paymentReference

Present for Multibanco Reference payments.

mbwayMandate

Present in MB WAY mandate operations.

merchantInitiatedTransaction

Present in recurring payment scenarios.

Field Semantics and Interpretation

• returnStatus reflects the technical execution result
• paymentStatus reflects the business outcome of the transaction

Both fields must be evaluated together.

Detailed transaction-state interpretation semantics are described in E.2.4 – Status Semantics and Interpretation.

Examples

Relationship with Webhook Payloads

The Status Inquiry response structure is aligned with webhook payloads, enabling:

• Reuse of compatible parsing and validation logic
• Consistent data handling across integration flows
• Simplified implementation

However:

• Webhooks represent events in time
• Status Inquiry APIs return the latest transaction state available through the query API

Webhook payload structures and payment-method-specific webhook variants are described in E.1.2 – Webhook Payload Variants by Payment Method.

Handling Optional Fields

• Not all fields are present in every response
• Integrators must:
  • Implement defensive parsing
  • Avoid strict schema assumptions
  • Handle missing fields gracefully

For extended transaction data beyond the standard Status Inquiry response structure, use the Inquiry Details API described in E.2.10 – Inquiry Details API and E.2.11 – Inquiry Details Endpoint Specification.

The Inquiry Details API may return additional metadata and contextual information that is not present in the standard Status Inquiry response and must be handled using the same defensive parsing principles.

Consistency Guarantees

• The response reflects the most up-to-date transaction state available at query time
• Depending on the payment method and transaction lifecycle stage, the returned state may continue to evolve asynchronously until final operational resolution is reached
• It must be used to validate:
  • Final transaction outcomes
  • State transitions after webhook reception

This validation should be performed using the Status Inquiry APIs when no final webhook is available or when additional confirmation is required. Extended data retrieved through the Inquiry Details API must not be used to determine transaction outcomes or to infer transaction state.

For more details, refer to:

• E.2.6 – Consistency Model: Query vs Webhook
• C.3 – Transaction States and Operational Meaning

Example Response (Extended)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "123456789",
    "transactionDateTime": "2025-02-20T10:15:30Z",
    "amount": {
        "value": 100.00,
        "currency": "EUR"
    },
    "merchant": {
        "merchantTransactionId": "order-123",
        "terminalId": 12345,
        "merchantName": "Demo Merchant"
    },
    "token": {
        "tokenType": "Card",
        "value": "abc123xyz"
    }
}

Key Integration Principles

• Use paymentStatus for business decision-making, interpreted together with returnStatus and the transaction context
• Validate final state using the Status Inquiry APIs when no final webhook is available or when additional confirmation is required
• Do not assume presence of optional fields
• Reuse compatible parsing and validation logic for webhook and status responses

Summary

The Status Inquiry response structure provides a standardized and extensible representation of transaction data, enabling:

• Consistent integration across payment methods
• Unified handling of synchronous and asynchronous flows
• Reliable interpretation of transaction outcomes

It forms the foundation for robust, scalable, and maintainable payment integrations within the SIBS Payment Gateway ecosystem.