Overview This chapter consolidates the key cross-cutting principles and consistency rules that apply across all sections of Chapter F. Technical Examples and Best Practices and the broader SPG documentation. Its purpose is to ensure that integrators interpret examples, flows, and behaviors consistently across different integration models, payment methods, and operational scenarios, avoiding misinterpretation caused by isolated reading of individual sections of the documentation. Event vs Transaction-State Confirmation Across all examples and flows in this documentation, a strict distinction must be maintained between: Webhook notifications represent asynchronous state transitions or processing events. In some scenarios, they may carry a final paymentStatus; however, transaction-state confirmation and reconciliation must follow the applicable validation rules. When confirmation, reconciliation, recovery, or inconsistency resolution is required, the transaction state should be confirmed using Status Inquiry / Get Status: This principle is consistently applied in: Asynchronous Processing Model All payment methods and flows must be interpreted within a distributed asynchronous processing model, even when operations appear synchronous. This implies: This model is consistently reflected across: Idempotency as a Core Requirement Idempotency is a mandatory requirement across all processing flows. All examples assume: This principle applies to: Separation of Acknowledgement and Processing Webhook acknowledgement must be treated as […]

Overview Webhook processing in SIBS Payment Gateway (SPG) must be designed to operate correctly under failure conditions, repeated delivery attempts, and asynchronous execution constraints. This section defines how integrators must handle: The objective is to ensure that webhook handling remains consistent, reliable, and safe, even when operating under non-ideal conditions. Failure Scenarios in Webhook Processing Webhook delivery and processing may fail at different stages, including: These failures may prevent SPG from confirming successful delivery and can trigger retry mechanisms. Additionally, SPG provides webhook delivery failure and system error notifications through the SIBS Backoffice configuration, typically delivered via email. These notifications are operational alerts and are not part of the webhook delivery mechanism itself. They must be integrated into monitoring and incident management processes to ensure visibility over webhook delivery issues. Configuration of these notifications is described in E.1.7 – Webhook Configuration (SIBS SPG Backoffice). These notifications do not replace retry behavior and must not be used as a trigger for business processing logic or state transitions. Retry Behavior and Delivery Guarantees SPG may retry webhook delivery when: Retry behavior is managed by SPG and is not controlled by the merchant system. Key characteristics of retry behavior: Webhook processing must therefore […]

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: Relevant characteristics: Example (simplified): Processing considerations: 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: Example (simplified): Mandate-related scenarios may include additional fields such as: Processing considerations: 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: Example (simplified): Processing considerations: Structural Differences Across Payment Methods While all webhook notifications share a common base structure, the following aspects vary across methods: Aspect Credit Card MB WAY Multibanco Reference Execution […]

Overview This section provides a complete, end-to-end example of how webhook notifications are integrated into the transaction lifecycle, including reception, processing, and reconciliation with the validated transaction-state outcome. The objective is to demonstrate how asynchronous notifications, API interactions, and internal processing must be combined to produce consistent and correct transaction outcomes in a production-grade SIBS Payment Gateway (SPG) integration. End-to-End Scenario Description The following scenario represents a typical asynchronous payment flow: This model applies across multiple payment methods where the final outcome is not immediately available at the time of the initial request. End-to-End Processing Flow This flow illustrates how webhook processing and status validation must be combined to ensure correct transaction state handling. Step-by-Step Processing Model Step 1 – Transaction Initiation The merchant initiates the transaction through a checkout request and executes the selected payment method. At this stage: Step 2 – Webhook Reception and Processing When the transaction state changes, SPG sends a webhook notification. The merchant system must: The notification must then be processed using the model described in F.10.1 – Webhook Reception, Decryption and Processing Flow. Step 3 – Idempotent Event Handling Before executing any business logic, the system must ensure idempotency: At this stage, the […]

Overview This section defines how webhook notifications must be acknowledged by the merchant system, ensuring correct interaction with the SIBS Payment Gateway (SPG) delivery mechanism. Webhook acknowledgement is not a trivial HTTP response operation but a critical part of the webhook delivery contract, directly impacting retry behavior, delivery guarantees, and overall system stability. A correct acknowledgement implementation ensures that notifications are not unnecessarily retried and that webhook delivery remains reliable under production conditions. Acknowledgement Response Contract After successfully receiving and validating a webhook notification, the merchant system must respond with an HTTP 200 status and a specific JSON payload. Required response: Requirements: Failure to comply with this response format may result in the notification being treated as not acknowledged. Timing and Execution Constraints Acknowledgement must be returned immediately after reception and minimal validation, without waiting for full business processing. The following constraints apply: Webhook handling must therefore follow a model where: This approach ensures that SPG receives confirmation promptly and avoids unnecessary retries. Acknowledgement Flow The acknowledgement is returned independently of the full processing pipeline, ensuring that delivery confirmation is not impacted by downstream operations. Impact on Retry Behavior The acknowledgement response directly influences how SPG handles delivery retries. Retries […]

