Overview

The Inquiry Details API enables retrieval of extended transaction data beyond the standard Status Inquiry response.

While the Status Inquiry endpoint provides the latest transaction state available through the query API, the Inquiry Details endpoint exposes additional contextual, operational, and method-specific information associated with the transaction lifecycle.

This chapter provides a concrete example of an Inquiry Details request and response, along with detailed annotations to guide correct interpretation and integration.

Example Request

GET <ROOT_URL>/payments/{transactionID}/status/details
Authorization: Bearer <AuthToken>
X-IBM-Client-ID: <ClientId>
Content-Type: application/json
Accept: application/json

Response Example

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "httpCode": 200,
        "httpMsg": "OK"
    },
    "payload": {
        "merchant": {
            "terminalId": 12345,
            "transactionId": "order-123",
            "merchantName": "Demo Merchant"
        },
        "customer": {
            "billingInfo": {
                "billingName": "John Doe",
                "billingEmail": "john.doe@example.com",
                "billingAddressLine1": "123 Main Street",
                "billingAddressLine2": "Suite 100",
                "billingAddressCity": "Lisbon",
                "billingAddressPostalCode": "1000-001"
            }
        },
        "operation": {
            "operationType": "AUTH",
            "operationStatus": "Success",
            "operationMethod": "CARD",
            "operationDescription": "order-123"
        },
        "mbway": {
            "inApp": false
        },
        "merchantInitiatedTransaction": {
            "type": "UCOF",
            "amountQualifier": "ESTIMATED"
        },
        "card": {
            "token": {
                "tokenValue": "tok_abc123xyz456",
                "tokenName": "Demo Token",
                "tokenType": "Card",
                "tokenExpiryDate": "2027-12-31T23:59:59.000Z",
                "tokenMaskedPAN": "411111******1111"
            }
        },
        "transaction": {
            "transactionId": "txn_987654321",
            "transactionDateTime": "2026-01-15T10:30:00.000Z",
            "amount": {
                "currency": "EUR",
                "value": 10.00
            },
            "transactionStatus": {
                "transactionStatusCode": "000",
                "transactionStatusMsg": "Success",
                "transactionStatusDescription": "Success"
            },
            "internalTransactionId": "INT-00000001"
        }
    }
}

Transaction data structures are not fixed and may vary depending on the payment method, transaction type, and processing context.

For example:

• Card-based transactions may include tokenization data with masked PAN information
• MB WAY transactions may include mobile-based tokens (e.g. phone number identifiers)
• Reference-based transactions (e.g. Multibanco Reference) may include a paymentReference block
• Certain transaction status blocks may or may not be present depending on the processing stage

All fields must be handled defensively and should not be assumed to be present in every response.

Response Structure and Interpretation

The Inquiry Details response follows a different structure from the Status Inquiry response and introduces a nested payload model for extended transaction data.

At the top level, the response includes:

• returnStatus → technical result of the request
• payload → container for extended transaction data

All transaction-related information is nested within the payload object.

returnStatus

Represents the technical execution result of the API call.

Important:

• statusCode = "000" indicates a successful API operation
• This does not imply that the transaction itself was successful and must not be interpreted as a business outcome indicator. It must be evaluated in conjunction with transaction data.

For the general response interpretation model (returnStatus vs paymentStatus), see F.2.2 – Generic Response Structure.

payload

The payload object contains extended transaction data and is composed of multiple logical sections.

The presence of each section depends on:

• Payment method
• Transaction type
• Processing context

Integrators must not assume that all blocks are always present.

merchant

Contains merchant-related information:

• terminalId → SIBS terminal identifier
• transactionId → merchant-defined transaction identifier
• merchantName → display name

customer

Provides customer-related information when available.

In this example:

• billingInfo includes name, email, and address fields

This data may not be present in all transactions.

Depending on the transaction context, additional structures such as shippingInfo may be present alongside billingInfo.

operation

Describes the operation performed:

