Overview

Webhook notifications in SIBS Payment Gateway (SPG) follow a consistent structural model, but their content and behavioral implications vary depending on the payment method and transaction type.

This section provides focused examples highlighting method-specific differences in webhook payloads and processing considerations, enabling integrators to correctly interpret and handle notifications across different payment scenarios.

The objective is not to restate full payload definitions, but to emphasize the relevant structural variations and their impact on processing logic.

Credit Card Webhook Example (One-Off and Two-Step)

In Credit Card transactions, webhook notifications typically reflect the outcome of operations such as:

• AUTH (authorization)
• CAPTURE (funds capture)
• PURS (purchase)

Relevant characteristics:

• paymentMethod is CARD
• paymentStatus reflects the result of the specific operation
• Additional data may include tokenization or 3DS-related context (if applicable)

Example (simplified):

{
    "paymentMethod": "CARD",
    "paymentType": "AUTH",
    "paymentStatus": "Success",
    "transactionID": "tx123",
    "notificationID": "notif001"
}

Processing considerations:

• Distinguish between AUTH and CAPTURE events
• Do not assume funds are captured after a successful AUTH
• For two-step flows, wait for CAPTURE confirmation before finalizing business actions
• Always confirm final state via Status API

MB WAY Webhook Example (One-Off and Mandate-Based)

MB WAY webhook notifications may represent both payment execution events and mandate lifecycle events, depending on the transaction type.

Relevant characteristics:

• paymentMethod is MBWAY
• Webhooks may include mandate-related data when applicable
• In mandate-based scenarios, webhook notifications may present paymentMethod as MANDATE, indicating that the event relates to a mandate lifecycle rather than a direct payment execution
• Processing is inherently asynchronous

Example (simplified):

{
    "paymentMethod": "MBWAY",
    "paymentStatus": "Success",
    "transactionID": "tx456",
    "notificationID": "notif002"
}

Mandate-related scenarios may include additional fields such as:

• mandateIdentification
• mandateAction (e.g., creation, cancellation)
• mandateActionStatus

Processing considerations:

• Treat mandate lifecycle events separately from payment events
• Do not assume immediate completion – user interaction is often required
• Handle asynchronous confirmation delays
• Validate final outcome through Status API before applying business logic

Multibanco Reference Webhook Example

Multibanco Reference payments involve delayed customer action, where the payment is completed outside the system using a generated reference.

Relevant characteristics:

• paymentMethod is REFERENCE
• Webhook represents notification of payment state transition, which must be confirmed via Status API before being treated as final
• A reference block may be present in the payload

Example (simplified):

{
    "paymentMethod": "REFERENCE",
    "paymentStatus": "Success",
    "transactionID": "tx789",
    "notificationID": "notif003"
}

Processing considerations:

• Expect delays between reference generation and payment completion
• Do not treat reference generation as payment success
• Only process business logic after confirmation webhook and status validation
• Handle expiration scenarios where payment may never occur

Structural Differences Across Payment Methods

While all webhook notifications share a common base structure, the following aspects vary across methods:

These differences directly impact how webhook notifications must be interpreted and processed.

Processing Implications

Regardless of payment method, the following principles must always be applied:

• Do not rely solely on the webhook payload for final decision-making
• Always confirm transaction state through the Status API
• Handle asynchronous behavior explicitly
• Ensure idempotent processing across all methods
• Avoid assumptions based on a single notification

Method-specific differences must influence processing logic, but not override the core consistency model.

Final Consideration

Webhook notifications vary in structure and behavior depending on the payment method, but they must always be processed within the same consistent and resilient integration model.

A correct implementation requires:

• understanding method-specific nuances
• applying appropriate processing logic
• maintaining consistent validation and reconciliation practices

By combining method-specific awareness with a unified processing model, integrators ensure that webhook handling remains accurate, reliable, and consistent across all supported payment methods.