Overview

The Status Inquiry response provides the current structured representation of a transaction, including its state, 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.

• Must match the transactionID used in the request
• 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.

Examples

Relationship with Webhook Payloads

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

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

However:

• Webhooks represent events in time
• Status Inquiry returns the latest known transaction state

Handling Optional Fields

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

Consistency Guarantees

• The response reflects the most up-to-date transaction state available at query time
• It must be used to validate:
  • Final transaction outcomes
  • State transitions after webhook reception

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": {
        "transactionID": "order-123",
        "terminalId": 12345,
        "merchantName": "Demo Merchant"
    },
    "token": {
        "tokenType": "Card",
        "value": "abc123xyz"
    }
}

Key Integration Principles

• Always use paymentStatus for business decision-making
• Always validate final state using Status Inquiry
• Do not assume presence of optional fields
• Reuse the same parsing logic for webhooks 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.