The official SIBS Postman collections are structured to reflect the organization of SPG API operations, providing a clear and consistent way to navigate and understand requests.
These collections group requests according to payment methods, operation types, and predefined scenarios, ensuring a structured representation of the available API capabilities.
Collection Organization
The SPG Payment Gateway Collection is organized into logical groups primarily based on payment methods and operation types, including:
MB WAY
Multibanco Reference
Card
Backoffice Operations
Within each group, requests represent individual API operations.
These operations are structurally related through the SPG transaction lifecycle, where outputs generated by one operation may become required inputs for subsequent requests.
This organization provides a clear executable structural representation of the SIBS SPG API and its operational lifecycle flows.
In addition to method-specific groupings, certain operations such as status inquiry appear across multiple groups, reflecting their use across different payment methods.
This reflects the role of Status Inquiry as a cross-cutting transaction-state validation and reconciliation mechanism across multiple payment methods.
Each request in the collection corresponds to a specific SPG API operation and includes the necessary method, endpoint, headers, and payload required for execution.
This ensures that each request directly maps to a specific API capability exposed by SPG.
Many requests also participate in chained execution flows through transaction identifiers such as transactionID, which maintain continuity across the integration lifecycle.
Each scenario contains a set of requests representing API operations organized according to the available interactions within that scenario.
These interactions may include both synchronous execution steps and asynchronous webhook notification propagation depending on the payment method and operational scenario.
The collection also includes additional grouped scenarios covering specific operational cases and API behaviors.
The Postman collections provide a structured executable representation of the SIBS SPG API, grouping requests by payment method, operation type, and predefined scenarios.
A correct understanding of this structure enables integrators to:
Navigate executable transaction flows effectively
Identify the appropriate requests for each operation
Understand how API interactions are organized and related within the collections
By following the structure provided in the collections, integrators ensure that API interactions are consistent with the defined SPG interfaces and available scenarios, enabling reliable and structured validation of integration behavior.
This chapter defines the role of Postman collections and cURL requests in the context of SIBS Payment Gateway (SPG) integrations, focusing on how API interactions are executed and validated in practice.
In SPG, integration correctness is not achieved solely through understanding API specifications or payload structures, but through the ability to execute transaction flows consistently and accurately across their full lifecycle. As demonstrated in F.1 – End-to-End Integration Examples, each payment interaction involves a sequence of dependent operations, including checkout creation, payment execution, asynchronous processing, and final state validation.
The Postman collections provided with this documentation represent the reference executable orchestration layer for these flows.
Download and use the following official Postman collections:
For quick functional validation and payment-method-specific testing scenarios, the Sandbox Payment Simulator may also be used as a complementary tool alongside the Postman collections.
These collections must be used as the baseline execution and validation mechanism for all integration testing activities.
They encapsulate:
Pre-configured requests aligned with SPG APIs
Correct lifecycle sequencing of operations
Automatic propagation of transaction context (e.g., transactionID)
Support for both synchronous and asynchronous scenarios
This includes validation of asynchronous webhook notification propagation and consistency with Status Inquiry / Get Status results when confirmation is required.
As further reinforced in F.8 – Sandbox Reproducible Examples, all testing – particularly in Sandbox – must be performed using these collections, which enable deterministic and reproducible validation of integration behavior.
Execution Model Using Postman Collections
The Postman collections must be used as the baseline execution model for all SPG integrations.
They enforce a structured execution pattern consistent with the SPG lifecycle:
Checkout request
Payment execution (method-specific)
Status validation
This sequence reflects the actual dependency model of SPG, where:
Each step depends on the output of the previous one
The transactionID is generated during checkout and required for all subsequent operations
Transaction state evolves across multiple steps and must be validated accordingly
This dependency model guarantees consistent transaction-state progression across the full integration lifecycle.
The collections provide built-in mechanisms that ensure correct execution:
Support for handling transaction identifiers across requests
Support for propagating transaction context across requests
Pre-configured request structures aligned with the API
Transaction-state confirmation and reconciliation should use Status Inquiry / Get Status when required.
Role of cURL
cURL may be used in SPG integrations as a complementary tool, particularly for:
Backend-level testing
Automation scenarios (e.g., CI/CD pipelines)
Debugging specific API interactions
However, cURL does not provide:
Execution sequencing
Variable management
End-to-end flow orchestration
As a result, it does not reflect the full integration lifecycle when used in isolation.
For this reason:
cURL should not be used as the primary mechanism for integration validation
Postman collections must remain the reference execution tool
cURL usage should be limited to controlled scenarios where individual request validation is required.
When extended operational diagnostics are required during execution analysis or troubleshooting, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Final Consideration
Postman collections are not auxiliary tooling – they are a core component of the SPG integration model.
They provide a validated and executable representation of how the platform operates, ensuring that integrations are tested under conditions that reflect real execution behavior.
A correct integration requires not only successful API calls and valid request payloads, but also the ability to:
Execute transaction flows end-to-end
Respect the dependency between operations
Correctly handle asynchronous processing and delayed outcomes
Validate final transaction state using validated final paymentStatus data, or Status Inquiry / Get Status when confirmation, recovery, or reconciliation is required
By using the Postman collections as the execution baseline, integrators ensure:
Consistency across testing and implementation
Alignment with SPG operational expectations
Reduced risk of integration errors in production environments
This approach establishes a reliable foundation for both development and production readiness.
The Sandbox environment plays a critical role in the integration lifecycle by providing a controlled and deterministic context for developing, validating, and refining payment integrations.
It enables integrators to:
Implement and test transaction flows
Validate system behavior under predefined scenarios
Verify handling of success, error, and edge conditions
The Sandbox must be understood as a validation and development tool, not as a representation of Production behavior, as detailed in F.8.4 – Sandbox vs Production Behavioral Gap.
Position in the Integration Lifecycle
The Sandbox environment is used during the early and intermediate phases of the integration lifecycle.
Its primary role is to support:
Initial implementation of API interactions
Validation of transaction flows and state transitions
Verification of integration logic and error handling
These elements together define the foundation for deterministic integration correctness and reproducible validation.
Scope of Validation in Sandbox
Sandbox validation is focused on verifying:
Correct construction of requests
Proper handling of responses
Accurate implementation of transaction lifecycle logic
Handling of predefined success, error, and edge scenarios
This includes:
Execution of complete transaction flows
Validation of paymentStatus, returnStatus, and confirmed transaction-state outcomes
Verification of state transitions and final outcomes
Sandbox validation confirms that the integration behaves correctly under controlled and reproducible conditions.
Status Inquiry / Get Status provides transaction-state confirmation and reconciliation support throughout the integration lifecycle when required.
Validation should also include correct handling of asynchronous webhook notification propagation and consistency with Status Inquiry / Get Status results.
Limitations of Sandbox Validation
While Sandbox is essential for integration development, its scope is inherently limited.
Sandbox does not validate:
Real-world issuer behavior
Customer-driven interactions under production conditions
Sandbox supports an iterative development and validation cycle.
Typical usage includes:
Implementing a flow
Executing deterministic scenarios
Validating outcomes
Refining logic based on observed behavior
This iterative process enables:
Progressive validation of integration components
Early detection of implementation issues
Controlled testing of different transaction scenarios
Reproducibility, as defined in F.8.3 – Reproducibility Requirements, is essential to ensure that each iteration produces consistent and verifiable results.
Reproducibility guarantees that integration behavior can be validated consistently across multiple execution cycles and supports reliable debugging, refinement, and lifecycle verification.
When extended operational diagnostics are required during lifecycle analysis or troubleshooting, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Validation vs Production Readiness
Sandbox validation ensures:
Correct implementation of integration logic
Proper handling of predefined scenarios
Compliance with API contract and flow structure
Production readiness, however, requires:
Handling of real-world variability
Resilience to external system behavior
Robust monitoring and operational capabilities
This distinction is critical:
Sandbox validates correctness
Production requires resilience and adaptability
Final Consideration
The Sandbox environment is an essential component of the integration lifecycle, providing the foundation for building and validating payment integrations.
Its role is to ensure that:
Transaction flows are correctly implemented
Integration logic behaves as expected under controlled scenarios
A successful integration depends on correctly leveraging Sandbox for validation while designing for the variability and complexity of Production environments.
The Sandbox environment provides a controlled and deterministic execution model designed to support integration development and validation.
Production environments, however, operate under real-world conditions, where transaction outcomes depend on external systems, user behavior, and asynchronous flows.
This creates an inherent behavioral gap between Sandbox and Production that must be clearly understood and accounted for during integration design and validation.
Transaction outcomes are deterministic and reproducible
The same inputs produce the same outputs
Scenarios are predefined and controlled
In Production:
Transaction outcomes are non-deterministic
Results depend on:
Issuer decisions
Customer actions
External processing systems
This implies that:
A successful Sandbox scenario does not guarantee a successful Production outcome
Integration logic must be designed to handle variability, not fixed results
Synchronous vs Asynchronous Behavior
Sandbox execution often appears immediate and operationally synchronous.
In Production:
Many payment methods are asynchronous by nature
Final transaction states may be delayed
Intermediate states (e.g., Pending) are common
Examples:
MB WAY requires customer confirmation
Multibanco payments may be completed hours or days later
This requires:
Proper handling of intermediate states
Use of webhooks for asynchronous state propagation and Status Inquiry / Get Status for confirmation when required
Avoidance of assumptions about immediate finality
External Dependency Influence
Sandbox execution does not involve real external systems.
In Production, transaction outcomes depend on:
Card issuer authorization systems
Fraud and risk engines
Customer authentication flows (e.g., 3DS)
Payment method-specific infrastructures
As a result:
Transaction outcomes and responses may vary even with identical inputs
Additional steps (e.g., authentication) may be required
Failures may occur due to external conditions
Integration logic must be resilient to these dependencies.
Timing and Latency Differences
Sandbox responses are typically:
Fast
Consistent
Not subject to network or system variability
Production environments introduce:
Network latency
Processing delays
External system response times
This impacts:
User experience
Timeout handling
Retry strategies
Integrations must be designed to tolerate variable timing conditions.
Error Behavior Differences
In Sandbox:
Errors are controlled and predictable
Specific scenarios simulate known failure conditions
In Production:
Errors may be:
Intermittent
Context-dependent
External-system driven
Examples:
Temporary issuer unavailability
Network failures
Unexpected validation conditions
This requires:
Robust error handling
Retry mechanisms where appropriate
Clear distinction between recoverable and non-recoverable errors
Data and Validation Differences
Sandbox environments often use:
Simplified validation rules
Test data
Controlled input constraints
Production environments enforce:
Full validation rules
Real data constraints
Compliance requirements
As a result:
Requests accepted in Sandbox may be rejected in Production
Additional required fields may be enforced
Data formats and constraints must be strictly respected
Idempotency and Duplicate Handling
In Sandbox:
Duplicate handling scenarios are controlled and predictable
In Production:
Duplicate requests may occur due to:
Network retries
Client-side resubmissions
Timeout handling
This requires:
Proper idempotency design
Safe retry logic
Protection against unintended duplicate operations
Observability and Operational Complexity
Sandbox environments provide:
Simplified observability
Controlled execution flows
Production environments require:
Continuous transaction monitoring
Logging and traceability across systems
Correlation of API calls, webhooks, and internal processing
This implies:
Observability must be designed as part of the integration
Debugging requires full lifecycle visibility
Monitoring and alerting become critical
Lifecycle visibility guarantees that transaction-state evolution can be correlated consistently across API calls, webhook propagation, and internal processing systems.
When extended operational diagnostics are required during Production troubleshooting or lifecycle analysis, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Implications for Integration Design
Due to the behavioral gap between Sandbox and Production, integrations must:
Avoid assumptions based on deterministic Sandbox behavior
Be designed for asynchronous and variable outcomes
Validate final transaction state using validated final paymentStatus data, or Status Inquiry / Get Status when confirmation, recovery, or reconciliation is required
Implement robust error handling and retry strategies
Ensure full lifecycle traceability
Sandbox validation confirms correct implementation, but not real-world behavior under all conditions.
Status Inquiry / Get Status provides transaction-state confirmation and reconciliation support for Production lifecycle verification when required.
The Sandbox environment is a validation tool, not a representation of Production behavior.
A correct integration must:
Use Sandbox to validate structure, logic, and handling
Anticipate real-world variability in Production
Be resilient to asynchronous processing, external dependencies, and unpredictable outcomes
Understanding and accounting for this behavioral gap is essential to ensure that an integration that works in Sandbox also behaves correctly in Production.
Reproducibility in Sandbox testing requires that each transaction flow can be executed multiple times with consistent inputs, controlled execution, and predictable outcomes.
A flow is only considered reproducible if it produces the same observable results when executed under the same conditions.
These requirements apply to flows executed through the official Postman collections, which provide the standard mechanism for Sandbox scenario execution (see Postman collections available in Chapter F.1 – End-to-End Integration Examples).
This chapter defines the mandatory requirements that must be satisfied to ensure that Sandbox executions are reliable, verifiable, and suitable for integration validation.
All reproducible flows must be based on deterministic inputs.
This means:
The same request payload structure must be used across executions
Scenario-specific values must remain consistent
Required fields must be explicitly defined and not inferred
In Sandbox scenario execution, these inputs may include specific values defined in the merchant.merchantTransactionId field of the Checkout request, as documented in the Postman collections. These values are part of the predefined request configuration and must be used as provided to ensure reproducible outcomes.
Any variation in input configuration may result in:
Different transaction behavior
Inconsistent outcomes
Invalid validation results
Deterministic input definition is a foundational prerequisite for reproducible Sandbox validation.
Controlled Execution Sequence
Reproducibility requires that the execution sequence is strictly controlled and consistently applied.
Each flow must:
Follow the defined structure (Initialization → Execution → Validation)
Execute all required steps in the correct order
Avoid skipping or reordering phases
Execution must always be treated as a complete lifecycle, not as isolated API calls.
Any deviation from the defined sequence invalidates reproducibility.
Each execution must operate on a fully isolated transaction context.
This implies:
A new transaction must be created for each test execution
No reuse of previous transactionID values
No dependency on the lifecycle state of prior executions
Isolation ensures that:
Results are not influenced by previous tests
State transitions remain predictable
Validation remains accurate
Consistent Use of transactionID
All phases of the flow must consistently use the same:
transactionID
This identifier:
Is generated during the Initialization phase
Must be propagated to all subsequent steps
Must be used for all validation operations
Failure to maintain consistent usage of transactionID leads to:
Loss of traceability
Invalid state validation
Incorrect test conclusions
Stable Expected Outcomes
Each reproducible scenario must have a clearly defined and stable expected outcome.
This includes:
Expected paymentStatus
Expected returnStatus.statusCode
Expected transaction lifecycle behavior
Expected outcomes must:
Be known before execution
Remain consistent across repeated runs
Be used as the baseline for validation
If expected outcomes vary, the scenario is not reproducible.
Explicit Validation Criteria
Reproducibility requires explicit and verifiable validation criteria.
Each flow must define:
What constitutes a successful outcome
What constitutes a failure
What conditions must be checked after execution
Validation must be based on:
Confirmed final transaction state via Status Inquiry / Get Status
Consistency between observed and expected results
Implicit or assumed validation is not acceptable.
Status Inquiry / Get Status provides transaction-state confirmation for reproducible Sandbox execution verification.
When webhook notifications are configured, validation should also confirm correct asynchronous notification propagation and consistency with Status Inquiry / Get Status results.
Idempotency and Duplicate Handling Awareness
Reproducible flows must account for:
Idempotency behavior
Duplicate request handling
This implies:
Avoiding unintended reuse of request identifiers
Ensuring that repeated executions do not interfere with each other
Understanding how duplicate operations are handled by the system
Failure to control these aspects may result in:
Unexpected responses
False validation outcomes
Environment Consistency
All reproducible flows must be executed under consistent environment conditions.
Avoiding cross-environment execution within the same flow
Environmental inconsistencies may lead to:
Divergent behavior
Invalid comparisons between executions
Error and Edge Case Reproducibility
Reproducibility applies equally to:
Successful scenarios
Error scenarios
Edge cases
For these scenarios:
The same structure (Initialization → Execution → Validation) must be preserved
The expected outcome must be clearly defined
Validation must confirm the specific error or edge condition
Error scenarios are considered reproducible only if they produce consistent and verifiable outcomes.
Observability and Traceability
Reproducibility requires sufficient observability and traceability of each execution.
This implies:
Logging of all request and response data
Clear association between requests and the corresponding transactionID
Ability to trace the full lifecycle of each transaction
In practice, Postman collections provide built-in mechanisms for capturing request and response data, which support traceability and validation of reproducible flows.
Observability guarantees that transaction-state evolution can be verified consistently across the full lifecycle and supports reliable validation, debugging, and operational analysis.
When extended operational diagnostics are required during reproducibility analysis, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Final Requirement
A Sandbox flow is considered reproducible only if all of the following conditions are satisfied:
Inputs are deterministic
Execution sequence is controlled and complete
Transactions are isolated
transactionID is used consistently
Expected outcomes are stable and predefined
Validation criteria are explicit and verifiable
If any of these conditions is not met, the flow cannot be considered reproducible and must not be used for integration validation.
These requirements ensure reproducibility within the Sandbox environment and must be interpreted in the context of the behavioral differences between Sandbox and Production described in F.8.4 – Sandbox vs Production Behavioral Gap.
A reproducible Sandbox flow is a structured sequence of steps that consistently produces a deterministic and verifiable transaction outcome.
Each flow must be defined so that it:
can be executed repeatedly
produces consistent results
supports controlled validation of the full transaction lifecycle
In practice, reproducible flows are executed through the official Postman collections, but correctness depends on the integrity of the full transaction sequence rather than on individual requests.
For deterministic Sandbox scenarios, the same structural sequence is represented in the SPG Sandbox Postman collection through scenario folders such as:
MB WAY → MB WAY – Success / MB WAY – Declined / MB WAY – Without ALIAS
In scenario-driven Sandbox validation, the same phase is represented by the Checkout request inside the selected scenario folder in SPG Sandbox Postman collection.
Phase 2 – Execution (Payment or Operation)
The execution phase applies the intended payment or operation to the initialized transaction.
This step:
triggers the payment or operation
produces a transaction outcome that may represent either an intermediate lifecycle state or a final transaction result
Depending on the scenario:
the outcome may be immediately final
the outcome may remain intermediate and require later confirmation
This phase must:
use the transactionID generated in the Initialization phase
follow the exact request configuration defined for the flow
The validation phase confirms the observed transaction outcome.
This step:
retrieves the current transaction state
confirms the final paymentStatus
validates consistency between the observed result and the expected outcome
When webhook notifications are configured, validation should also confirm correct asynchronous notification propagation and consistency with Status Inquiry / Get Status results.
Validation must:
be performed using Status Inquiry / Get Status
be executed after the execution phase
be treated as confirmation of the transaction result
Status Inquiry / Get Status provides transaction-state confirmation for reproducible Sandbox flow verification.
A flow is only complete when the final state has been confirmed through this phase.
In Postman, this phase corresponds to the status request, for example:
SIBS PAYMENT GATEWAY → MB WAY → getStatus
SIBS PAYMENT GATEWAY → Multibanco → getStatus
SIBS PAYMENT GATEWAY → Card → getStatus
scenario-specific Status requests in SPG Sandbox folders
any method-specific response elements required for validation
The expected outputs must be known in advance and used as the basis for validation.
Sequence Integrity
The correctness of a reproducible flow depends on maintaining strict sequence integrity.
This means:
Initialization must always precede Execution
Execution must always precede Validation
no phase may be skipped or reordered
Breaking this sequence results in:
invalid test conditions
inconsistent outcomes
unreliable validation conclusions
This is also reflected in the collections themselves, where the relevant requests are organized to support the logical order Checkout → Execution → Status.
Sequence integrity guarantees that transaction-state evolution remains consistent across the full lifecycle and prevents invalid correlation between unrelated transaction contexts.
Validation Criteria
A reproducible flow must include explicit validation criteria.
At minimum, validation must confirm:
that the final paymentStatus matches the expected scenario
that the returnStatus.statusCode is consistent with the observed outcome
that the transaction lifecycle is consistent with the expected behavior across the full flow
When extended operational diagnostics are required during reproducibility analysis, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Reproducibility Conditions
For a flow to be considered reproducible, it must satisfy the following conditions:
Deterministic inputs The same request configuration must be used for each execution.
Consistent execution sequence The same phases must be executed in the same order.
Isolated execution context Each flow must use a new transaction context.
Stable expected outcomes The expected result must remain consistent across repeated executions.
If any of these conditions is not satisfied, the flow cannot be considered reproducible.
Error and Edge Case Handling
A reproducible flow must also support validation of:
error scenarios
declined outcomes
duplicate or idempotency-related scenarios
other controlled edge cases
In these situations, the structure of the flow remains the same:
Initialization
Execution
Validation
What changes is the expected lifecycle outcome, not the structural model of the flow.
This is particularly evident in the SPG Sandbox collection, where multiple scenario folders preserve the same structural pattern while changing the expected result.
Final Consideration
A reproducible Sandbox flow is not defined by isolated requests, but by the consistency of the full sequence and its validated final outcome.
By structuring flows around:
Initialization
Execution
Validation
and by enforcing strict sequencing and validation criteria, integrators can ensure that:
test scenarios are reliable
outcomes are predictable
integration behavior is correctly validated under controlled conditions
The Postman collections provide the executable form of these flows, but reproducibility depends on preserving the integrity of the full lifecycle from Checkout to final Status confirmation.
This structured approach ensures correct execution in Sandbox but must be interpreted in light of the behavioral differences between Sandbox and Production described in F.8.4 – Sandbox vs Production Behavioral Gap.
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.
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)
Execute this step in Postman using:
Collection Path:
SIBS PAYMENT GATEWAY → General → Get Status
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.
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:
POST <ROOT_URL>/payments
POST <ROOT_URL>/payments/{transactionID}/[payment-method]/...
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:
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.
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.
In addition to the official Postman collections, the Sandbox Payment Simulator may be used to execute predefined payment scenarios through a browser-based interface, allowing integrators to validate payment-method-specific behaviours, transaction lifecycle progression, and operational request/response flows without implementing a complete integration.
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.
Sandbox reproducibility complements, but does not replace, the broader production-readiness validation activities described in F.6 – Production Readiness Guidelines.
Sandbox scenarios must be executed following the request sequences defined in the Postman collections.
A standard execution flow consists of:
Checkout Request
POST <ROOT_URL>/payments
Retrieves:
transactionID
transactionSignature
Payment Execution
Method-specific endpoint:
POST <ROOT_URL>/payments/{transactionID}/mbway-id/purchase
POST <ROOT_URL>/payments/{transactionID}/card/purchase
POST <ROOT_URL>/payments/{transactionID}/service-reference/generate
Status Validation
GET <ROOT_URL>/payments/{transactionID}/status
Webhook Validation (when configured)
Validate asynchronous notification delivery, transaction correlation, and state propagation behavior
Status Inquiry / Get Status provides transaction-state confirmation for Sandbox reproducibility and lifecycle consistency verification.
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.
Sequential execution guarantees that transaction-scoped identifiers and lifecycle state remain consistent across all requests participating in the same Sandbox scenario.
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 primary SPG identifier for all transaction-scoped 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 merchant.merchantTransactionId is included in requests:
It is not the primary SPG identifier of the transaction lifecycle
It must not be used to drive transaction state, reconciliation, or lifecycle decisions
Observability and Execution Traceability
The Postman collections provide built-in mechanisms to support reproducibility:
Structured request grouping by deterministic 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.
Limitations of Sandbox
Sandbox is a controlled simulation environment and does not fully replicate production operational 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 intentionally deterministic, and external dependencies are not represented.
Final Consideration
The official Postman collections provide the reference execution framework for Sandbox reproducible examples, enabling deterministic validation of all supported flows.
A correct integration must demonstrate:
Consistent use of transactionID
Proper lifecycle handling
Reliable transaction-state confirmation through Status Inquiry / Get Status when required
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.
Operational resilience under real-world concurrency, infrastructure variability, network instability, issuer behavior, and distributed timing conditions must be validated separately during production-readiness activities.
When extended operational diagnostics are required during Sandbox validation, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
A fundamental integration pitfall in SIBS Payment Gateway (SPG) implementations is the lack of a true end-to-end validation mindset.
This occurs when integrations are validated only at the level of:
individual API calls
isolated components
or controlled test scenarios
without validating the complete transaction journey across all system boundaries and lifecycle stages.
In SPG, correctness is not defined by isolated success, but by the ability of the system to behave consistently across the entire end-to-end flow, including asynchronous interactions, state evolution, and cross-system coordination.
Nature of the Problem
SPG integrations span multiple layers and interaction points:
client or front-end initiation
backend API interactions
SPG processing
asynchronous webhook notifications
Status Inquiry / Get Status confirmation when required
internal system updates and business actions
Each of these components may function correctly in isolation, yet the overall system may still fail when:
interactions are combined
timing variability is introduced
real-world conditions are applied
End-to-end validation is therefore required to ensure that the complete transaction lifecycle behaves correctly, not just its individual parts.
Transaction-state reconciliation during validation scenarios should use E.2 – Status Inquiry / Get Status when confirmation or reconciliation is required rather than assumptions derived solely from webhook timing or intermediate transaction states.
See also E.1 – Webhooks (Notifications) for detailed guidance regarding asynchronous notification delivery, retry behavior, and event propagation semantics.
The Core Pitfall
The core issue arises when integrations assume:
“If each component works correctly, the system works correctly.”
This assumption is invalid in SPG integrations.
Common manifestations include:
validating only API request/response correctness
testing webhook handling independently from transaction initiation
verifying isolated success scenarios without full lifecycle coverage
assuming that correct component behavior guarantees correct system behavior
These approaches ignore the operational complexity introduced by interaction, timing variability, and distributed state evolution across components.
Incorrect Validation Patterns
A lack of end-to-end validation typically manifests as:
Testing only deterministic happy-path scenarios
Not validating asynchronous flows from initiation to final state
Not correlating API calls, webhooks, and status inquiries in tests
Skipping validation of retry, delay, and failure scenarios
Not verifying consistency between SPG state and internal system state
Validating components in isolation without system-level integration tests
These patterns result in a false sense of correctness prior to production deployment.
Correct Validation Approach
A correct implementation must adopt a system-level validation strategy, where:
full transaction flows are tested from initiation to final outcome
all interaction points are validated together, including:
API requests
webhook notifications
status inquiries
validation includes:
asynchronous behavior
state transitions over time
interaction between components
Testing must ensure that:
the system reaches correct final states
intermediate states are handled correctly
all components remain operationally and transactionally consistent with each other
When extended operational diagnostics are required during validation activities, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Relationship with Other Integration Pitfalls
The lack of end-to-end validation often amplifies other pitfalls described in this chapter:
Without end-to-end validation, these issues remain undetected until production.
Consequences of Inadequate Validation
Failure to validate end-to-end behavior leads to:
discrepancies between expected and actual transaction outcomes
inconsistent system state across components
incorrect handling of asynchronous flows
production issues that were not detected during testing
increased operational and support overhead
reduced confidence in system reliability
These issues are often only discovered after go-live, when real-world conditions expose integration weaknesses.
Key Principle
Correctness in SPG integrations must be validated end-to-end, not component-by-component.
Proper validation requires:
testing complete transaction journeys across all system boundaries
validating behavior under real-world conditions
ensuring consistency across all interaction points and lifecycle stages
Any integration that does not adopt an end-to-end validation mindset will produce systems that appear correct in isolation but fail under real operational conditions.
A critical integration pitfall in SIBS Payment Gateway (SPG) implementations is the inadequate interpretation and handling of error conditions and transaction outcomes.
This occurs when integrators:
misinterpret response fields
conflate technical and business outcomes
or apply simplistic success/failure logic
In SPG, transaction responses contain multiple layers of meaning, and correct behavior depends on interpreting them accurately within the transaction lifecycle. Misinterpretation leads to incorrect system decisions and inconsistent business outcomes.
SPG responses typically include distinct indicators that must be interpreted independently:
returnStatus → represents the technical processing result of the request
paymentStatus → represents the business outcome or current state of the transaction
statusDescription → may provide additional operational or business context explaining the transaction state or outcome
These dimensions represent distinct operational and business semantics and must not be interpreted as equivalent.
A technically successful response does not necessarily indicate a successful payment outcome, and a non-final payment state does not necessarily indicate an error.
Correct interpretation requires understanding the relationship between these dimensions.
The Core Pitfall
The core issue arises when integrations assume:
“If the request was successful, the payment was successful.”
or conversely:
“If the payment is not successful, the request failed.”
Both assumptions are incorrect.
Typical misinterpretations include:
Treating returnStatus.statusCode = "000" as confirmation of payment success
Treating non-final states (e.g., Pending) as failures
Treating declined payments as technical errors
Ignoring the distinction between processing errors and business outcomes
These mistakes incorrectly collapse distinct operational and business concepts into a single success/failure model.
Final transaction state must be determined from validated final paymentStatus data, or through E.2 – Status Inquiry / Get Status when confirmation, recovery, or reconciliation is required. Webhook notifications should be treated as asynchronous state propagation mechanisms and not as isolated confirmation events.
Incorrect Implementation Patterns
Inadequate error interpretation typically manifests as:
Triggering business success actions based solely on returnStatus
Failing to act on paymentStatus changes
Misclassifying declined payments as system errors
Not distinguishing between temporary states and final outcomes
Applying uniform error handling across all scenarios
Ignoring contextual information when evaluating transaction results
These patterns result in incorrect decision-making and inconsistent system behavior.
Correct Interpretation Model
A correct implementation must treat SPG responses as multi-dimensional signals, where:
Technical processing (returnStatus) → confirms whether the request was correctly received and processed
Business outcome (paymentStatus) → defines the current transaction state within its lifecycle
Both dimensions must be evaluated independently and in context.
This requires:
Basing business decisions on paymentStatus, not returnStatus
Recognizing intermediate states as part of normal processing
Distinguishing between:
technical failures (e.g., invalid request)
business outcomes (e.g., declined payment)
As defined in F.3 – Success and Error Scenarios, correct interpretation depends on understanding the meaning of each status within the transaction lifecycle.
Handling decisions such as retry, failure, or user action must be based on error classification (e.g., Txxxx for temporary conditions requiring retry, Exxxx for validation or business errors requiring correction or user-driven resolution).
Lifecycle-Aware State Interpretation
Error interpretation is directly tied to lifecycle management.
Because transaction states evolve over time:
a response may reflect an intermediate state
final outcomes may be delivered asynchronously
multiple updates may occur before completion
Incorrect interpretation leads to:
premature decisions
incorrect state transitions
inconsistent system behavior
A correct implementation must interpret responses in the context of ongoing state evolution, not as isolated events.
Asynchronous Outcome Evolution
Asynchronous behavior increases the complexity of error interpretation.
For example:
a transaction may initially return a successful technical response but remain in Pending
a webhook may later indicate a final outcome
multiple status updates may occur over time
See E.1 – Webhooks (Notifications) for detailed guidance regarding asynchronous notification delivery and state propagation behavior.
A correct implementation must:
avoid interpreting intermediate states as errors
handle delayed and asynchronously evolving outcomes appropriately
ensure that final decisions are based on validated final paymentStatus data, or on Status Inquiry / Get Status when confirmation, recovery, or reconciliation is required
When extended operational diagnostics are required, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.
Failure to do so leads to incorrect conclusions about transaction success or failure.
Consequences of Inadequate Error Handling
Improper interpretation and handling of errors leads to:
incorrect confirmation or rejection of transactions
misclassification of valid declines as system failures
premature cancellation of valid transactions
inconsistent transaction state across systems
incorrect user communication
increased reconciliation complexity
These issues directly impact both system reliability and user trust.
Key Principle
SPG responses must be interpreted as multi-dimensional and state-dependent signals, not as simple success/failure indicators.
Correct integration behavior requires:
separating technical processing results from business outcomes
interpreting transaction states within their lifecycle context
handling intermediate and final states appropriately
Any integration that reduces SPG responses to a single success/failure dimension will produce incorrect, inconsistent, and unreliable behavior in production environments.