Overview This section provides a concrete and implementation-oriented example of how webhook notifications must be received, decrypted, validated, and processed within a production-grade SIBS Payment Gateway (SPG) integration. Webhook delivery, encryption model, and required headers are defined in the E.1 – Webhooks (Notifications) section. The objective here is to demonstrate how those specifications are applied in a real processing pipeline, ensuring correctness under asynchronous and non-deterministic conditions. Webhook handling must be implemented as a structured and controlled process, where each step is explicitly defined and validated, rather than as a single-step operation. End-to-End Processing Flow Webhook processing must follow a deterministic and explicitly validated sequence of operations, from reception to acknowledgement. Each step in this flow must be executed in a controlled and failure-aware manner. Partial execution or skipping validation steps may lead to inconsistent transaction state or incorrect processing outcomes. Webhook Reception and Validation Webhook notifications are delivered via an HTTP POST request to the merchant endpoint. At reception time, the following validations must be performed: These validations ensure that only structurally valid and processable requests are accepted into the processing pipeline. Header semantics, transport guarantees, and authenticity requirements are defined in the E.1 – Webhooks (Notifications) section. Payload […]

Overview This chapter provides practical and implementation-oriented examples of webhook handling in SIBS Payment Gateway (SPG) integrations, focusing on how asynchronous notifications are received, processed, and incorporated into the transaction lifecycle. In SPG, transaction processing is not limited to synchronous API interactions. A significant portion of payment flows rely on asynchronous state transitions, where the final outcome of a transaction is delivered after the initial request through external processing, customer interaction, or delayed processing. Webhook notifications represent the primary asynchronous mechanism for communicating transaction-state changes to the merchant system, as defined in the E.1 – Webhooks (Notifications) section. Final transaction-state confirmation and reconciliation should use Status Inquiry / Get Status when confirmation, recovery, or inconsistency resolution is required. See E.2 – Status Inquiry / Get Status. When extended operational diagnostics are required during webhook lifecycle analysis or troubleshooting, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API. Role of Webhooks in the Transaction Lifecycle Webhook handling must be implemented as a core component of the transaction execution model, not as an auxiliary integration feature. A correct implementation requires the ability to: This reflects the operational reality of SPG integrations, where systems must behave correctly under […]

Overview While the official Postman collections are the primary reference execution tool for SIBS Payment Gateway (SPG) integrations, cURL remains useful in a limited set of complementary scenarios. Its role is not to replace the structured execution model provided by the collections, but to support targeted request execution, backend-level validation, and controlled troubleshooting activities where a single API interaction must be observed, reproduced, or technically validated in isolation. This section clarifies where cURL is relevant, where it is not, and how it should be positioned within the broader SPG integration and validation model described throughout F.9 – cURL and Postman Collections. Role of cURL in the SPG Context cURL is appropriate when the goal is to execute or inspect an individual request outside the full orchestration context provided by Postman. Typical complementary use cases include: In these contexts, cURL provides a lightweight and direct mechanism for interacting with the SPG API. Appropriate Complementary Scenarios cURL is particularly relevant in scenarios such as: These are targeted uses of cURL, focused on specific technical objectives, not on full transaction-state lifecycle validation. Limitations of cURL in SPG Flows cURL does not provide the execution features that the official Postman collections provide by design. […]

Overview The SPG Sandbox Collection provides a structured set of predefined scenarios that allow integrators to execute and validate transaction flows against predefined and consistent outcomes. These scenarios are designed to support deterministic testing, where executing a specific scenario produces a consistent and repeatable response pattern, as defined within the collection. The use of these scenarios complements the execution model described in F.9.2 – Execution Model Using Postman Collections and the reproducibility principles outlined in F.8 – Sandbox Reproducible Examples. Structure of Sandbox Scenarios Sandbox scenarios are organized within the SPG Sandbox Collection by: Each scenario contains a deterministic sequence of requests representing a complete transaction lifecycle flow. For example: This structure allows integrators to execute and validate a full transaction lifecycle within a defined scenario. Deterministic Behavior in Sandbox The Sandbox collection defines scenarios that produce consistent and repeatable outcomes when executed. Each scenario: This enables integrators to: The specific inputs required to execute each scenario are defined within the corresponding requests in the collection and must be used as provided. Scenario execution in the Sandbox collection may rely on specific input values defined within the requests, including predefined merchant.merchantTransactionId values associated with controlled Sandbox simulation scenarios, as documented […]

Overview The Postman collections provided for the SIBS Payment Gateway (SPG) rely on runtime variable management and request chaining to enable the correct execution of dependent API operations. This mechanism ensures that data produced during one step of a transaction flow is captured, stored, and reused in subsequent requests, allowing the execution model described in F.9.2 – Execution Model Using Postman Collections to function correctly. Rather than requiring manual input between requests, the collections implement automated data propagation, ensuring consistency, accuracy, and repeatability across transaction flows. Types of Variables Used The collections make use of standard Postman variable scopes, including: These variables allow requests to be parameterized and reused without modifying individual request definitions. Variable Extraction from Responses During execution, the collections use Postman test scripts to extract specific fields from API responses and store them in variables. For example, after executing: The response contains identifiers required for subsequent operations. These are extracted and stored using scripts such as: This ensures that: Variable Injection into Requests Once variables are stored, they are referenced dynamically in subsequent requests, typically in: For example: These references ensure that each request is executed using the correct transaction context generated during the flow. Request Chaining […]