Overview

SIBS SPG webhooks are asynchronous notifications sent by SIBS to a merchant-defined endpoint to communicate transaction-related events.

Each webhook contains a JSON payload representing the state of a transaction at a given point in time.

All webhook payloads follow a consistent structural model defined by SIBS, composed of:

• a stable core structure, consistently present across transaction-related notifications
• optional additional fields and objects, depending on the event context

This page defines the generic webhook payload structure, corresponding to the stable core.

Method-specific payload extensions are defined in E.1.2 Webhook Payload Variants by Payment Method

Generic Payload Model

{
  "returnStatus": {
    "statusMsg": "string",
    "statusCode": "string"
  },
  "paymentStatus": "string",
  "paymentMethod": "string",
  "transactionID": "string",
  "transactionDateTime": "datetime",
  "amount": {
    "currency": "string",
    "value": "number"
  },
  "merchant": {
    "transactionId": "string",
    "terminalId": "number"
  },
  "paymentType": "string",
  "notificationID": "string"
}

This structure defines the baseline integration contract for webhook processing.

The webhook payload is composed of:

• a stable core structure, defined above
• optional fields and objects, which may be included depending on the event context

Additional fields do not alter this structure and should be treated as contextual extensions.

Generic Payload Example

{
  "returnStatus": {
    "statusMsg": "Success",
    "statusCode": "000"
  },
  "paymentStatus": "Success",
  "paymentMethod": "MBWAY",
  "transactionID": "s2bfw1g1P1siCSUjVPP8",
  "transactionDateTime": "2026-03-12T10:48:44Z",
  "amount": {
    "currency": "EUR",
    "value": 15.9
  },
  "merchant": {
    "transactionId": "aafd48f8d6814e86855ed5489d04880f",
    "terminalId": 1562569,
    "merchantName": "MERCHANT DOT COM",
    "inApp": "false"
  },
  "paymentType": "PURS",
  "token": {
    "tokenType": "MobilePhone",
    "value": "351#912345678"
  },
  "internalTransactionId": "S13039300290071S",
  "notificationID": "b6571d90-35d6-41a6-b7b1-732464b1e58c"
}

Core Structure Definition

returnStatus

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

Represents the technical result of the processing.

The meaning of these fields is defined in [C 1.1 – Meta Information, Codes and Transaction States].

paymentStatus

"paymentStatus": "Success"

Represents the business state of the transaction.

This is the primary field for business decision-making.

The possible values and state transitions are defined in [C 1.1 – Meta Information, Codes and Transaction States].

paymentMethod

"paymentMethod": "REFERENCE"

Identifies the payment method associated with the notification.

This field is typically present in transaction-related notifications.
Its presence depends on the type of event being reported.

Detailed structures and method-specific extensions are defined in E.1.2 Webhook Payload Variants by Payment Method.

transactionID

"transactionID": "s2bfw1g1P1siCSUjVPP8"

Unique identifier of the transaction generated by SIBS.

This is the primary transaction correlation field across:

• webhook notifications
• transaction status queries
• payment operations

transactionDateTime

"transactionDateTime": "2026-03-12T10:25:00.001Z"

Timestamp associated with the transaction event.

amount

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

Represents the transaction amount.

merchant

"merchant": {
  "transactionId": "aafd48f8d6814e86855ed5489d04880f",
  "terminalId": 1562569,
  "merchantName": "MERCHANT DOT COM"
}

Contains merchant-side transaction correlation data.

Additional merchant fields may be present depending on the context.

paymentType

"paymentType": "PURS"

Identifies the type of operation associated with the transaction.
Examples depend on the payment flow and are defined in the corresponding payment method sections.

Detailed structures and method-specific extensions are defined in E.1.2 Webhook Payload Variants by Payment Method.

notificationID

"notificationID": "b6571d90-35d6-41a6-b7b1-732464b1e58c"

Unique identifier of the webhook event.

This identifier is independent from the transaction and is used to:

• distinguish individual webhook notifications
• support idempotent processing
• identify retries of the same event

It should not be used as a transaction identifier.

Identifier Roles

The webhook payload contains multiple identifiers with different purposes:

• transactionID: identifies the transaction across all systems and operations
• merchant.transactionId: identifies the transaction within the merchant system
• notificationID: identifies the specific webhook event

These identifiers serve distinct roles and should not be used interchangeably.

Field Optionality

While the generic structure defines the common payload model, some fields may not be present in all webhook notifications.

