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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.optty.com/direct-api-orders/sandbox-payment-method-simulator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.