• operationType → e.g. AUTH, PURS
• operationStatus → result of the operation
• operationMethod → payment method used

This provides contextual information about how the transaction was executed.

Examples:

• AUTH → card authorization
• PURS → purchase (e.g. MB WAY payments)
• PREF → reference generation (e.g. Multibanco Reference)

payment method-specific blocks

The payload may include blocks specific to the payment method.

Examples:

• mbway → MB WAY specific data
• card → card-related information
• paymentReference → Multibanco Reference data (not shown in this example)
  This structure is associated with deferred or reference-based payment methods and is not applicable to card-only transaction flows.

These blocks vary depending on the payment method and must be handled dynamically.

In Multibanco Reference transactions, the payload may include a paymentReference block containing reference-specific information such as payment status (e.g. UNPAID, PAID). This block is only present for reference-based payment methods (e.g. Multibanco Reference) and must not be assumed to exist for other payment types.

card.token

In card and mobile-based payment methods, the payload may include tokenization data within the card block.

Depending on the payment method, the token structure may represent:

• Card tokens (e.g. masked PAN, expiry date)
• Mobile identifiers (e.g. phone number for MB WAY, with tokenType = MobilePhone)

The presence, structure, and semantics of this block depend on the payment method and must not be assumed to be uniform.

merchantInitiatedTransaction

Provides context for recurring or MIT transactions:

• type → e.g. UCOF, RCRR
• amountQualifier → ESTIMATED or ACTUAL

This is particularly relevant for recurring and subsequent payments.

transaction

The transaction block contains core transaction data:

• transactionId → SIBS transaction identifier
• transactionDateTime → timestamp of the transaction
• amount → value and currency

transaction.transactionStatus

This block provides status-related information:

• transactionStatusCode
• transactionStatusMsg
• transactionStatusDescription

This is not equivalent to paymentStatus in the Status Inquiry response and must not be interpreted as the current or final transaction state.

This block may not be present in all transactions and must not be assumed to exist.

The structure and values of this block may also vary depending on the payment method, processing stage, and transaction lifecycle context.

Critical Distinction: Status Inquiry vs Inquiry Details

Status Inquiry:

• Returns paymentStatus
• Provides the latest transaction state available through the query API
• Should be used when no final webhook is available or when confirmation, recovery, or reconciliation is required

Inquiry Details:

• Returns transaction.transactionStatus
• Provides extended transaction information
• Must not be used to determine transaction outcome under any circumstances and must not be used to infer transaction state

For the transaction state validation model, refer to E.2.2 – Status Inquiry Endpoint Specification and E.2.3 – Response Payload Structure.

Key Integration Rules

Integrators must follow these principles:

• Use Status Inquiry (E.2 – Status Inquiry / Get Status) when no final webhook is available or when confirmation, recovery, or reconciliation is required.
• Never infer transaction success or failure from Inquiry Details
• Use Inquiry Details only for inspection, analysis, and reconciliation
• Parse payload defensively due to optional and variable fields
• Integration logic should tolerate unknown or additional payload structures without assuming a fixed schema across all transaction types
• Do not assume consistent structure across payment methods
• Do not use transaction.transactionStatus for business-critical decisions

Common Pitfalls

Using Inquiry Details as a replacement for Status Inquiry can lead to:

• Incorrect business decisions
• Misinterpretation of transaction outcomes
• Inconsistent system behavior

This API is designed for extended visibility, not transaction state validation.

Its primary purpose is to support operational diagnostics, transaction investigation, reconciliation analysis, and contextual payment inspection workflows.

See also F.7.9 – Inadequate Error Interpretation and Handling Strategy.

Summary

The Inquiry Details API provides a rich and flexible mechanism to retrieve extended transaction data across multiple payment methods.

It complements the Status Inquiry mechanism by exposing additional metadata and contextual information, enabling:

• Detailed transaction investigation
• Enhanced reconciliation workflows
• Improved operational visibility

However, it must not be used as the source for determining the current or final transaction state; use final webhook paymentStatus or Status Inquiry when required.