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.

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.

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, Error, or InProcessing.
• 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.

2. paymentStatus

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

Typical values include:

• Success
• Pending
• InProcessing
• 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.

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 is important for conditional interpretation of extension blocks and payment-specific data.

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.

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 asynchronous transaction events and state changes.

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 latest known state of the transaction and must be treated as the authoritative source when resolving uncertain outcomes or reconciling asynchronous events.

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 should 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 should persist:

• transactionID
• merchant.transactionId
• notificationID, when present

6. Reconcile asynchronous outcomes through status inquiry when needed

In asynchronous flows, webhook payloads should be treated as event notifications, while the status inquiry response should be used as the authoritative source for final state confirmation.

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.