In particular:

• paymentMethod may depend on the type of event being reported
• internalTransactionId may be present depending on the transaction context
• the merchant object may not include all subfields in every event

Implementations should not assume strict field presence beyond the generic structure.

Structural Characteristics

Stable Core

The generic webhook structure is centered on:

• event identification (notificationID)
• technical result (returnStatus)
• business state (paymentStatus)
• transaction identification (transactionID, transactionDateTime)
• payment classification (paymentMethod, paymentType)
• financial data (amount)
• merchant correlation (merchant)

Extensibility

Webhook payloads are extensible by design and may include additional fields or objects depending on the event context.

This extensibility allows SIBS to:

• introduce new payment methods and features
• enrich existing webhook payloads with additional data
• evolve the platform without breaking existing integrations

These extensions do not alter the generic structure and are documented in E.1.2 Webhook Payload Variants by Payment Method

From an integration perspective, this means that:

• new fields may appear in webhook payloads over time
• additional objects may be included for specific transaction types
• existing fields will retain their meaning and structure

Implementations should therefore be designed to process the generic structure independently from any additional fields.

Forward Compatibility

Webhook payloads may evolve over time as new capabilities are introduced.

To ensure long-term stability of integrations, webhook processing should be implemented in a forward-compatible manner.

In practice, this means:

• unknown fields should be ignored without causing processing failures
• optional fields should not be assumed to be always present
• parsing logic should focus on the generic core structure rather than a fixed schema

Failure to follow these principles may result in:

• breaking integrations when new fields are introduced
• incorrect processing when optional data is missing
• increased maintenance effort due to rigid payload assumptions

By designing for forward compatibility, integrations remain stable across platform updates without requiring frequent changes.

Common Integration Pitfalls

The following are common integration pitfalls when implementing webhook processing.

Understanding and addressing these topics is critical for ensuring a robust and reliable integration.

1. Assuming a Fixed Payload Structure

Webhook payloads are extensible and may include additional fields over time.

Implementations that rely on strict schema validation or fixed object structures may fail when new fields are introduced.

Recommendation

• Parse only the required fields from the generic structure
• Ignore unknown or additional fields

2. Assuming All Fields Are Always Present

Not all fields are guaranteed to be present in every webhook notification.

For example:

• paymentMethod may depend on the event type
• internalTransactionId may not be included
• some subfields within objects may be omitted

Recommendation

• Treat the payload as partially optional
• Validate only the fields required for your business logic

3. Using Webhook Data as Final Transaction State

Webhook notifications represent events, not necessarily the final state of a transaction.

Relying solely on webhook data may lead to incorrect conclusions, especially in asynchronous flows.

Recommendation

• Use webhooks as triggers
• Confirm the final state using the transaction status service

4. Not Handling Duplicate Notifications

Webhook notifications may be delivered more than once due to retries.

Processing the same event multiple times can result in:

• duplicated business operations
• inconsistent system state

Recommendation

• Implement idempotent processing
• Use notificationID and transactionID for deduplication

5. Assuming Event Ordering

Webhook notifications are not guaranteed to be delivered in order.

For example:

• a Success event may be received before a Pending event
• retries may arrive after later events

Recommendation

• Do not rely on chronological ordering
• Always evaluate the current transaction state

6. Ignoring Identifier Semantics

Confusing identifiers may lead to incorrect correlation.

• transactionID identifies the transaction
• notificationID identifies the event
• merchant.transactionId identifies the merchant-side reference

Recommendation

• Use each identifier according to its purpose
• Do not interchange them

Processing Considerations

Event-Based Model

A transaction may generate multiple webhook notifications over time.

Notifications represent transaction events and state changes, and ordering is not guaranteed.

Idempotency

Webhook processing should ensure that duplicate notifications do not produce duplicate effects.

Recommended identifiers:

• notificationID
• transactionID

Webhook and Transaction Status

Webhook notifications communicate transaction events.

The transaction status service provides the authoritative and current state of the transaction and should be used when deterministic state confirmation is required.

Summary

The SIBS SPG webhook payload follows a consistent, extensible structure defined by:

• transaction identification
• transaction state
• payment classification
• financial data
• merchant correlation
• event identification

This generic structure provides a stable integration contract for webhook processing, while allowing contextual extensions for specific payment methods and operations.

Method-specific payload structures are defined in E.1.2 Webhook Payload Variants by Payment Method