Overview

The SIBS Payment Gateway (SPG) uses a structured and consistent response model to represent transaction meta information across API responses, webhook notifications, and transaction status queries.

This model defines how transaction-related information is returned by SPG and how merchant systems must interpret the different structural blocks present in each response.

This structure must be interpreted in conjunction with the response interpretation model defined in C. Meta Information, Codes and Transaction States, particularly the distinction between technical processing results and business outcomes.

Although specific fields may vary depending on the payment method, operation type, and communication channel, SPG responses follow a common logical structure composed of:

• operation result information
• transaction identification
• transaction state information
• merchant context
• financial context
• optional method-specific extension blocks

This common structure is the basis for deterministic transaction processing, reconciliation, and troubleshooting.

Standard Response Structure

A typical SPG transaction response contains a core set of common fields and may be extended with operation-specific or payment-method-specific blocks.

Canonical structure

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000",
        "statusDescription": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2grnvtruigbitu845hhtn",
    "transactionDateTime": "2022-11-11T16:18:53.127Z",
    "amount": {
        "currency": "EUR",
        "value": 19.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008mvn432kop",
        "terminalId": 99978,
        "merchantName": "MERCHANT DOT COM"
    },
    "paymentType": "PURS"
}

This model represents the core meta-information envelope used by SPG.

Additional blocks may be appended depending on the operation, such as paymentReference, token, merchantInitiatedTransaction, mbwayMandate, internalTransactionId, or notificationID.

Figure – SPG Transaction Meta Information Structure

Core Structure

1. returnStatus

The returnStatus object represents the technical result returned by SPG for the processed operation.

Typical structure:

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000",
        "statusDescription": "Success"
    }
}

Fields

• statusCode
  Technical result code associated with the operation.
• statusMsg
  High-level result classification, such as Success, Pending, Declined, or Error.
• statusDescription
  Human-readable description associated with the returned status.
  When the operation is successful, this field may simply repeat the high-level meaning, for example, Success.

Important interpretation rule

returnStatus describes the technical or protocol-level result returned by SPG and must not be interpreted in isolation as the business outcome of the transaction.

Merchant systems must always evaluate returnStatus together with paymentStatus.

Typical examples of statusDescription

Examples observed in real SPG behavior include:

• Success
• Card holder abandoned the transaction (push notification not accepted nor refused)
• After the operation was successful, was refused by the cardholder.
• Issue with the Operation (declined).

These examples confirm that statusDescription is not merely decorative. It provides meaningful operational detail and should be logged, stored when relevant, and used for support and troubleshooting scenarios.

For detailed error handling strategies and interpretation patterns, refer to C.6 – Error Payloads and Handling Guidelines.

2. paymentStatus

The paymentStatus field represents the current business state of the transaction lifecycle.

Typical values include:

• Success
• Pending
• Declined
• Error
• Timeout

This is the primary field that merchant systems must use to determine the operational state of the transaction.

Use of paymentStatus

paymentStatus must be used to determine whether:

• the payment has been completed successfully
• the transaction is still awaiting completion
• further action is required
• the transaction reached a non-success final state

In asynchronous flows, paymentStatus must be validated against the latest server-to-server status inquiry whenever finality is required.

For the complete definition of transaction states and their operational meaning, refer to C.3 – Transaction States and Operational Meaning.

3. paymentMethod

The paymentMethod field identifies the payment instrument or payment family used in the operation.

Typical values include:

• CARD
• MBWAY
• REFERENCE
• TOKEN
• MANDATE

This field determines how payment-method-specific data and extension blocks must be interpreted.

4. paymentType

The paymentType field identifies the operation type being represented.

Typical examples include:

• PURS – purchase
• AUTH – authorization
• CAPT – capture
• CAUT – authorization cancellation
• RFND – refund
• MITR – merchant initiated transaction
• PREF – reference generation

This field provides the transactional context necessary to correctly interpret the rest of the payload.

5. transactionID

The transactionID field is the SPG-generated identifier of the transaction.

This identifier must be treated as a core reference key and must be stored by the merchant system for:

• transaction status inquiries
• post-payment operations
• reconciliation
• troubleshooting
• log correlation

6. transactionDateTime

The transactionDateTime field represents the transaction timestamp associated with the returned event or transaction record.

Format:

• ISO 8601
• typically UTC-based

Example:

"transactionDateTime": "2022-11-11T16:18:53.127Z"

7. amount

The amount block represents the financial amount associated with the transaction.

Typical structure:

"amount": {
    "currency": "EUR",
    "value": 19.2
}

Fields

• currency – ISO 4217 currency code
• value – transaction amount

8. merchant

The merchant block provides merchant-side contextual information associated with the transaction.

Typical structure:

"merchant": {
    "transactionId": "863b730df285443ca404e008mvn432kop",
    "terminalId": 52221,
    "merchantName": "MERCHANT NAME"
}

Fields

• transactionId – Merchant-defined transaction identifier
• terminalId – SIBS-assigned terminal identifier
• merchantName – Merchant display or business name, when present

This block is essential for reconciliation between SPG and merchant systems.

Within this structure, not all fields have the same decision-making weight. In particular:

• paymentStatus must be treated as the primary driver of transaction state and business decisions
• returnStatus provides the technical execution context and must not be used alone to determine transaction success
• transactionID must be treated as the authoritative transaction identifier across all operations

