Overview

The Sandbox environment enables deterministic scenario modeling, allowing integrators to execute predefined transaction scenarios with consistent and repeatable outcomes.

These scenarios are defined and executed through the official Postman collections, which provide structured requests representing specific transaction behaviors.

These scenarios must be executed following the flow structure defined in F.8.2 – Structure of a Reproducible Sandbox Flow and validated according to F.8.3 – Reproducibility Requirements.

Scenario Definition Through Postman Collections

Sandbox scenarios are explicitly defined in the Postman collections.

Each scenario is represented by a combination of:

• A predefined request configuration
• A specific execution flow
• An expected outcome (e.g., success, declined, error, pending)

Within the collections, scenarios are organized by:

• Payment method (Card, MB WAY, Multibanco)
• Transaction type (payment, capture, refund, etc.)
• Scenario type (success, error, edge case)

For example, scenarios are executed through predefined requests such as:

• POST <ROOT_URL>/payments (Checkout creation)
• POST <ROOT_URL>/payments/{transactionID}/card/purchase
• POST <ROOT_URL>/payments/{transactionID}/mbway-id/purchase
• POST <ROOT_URL>/payments/{transactionID}/service-reference/generate
• GET <ROOT_URL>/payments/{transactionID}/status

These requests are already configured within the Postman collections and must be executed as defined within the collection.

Deterministic Outcomes

Each scenario in the Postman collection produces a predictable and repeatable outcome, including:

• paymentStatus (e.g., Success, Declined, Pending)
• returnStatus.statusCode
• Method-specific response structures

Executing the same scenario:

• With the same request configuration
• In the same sequence

will consistently produce the same observable results.

This determinism allows:

• Reliable and repeatable validation of integration behavior
• Repeatable testing across environments and teams
• Controlled verification of error and edge cases

The reproducibility of these outcomes depends on compliance with the requirements defined in F.8.3 – Reproducibility Requirements.

Scenario Inputs and Request Configuration

Each predefined scenario relies on a specific request configuration, embedded in the Postman collection.

This configuration may include, among others:

• Scenario-specific payload values
• Predefined identifiers
• Field combinations required to produce the expected outcome

For example:

• The Checkout request (POST <ROOT_URL>/payments) establishes the transaction context
• The execution request (e.g., /card/purchase, /mbway-id/purchase) applies the scenario
• The Status request (GET <ROOT_URL>/payments/{transactionID}/status) confirms the resulting state

Status Inquiry / Get Status provides transaction-state confirmation for deterministic Sandbox scenario verification.

(See collection root variables in SIBS PAYMENT GATEWAY POSTMAN Collection)

Integrators should:

• Execute the predefined requests without modification when validating standard scenarios
• Only modify inputs intentionally when testing variations

The internal mechanism used by Sandbox to produce deterministic outcomes is abstracted and not part of the integration contract.

Scope of Scenario Coverage

The Sandbox Postman collections provide deterministic scenarios across multiple areas:

Payment Methods

• MB WAY (execution via /mbway-id/purchase)
• Card (execution via /card/purchase)
• Multibanco Reference (execution via /service-reference/generate)

Transaction Outcomes

• Successful execution
• Declined transactions
• Invalid or inconsistent requests
• Pending or asynchronous states

Operational Flows

• Capture (e.g., POST <ROOT_URL>/payments/{transactionID}/capture)
• Refund
• Cancellation

Edge Cases

• Duplicate transactions
• Idempotency validation
• Reuse of request data across executions

These scenarios are directly executable through the structured folders provided in the Postman collections.

Role of transactionID in Scenario Execution

Regardless of the scenario executed, the transaction lifecycle remains anchored on:

• transactionID

The transactionID:

• Is generated during Checkout (POST <ROOT_URL>/payments)
• Is the primary SPG identifier of the transaction
• Is required for all subsequent operations, including:
  • Payment execution
  • Status validation (GET <ROOT_URL>/payments/{transactionID}/status)
  • Operational flows (capture, refund, cancellation)

All scenario validation must be performed using transactionID as the reference across API calls and webhook processing.

Webhook validation should confirm correct asynchronous notification propagation, transaction correlation, and consistency with Status Inquiry / Get Status results when confirmation is required.

Repeatability and Consistency

A defining characteristic of Sandbox scenario modeling is repeatability.

Each scenario:

• Can be executed repeatedly
• Produces consistent outcomes
• Follows the same observable transaction behavior

This depends on:

• Executing the same Postman requests
• Preserving the defined execution order
• Using consistent request configurations

This enables:

• Regression testing
• Cross-team validation
• Deterministic debugging

See E.1 – Webhooks (Notifications) and E.2 – Status Inquiry / Get Status for detailed guidance regarding asynchronous notification handling, transaction-state confirmation, and reconciliation.

When extended operational diagnostics are required during Sandbox scenario analysis, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.

Scenario Isolation

To maintain deterministic behavior, scenarios must be executed in isolation.

This implies:

• Creating a new transaction via POST <ROOT_URL>/payments for each execution
• Avoiding reuse of previous transaction contexts
• Executing flows sequentially as defined in the Postman collection

Isolation ensures:

• Predictable outcomes
• Clear transaction boundaries
• Accurate validation of each scenario

Scenario isolation prevents cross-scenario lifecycle interference and guarantees deterministic validation of transaction-state evolution.

Practical Execution Using Postman Collections

The Postman collections provide ready-to-use scenario folders where:

• Each folder represents a specific deterministic scenario
• Requests are preconfigured with the correct endpoints and payloads
• Execution order is defined (Checkout → Execution → Status)

Typical execution sequence:

1. POST <ROOT_URL>/payments
2. POST <ROOT_URL>/payments/{transactionID}/[payment-method]/...
3. GET <ROOT_URL>/payments/{transactionID}/status

All steps should be executed within the same collection context to ensure correct variable propagation.

Limitations of Scenario Modeling

Deterministic scenarios in Sandbox provide controlled validation but do not represent real-world processing.

Their limitations include:

• Predefined and fixed outcomes
• No real user or issuer interaction
• Simplified execution conditions

As a result:

• Scenario results are intentionally consistent but not representative of real-world operational variability
• Certain production behaviors may not be fully simulated

Scenario modeling must therefore be used to validate integration correctness, not to infer production behavior.

Final Consideration

Deterministic scenario modeling in Sandbox enables controlled validation of:

• Transaction outcome handling
• Error and edge case processing
• Lifecycle consistency across flows

By executing predefined scenarios through the Postman collections and validating outcomes using:

• POST <ROOT_URL>/payments
• Payment execution endpoints (e.g., /card/purchase, /mbway-id/purchase)
• GET <ROOT_URL>/payments/{transactionID}/status

integrators can verify system behavior under controlled and repeatable conditions, while consistently using transactionID as the primary SPG identifier throughout the transaction lifecycle.

These deterministic scenarios are intended for validation within the Sandbox environment and must be interpreted in the context of the differences between Sandbox and Production described in F.8.4 – Sandbox vs Production Behavioral Gap.