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.

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>/api/v2/payments (Checkout creation)
• POST <ROOT_URL>/api/v2/payments/{transactionID}/card/purchase
• POST <ROOT_URL>/api/v2/payments/{transactionID}/mbway-id/purchase
• POST <ROOT_URL>/api/v2/payments/{transactionID}/service-reference/generate
• GET <ROOT_URL>/api/v2/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 validation of integration behavior
• Repeatable testing across environments and teams
• Controlled verification of error and edge cases

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>/api/v2/payments) establishes the transaction context
• The execution request (e.g., /card/purchase, /mbway-id/purchase) applies the scenario
• The Status request (GET <ROOT_URL>/api/v2/payments/{transactionID}/status) confirms the resulting state

(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 mechanism used by Sandbox to produce these 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>/api/v2/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>/api/v2/payments)
• Is the canonical and authoritative identifier of the transaction
• Is required for all subsequent operations, including:
  • Payment execution
  • Status validation (GET <ROOT_URL>/api/v2/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.

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

Scenario Isolation

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

This implies:

• Creating a new transaction via POST /api/v2/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

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>/api/v2/payments
2. POST <ROOT_URL>/api/v2/payments/{transactionID}/[payment-method]/...
3. GET <ROOT_URL>/api/v2/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 consistent but not representative of real-world 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>/api/v2/payments
• Payment execution endpoints (e.g., /card/purchase, /mbway-id/purchase)
• GET <ROOT_URL>/api/v2/payments/{transactionID}/status

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