Common Extension Blocks

In addition to the core structure, SPG responses may include conditional blocks depending on the operation and payment method.

paymentReference

Used mainly in Multibanco Reference flows.

"paymentReference": {
    "reference": "256309828",
    "entity": "40200",
    "paymentEntity": "40200",
    "amount": {
        "value": "20.0",
        "currency": "EUR"
    },
    "status": "UNPAID",
    "expiryDate": "2022-01-23T10:48:39.153Z"
}

token

Used in token generation or token-based payment contexts.

"token": {
    "tokenType": "Card",
    "value": "gbtyhyujyuikuier45646ger4"
}

merchantInitiatedTransaction

Used in MIT contexts.

"merchantInitiatedTransaction": {
    "type": "UCOF",
    "amountQualifier": "ESTIMATED"
}

mbwayMandate

Used in Authorized Payments / mandate-related scenarios.

"mbwayMandate": {
    "mandateIdentification": "12345690656800744652",
    "mandateAction": "CRTN",
    "mandateActionStatus": "SCCS",
    "mandateType": "SBSC"
}

internalTransactionId

SPG internal transaction correlation field, present in some responses and webhook examples.

notificationID

Used in webhooks to uniquely identify the notification sent by SPG.

This field is important for webhook processing, acknowledgement tracking, and log correlation.

Response Variants by Communication Channel

The meta-information model is structurally consistent, but field presence and emphasis vary depending on the communication channel.

API responses

Synchronous API responses usually provide the initial operation result and may represent either:

• a final transaction state
• a non-final transaction state requiring subsequent validation

In these responses, returnStatus provides the technical outcome of the call and paymentStatus provides the transaction state known at that point in time.

Webhook notifications

Webhook notifications communicate transaction-status updates. For payment transactions, they normally communicate final transaction states. Multibanco Reference Generation is the relevant exception, as its webhook may communicate a Pending state.

They typically include the same core logical structure and commonly contain:

• returnStatus
• paymentStatus
• paymentMethod
• paymentType
• transactionID
• transactionDateTime
• amount
• merchant
• notificationID

In practice, webhook payloads also commonly include returnStatus.statusDescription, which may be especially useful in declined, abandoned, or refused scenarios.

Status query responses

The Status Inquiry response returns the current transaction state when explicit status retrieval is required. It supports verification, reconciliation, and recovery scenarios, and must not be presented as overriding or invalidating a valid final-state webhook.

The official response structure includes returnStatus.statusCode, returnStatus.statusMsg, and returnStatus.statusDescription as part of the status response model.

Field Presence Rules

Core fields

The following fields form the standard transaction meta-information model and are expected in most transaction-oriented responses:

• returnStatus
• paymentStatus
• paymentMethod
• paymentType
• transactionID
• transactionDateTime
• amount
• merchant

Conditional fields

The following fields are conditional and depend on operation type or payment method:

• paymentReference
• token
• merchantInitiatedTransaction
• mbwayMandate
• internalTransactionId
• notificationID

About statusDescription

returnStatus.statusDescription should be treated as part of the standard returnStatus structure wherever SPG provides it. It is especially relevant in:

• status queries
• webhook notifications
• declined or error-related operational responses

Merchant systems must not assume that statusDescription is only relevant for failures. It may also be present in successful cases with the value Success.

Interpretation Principles

Merchant systems must interpret SPG transaction meta information according to the following rules.

1. Distinguish technical result from business outcome

• returnStatus describes the technical response classification returned by SPG
• paymentStatus describes the transaction state from a business and lifecycle perspective

2. Use paymentStatus as the primary transaction-state driver

Business actions must be driven primarily by paymentStatus, not by statusMsg alone.

3. Use statusDescription as a diagnostic and explanatory field

statusDescription provides additional detail that may clarify the exact reason for a declined, abandoned, refused, timeout, or other non-success outcome.

It should be used for:

• logging
• support analysis
• troubleshooting
• merchant-side operator visibility
• optional customer communication mapping, when appropriate

4. Do not assume all extension blocks are present

Merchant systems must validate the presence of optional structures before attempting to use them.

5. Persist identifiers required for reconciliation

At minimum, merchant systems must persist:

• transactionID
• merchant.transactionId
• notificationID, for webhook notifications only

6. Reconcile asynchronous outcomes through status inquiry when needed

Webhook payloads and Status Inquiry responses must be handled as complementary transaction-status mechanisms. Final-state webhooks normally communicate the definitive transaction outcome, while Status Inquiry retrieves the current transaction state when explicit verification, reconciliation, or recovery is required.

Summary

The SPG transaction meta-information structure provides a consistent and extensible model for representing transaction context across synchronous responses, asynchronous webhooks, and status inquiries.

Its core structure is centered on:

• returnStatus
• paymentStatus
• paymentMethod
• paymentType
• transactionID
• transactionDateTime
• amount
• merchant

Within this model, returnStatus.statusDescription is an important standard explanatory field that complements statusCode and statusMsg, especially in declined, abandoned, refused, timeout, and other non-success scenarios, while also being present in successful responses with a generic value such as Success.

Correct implementation of this structure is essential to ensure robust transaction processing, reliable reconciliation, and effective troubleshooting across all SPG payment methods and integration models.