Overview
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.
This chapter complements the deterministic and reproducible model defined in F.8.1 – Deterministic Scenario Modeling in Sandbox, F.8.2 – Structure of a Reproducible Sandbox Flow, and F.8.3 – Reproducibility Requirements by explaining how Production behavior differs from Sandbox assumptions.
Determinism vs Real-World Variability
In Sandbox:
- 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.
See E.1 – Webhooks (Notifications) and E.2 – Status Inquiry / Get Status for detailed guidance regarding asynchronous notification handling, transaction-state reconciliation, and transaction-state confirmation and reconciliation semantics.
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
paymentStatusdata, 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.
These considerations must be applied on top of the deterministic execution and validation model defined in F.8.1 – Deterministic Scenario Modeling in Sandbox, F.8.2 – Structure of a Reproducible Sandbox Flow, and F.8.3 – Reproducibility Requirements.
Final Consideration
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.
The deterministic and reproducible approach defined in F.8.1 – Deterministic Scenario Modeling in Sandbox, F.8.2 – Structure of a Reproducible Sandbox Flow, and F.8.3 – Reproducibility Requirements provides the foundation for validation, but Production readiness depends on correctly handling the behavioral differences described in this chapter.