> For the complete documentation index, see [llms.txt](https://docs.optty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optty.com/direct-api-orders/sandbox-payment-method-simulator.md).

# 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

<table data-header-hidden><thead><tr><th width="111.8515625">Scenario</th><th>Configuration</th><th>Benefit</th></tr></thead><tbody><tr><td>Happy Path</td><td>Status: Successful | Initial: Instant</td><td>Quick verification of the checkout flow.</td></tr><tr><td>Async Webhooks</td><td>Status: Successful | Initial: Pending</td><td>Tests if your backend correctly handles <code>ORDER_STATUS</code> updates via webhooks.</td></tr><tr><td>Error Handling</td><td>Status: Declined/Error</td><td>Ensures your UI correctly displays error messages to users.</td></tr><tr><td>Edge Cases</td><td>Browser Crash / Timeout</td><td>Test system resilience when the redirect is interrupted.</td></tr></tbody></table>

***

### 📝 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.