Overview

The SIBS Payment Gateway (SPG) Sandbox environment enables the execution of deterministic and reproducible transaction scenarios, allowing integrators to validate integration behavior prior to production deployment.

All Sandbox testing must be performed using the official Postman collections, which provide:

• Pre-configured request sequences for all supported payment methods
• End-to-end execution flows aligned with SPG v2
• Scenario-driven simulations (success, declined, error, and edge cases)
• Environment variables and authentication setup

These collections must be used as the execution layer for all Sandbox validation activities, as introduced in F.1 End-to-End Integration Examples.

Download Postman Collections:

• SPG Payment Gateway Collection
• SPG Sandbox Collection

Execution Model Using Postman Collections

Sandbox scenarios must be executed following the request sequences defined in the Postman collections.

A standard execution flow consists of:

1. Checkout Request
   • POST <ROOT_URL>/api/v2/payments
   • Retrieves:
     • transactionID
     • transactionSignature
2. Payment Execution
   • Method-specific endpoint:
     • POST <ROOT_URL>/api/v2/payments/{transactionID}/mbway-id/purchase
     • POST <ROOT_URL>/api/v2/payments/{transactionID}/card/purchase
     • POST <ROOT_URL>/api/v2/payments/{transactionID}/service-reference/generate
3. Status Validation
   • GET <ROOT_URL>/api/v2/payments/{transactionID}/status

The Postman collections automatically:

• Extract the transactionID from the Checkout response
• Store it as a variable
• Reuse it in all subsequent requests

Requests must be executed sequentially within the collection to ensure correct variable propagation and scenario consistency.

This enforces the correct execution pattern and ensures consistency across all test scenarios.

Primary Transaction Identifier

The transaction lifecycle is anchored on the transactionID, which is the canonical and authoritative identifier for all SPG operations.

This identifier:

• Is generated by SPG during Checkout
• Is required for all subsequent operations
• Must be used for correlation across:
  • API calls
  • Webhook notifications
  • Internal system processing

The Postman collections explicitly reflect this model by:

• Capturing transactionID after Checkout
• Using it in all downstream requests (purchase, status, operations)

While merchantTransactionId is included in requests:

• It is used for scenario triggering in Sandbox and for merchant-side reference only
• It is not the authoritative identifier of the transaction lifecycle
• It must not be used to drive transaction state, reconciliation, or lifecycle decisions

Scenario Simulation Using Postman Collections

Sandbox behavior is driven by predefined simulation scenarios embedded in the Postman collections.

These scenarios are triggered through specific values in:

• merchantTransactionId (Checkout request)

Each value corresponds to a deterministic outcome, such as:

• Success
• Declined
• Invalid data
• Missing required information
• Idempotency and duplicate scenarios

The SPG Sandbox Postman Collection includes ready-to-execute scenarios for:

• MB WAY (Success, Declined, Missing Alias)
• Card (Success, Declined, Invalid Data)
• Multibanco (Paid, Unpaid)
• Idempotency and duplicate validation

This allows controlled and repeatable validation of integration behavior.

Full Lifecycle Validation Requirement

Each Sandbox scenario must validate the complete transaction lifecycle.

This includes:

• Checkout creation
• Payment execution
• Handling of intermediate states (e.g., Pending)
• Webhook processing (when applicable)
• Final validation via Status API

The Status endpoint is the authoritative and final source of truth for the transaction outcome and must always be used to confirm it.

The Postman collections include ready-to-use getStatus requests for this purpose.

Observability and Execution Traceability

The Postman collections provide built-in mechanisms to support reproducibility:

• Automatic variable propagation (transactionID, transactionSignature)
• Structured request grouping by scenario
• Environment configuration for Sandbox execution

For each execution, integrators must capture:

• Request payloads
• Response payloads
• Status responses
• Transaction identifiers

This ensures consistent validation and reproducibility across all test scenarios.

Validation of Asynchronous Behavior

Sandbox scenarios must explicitly validate asynchronous transaction behavior, particularly for:

• MB WAY
• Multibanco Reference

This includes:

• Handling Pending states
• Receiving and processing webhook notifications (if configured)
• Confirming final state via Status API

Even in Sandbox:

• A Pending status is not final
• API responses alone are insufficient to determine outcome

The Postman collections explicitly guide this behavior through status polling patterns .

Operational and Edge Case Scenarios

The Postman collections include dedicated scenarios for validating:

• Capture
• Refund
• Cancellation
• Idempotency
• Duplicate transactions

These scenarios allow validation of:

• Post-payment lifecycle operations
• Retry safety
• Duplicate protection mechanisms

All operations are executed using:

• transactionID as the primary and authoritative reference
• Controlled inputs for deterministic outcomes

Limitations of Sandbox

Sandbox is a controlled simulation environment and does not replicate production behavior.

Key limitations include:

• No real issuer or acquirer interaction
• No real customer-driven authorization
• No fraud or risk evaluation
• Simplified timing and execution behavior

Scenario outcomes are predefined and deterministic, and external dependencies are not represented.

Correct Usage Principles

Sandbox must be used to validate:

• Correct implementation of SPG flows
• Proper handling of transaction states
• Consistent use of transactionID
• Handling of asynchronous behavior
• Idempotency and duplicate protection

It must not be used to:

• Infer production timing or performance
• Assume real-world approval behavior
• Replace production readiness validation

Final Consideration

The Postman collections are the canonical tool for executing Sandbox reproducible examples, enabling deterministic validation of all supported flows.

A correct integration must demonstrate:

• Consistent use of transactionID
• Proper lifecycle handling
• Reliable state validation via Status API
• Robust handling of asynchronous flows

Sandbox validates implementation correctness under controlled conditions, while production correctness depends on consistent and resilient behavior under real-world execution.