Sandbox environment
The Cardflo payment gateway sandbox provides quality assurance engineers and developers with an isolated testing environment to simulate transaction lifecycles safely. Teams can trigger specific decline codes and validate error handling without moving actual funds before proceeding to production deployment.
- Category
- Developer
- Capabilities
- 10
- Available on
- All plans
The Cardflo sandbox environment allows developers to integrate and test payment solutions without affecting live transactions. This isolated space mirrors our production environment, enabling thorough testing of all Cardflo features, from payment processing to webhooks and API interactions, ensuring a smooth transition to live operations.
Testing in the sandbox environment allows merchants to rigorously validate their payment integrations and simulate the entire transaction lifecycle. This vital step ensures readiness for live processing, minimising risks and errors upon launch.
Sandbox environment overview
A sandbox environment acts as a non-production instance of a payment gateway or orchestration platform, allowing developers to model the entire transaction lifecycle without moving real funds. It operates as a replica of the live API, including components for authorisation, capture, and settlement.
Within this isolated container, technical teams can verify their integration logic, request structures, and authentication headers against strict validation rules. By using test credentials and simulated Card Identification Numbers (BINs), merchants can evaluate how their backend reacts to various responses, such as successful payments, soft declines, or 3DS authentication prompts.
The sandbox sits between the merchant application and the simulated acquirer, providing a safe space to ensure that the code handles edge cases, such as insufficient funds or expired cards, before moving to a live production environment where errors could result in loss of revenue or increased chargeback ratios.
How sandbox environment works
Credential generation and authentication
Developers obtain a specific set of API keys or Bearer tokens designated for the testing environment. These credentials route requests to a mock processor rather than the live payment schemes. This ensures that no merchant identification number (MID) is billed for processing fees and no real cardholder data enters the production systems.
Simulated transaction processing
The merchant sends a payment request using predefined test card numbers that trigger specific outcomes. For example, using one BIN might simulate a successful authorisation, while another triggers a CVV mismatch or a hard decline. The sandbox returns an identical JSON response structure to the live API to ensure compatibility.
Webhook event notification
Once a transaction status changes in the sandbox, the system generates asynchronous webhooks. The merchant server receives these notifications at a designated endpoint to verify that their system correctly updates the internal database. This step is critical for testing automatic order fulfilment or subscription management logic in real time.
State change and settlement
Users can manually or programmatically transition the state of a transaction from authorised to settled or refunded within the testing dashboard. This allows for the verification of post-purchase workflows, including the handling of retrieval requests or partial refunds, ensuring the merchant UI reflects the correct financial state.
Why sandbox environment matters
Risk mitigation during deployment
Implementing new payment flows directly in production creates high operational risk. By utilising a sandbox, developers can identify logical errors or malformed API requests that would otherwise lead to failed checkouts. This isolation protects the integrity of the live Merchant Identification Number and prevents accidental triggers of anti-fraud filters that could occur during aggressive testing of new card-present or card-not-present integration logic.
Validation of complex logic
Modern payments often involve multi-step processes like Strong Customer Authentication (SCA) or recurring billing. A sandbox allows for the rigorous testing of cardholder-initiated and merchant-initiated transactions without the financial cost of real transactions. It ensures that the system correctly interprets various decline codes and response messages from issuers, allowing for the refinement of dunning logic and retry strategies to optimise eventual conversion rates.
Sandbox environment use cases
Dummy card outcome testing
Quality assurance engineers use dummy Visa and Mastercard numbers to exercise approved, declined and invalid card outcomes without moving funds. Cardflo’s payment gateway sandbox returns deterministic authorisation responses, allowing developers to verify order states, customer messaging and test evidence before production onboarding.
Testing recurring payment lifecycles
Developers trigger specific issuer-style decline codes to confirm that insufficient funds, expired card and suspected fraud responses follow distinct application paths. Cardflo’s payment gateway sandbox supplies repeatable response codes so teams can validate retry suppression, error mapping and operational logging against each simulated outcome.
Network timeout recovery tests
Quality assurance teams simulate network timeouts and delayed gateway responses to test idempotency, duplicate submission controls and uncertain transaction states. Cardflo’s sandbox provides controlled failure conditions so developers can confirm safe retries, status polling and reconciliation behaviour when an authorisation response does not arrive as expected.
Sandbox rate limit validation
Engineering teams generate controlled request bursts to check how integrations behave when sandbox environment rate limits are reached during automated test suites. Cardflo exposes predictable throttling responses, enabling developers to validate backoff intervals, queue handling and request logging without confusing test limits with production capacity planning.
Sandbox environment by the numbers
Typical efficiency gains observed by technical teams when using a comprehensive sandbox compared to manual documentation review and direct production testing.
Estimated range of reduction in post-deployment bugs related to payment logic when rigorous sandbox testing is implemented as part of the CI/CD pipeline.
Industry standard response time for mock API endpoints, allowing for rapid iteration during the software development lifecycle.
Methodology: these figures are illustrative ranges drawn from published industry data and observed merchant cohorts, not guarantees. Actual results depend on your risk profile, card mix, geography and acquiring setup, and are confirmed only in your own pricing and approval terms.
Related terms
Talk to our team about a live rollout across our acquirer partners' rails.
What you get with Sandbox environment
- Verify API request and response structures against official documentation in a secure environment.
- Simulate specific authorisation decline reasons to validate error handling and customer messaging.
- Trigger and receive webhook notifications for status updates like capture, refund, and dispute.
- Test 3D Secure authentication flows to ensure compliance with PSD2 and SCA requirements.
- Validate the handling of network tokens and account updater notifications without real data.
- Perform load testing on integration logic before transitioning to higher volume production environments.
- Configure multiple merchant profiles to test currency conversion and domestic versus international processing.
- Audit the logging of transaction IDs, ARNs, and timestamps for internal financial reconciliation.
- Model the behaviour of partial captures and multiple refunds on a single transaction.
- Examine the impact of merchant category codes on simulated authorisation rates and fee structures.
A short scoping call, then a written plan for your MIDs.
Questions about Sandbox environment
Do sandbox transactions appear on real bank statements or incur scheme fees?
No, transactions processed within a sandbox environment do not interact with actual payment schemes like Visa or Mastercard. They are handled by a mock processor that simulates the issuer response.
Consequently, no real funds are moved, no cardholder is charged, and the merchant does not incur any interchange or scheme fees. The environment is entirely isolated to prevent financial impact.
How can a payment gateway sandbox trigger specific card decline codes?
QA engineers can submit designated dummy card numbers or documented test values that map to specific decline responses in the payment gateway sandbox.
Each trigger produces a predictable code and transaction state without moving funds, allowing applications to verify customer messaging, retry controls and order handling.
Test results should be recorded against the expected response mapping because sandbox codes may represent simulated gateway or acquirer partner outcomes rather than issuer behaviour.
How do I simulate a hard decline versus a soft decline in testing?
Simulation is usually achieved by using different test card numbers or transaction amounts specified in the documentation. A specific BIN might be mapped to a 'Lost or Stolen' response (hard decline), while another might trigger 'Insufficient Funds' (soft decline).
Testing these variants is vital for developers to implement proper retry logic and to distinguish between permanent and temporary failures.
Is stored cardholder data in the sandbox subject to PCI DSS compliance?
While the sandbox should not contain real cardholder data, the security of the API keys and the simulated data remains important. Most sandbox environments use pseudo-data that resembles real PANs but fails Luhn algorithm checks or belongs to unassigned ranges.
However, developers should maintain good security practices and never use real customer data within a testing environment to avoid potential data leakage risks.
Will my webhook endpoints receive the same payload as the production environment?
The JSON or XML payload delivered to your webhook URL in the sandbox should mirror the production schema exactly. This includes the same fields for transaction ID, amount, currency, and status codes.
Testing this ensures that your backend parser is correctly configured to handle the live data stream without needing to make code changes during the transition to production.
Can I test the settlement and reconciliation process in the sandbox?
You can simulate the transitions that lead to settlement, such as moving a transaction from 'authorised' to 'captured'. Some sandboxes allow you to generate mock reports that resemble the settlement files provided by acquirers.
This helps in building automated reconciliation tools that match internal order IDs with the transaction references provided by the payment service provider.
Related guides.
See how Cardflo compares.
Ready to improve your payments setup?
Tell us about your business. We'll match you with the right acquiring partners and the right route, typically inside a week.