Sandbox Payment Method (Simulator)
The Sandbox APM is a dedicated payment simulation tool within the Optty sandbox environment. It is designed to remove dependencies on third-party APM sandbox environments, eliminating the need for merchants to manage multiple test credentials or external login details.
By using this single method, partners and merchants can simulate a wide range of payment behaviours, technical flows, and edge cases—making it an essential tool for testing complex integrations.
🚀 Why Use the Sandbox APM?
Unified Testing: Simulate all payment scenarios (success, decline, pending, and refunds) easily through one interface.
Asynchronous Simulation: Test how your system handles "Pending" states and subsequent webhook notifications without depending on third party APM environments.
Customisable Behaviour: Configure the final outcome and timing of every transaction directly on the checkout page.
🛠 How It Works
When using the Sandbox APM in a test environment, the simulation is triggered based on the transaction setup which is configured by the user when opening the "redirectUrl".
1. Payment Configuration
On the simulator checkout page, you can define the following parameters for the current transaction:
Final Status: Choose between Successful, Declined, Cancelled, or Error.
Initial Response:
Instant: The final status is returned immediately in the redirect URL.
Pending: The system returns an instant "Pending" status. You must then wait for an asynchronous notification (webhook) or poll the "Get Order Status" API to receive the final outcome.
Webhook Timing: If a Pending state is selected, you can configure the delay for the asynchronous notification to either 10 seconds or 2 minutes.
10 seconds allows testing that the customers final status page is updated upon recieving the webhook while they are still present.
2 minutes can be used to ensure the customer is notified of the final payment status after leaving the checkout page.
2. Refund Simulation
Refunds are initiated via the standard Refund API. You can pre-configure how the simulator handles these requests:
Instant Refunds: Immediate success or failure.
Asynchronous Refunds: Simulates a pending refund that resolves later.
💡 Common Use Cases
Happy Path
Status: Successful | Initial: Instant
Quick verification of the checkout flow.
Async Webhooks
Status: Successful | Initial: Pending
Tests if your backend correctly handles ORDER_STATUS updates via webhooks.
Error Handling
Status: Declined/Error
Ensures your UI correctly displays error messages to users.
Edge Cases
Browser Crash / Timeout
Test system resilience when the redirect is interrupted.
📝 Important Notes
Per-Transaction Configuration: Settings applied on the checkout page are specific to that individual payment and do not persist to the next transaction.
Sandbox Only: This tool is strictly available in the sandbox environment and cannot be used in production.
Last updated