> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashweb.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Test your integration against the CashWeb staging environment before going live.

## Staging Environment

|              |                                                   |
| ------------ | ------------------------------------------------- |
| **Base URL** | `https://api-staging.cashweb.cash/api/v1/partner` |
| **Purpose**  | Integration testing and development               |

Sandbox partner transactions are currently restricted to a single canonical deposit pair:

* **Token:** `usdt`
* **Network:** `bep20`

This keeps upstream Quidax address allocation efficient in test environments.

## Getting Sandbox Credentials

Contact the CashWeb team to receive staging API keys:

* **Email:** [michael@cashweb.cash](mailto:michael@cashweb.cash)

Include your company name and intended use case in the request.

## Testing Workflow

### 1. Create a Quote

```bash theme={null}
curl -X POST "https://api-staging.cashweb.cash/api/v1/partner/quotes" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $SANDBOX_API_KEY" \
  -d '{
    "crypto_currency": "usdt",
    "crypto_amount": "10.00",
    "network": "bep20"
  }'
```

### 2. Create a Transaction

```bash theme={null}
curl -X POST "https://api-staging.cashweb.cash/api/v1/partner/transactions" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $SANDBOX_API_KEY" \
  -H "Idempotency-Key: test-tx-001" \
  -d '{
    "quote_id": "<quote_id_from_step_1>",
    "network": "bep20",
    "merchant_reference": "test-order-001"
  }'
```

### 3. Verify Webhook Delivery

Set up a webhook endpoint (use a service like webhook.site for testing) and verify you receive `transaction.created` events.

### 4. Query Transaction Status

```bash theme={null}
curl "https://api-staging.cashweb.cash/api/v1/partner/transactions/<transaction_id>" \
  -H "X-API-KEY: $SANDBOX_API_KEY"
```

### 5. Simulate Lifecycle Events

Use the staging-only sandbox simulator to drive partner webhook and TSQ flows from one standalone endpoint:

You must first create a transaction and use the returned transaction `id` as `transaction_id`. The simulator does not create transactions for you.

```bash theme={null}
curl -X POST "https://api-staging.cashweb.cash/api/v1/partner/sandbox/simulate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $SANDBOX_API_KEY" \
  -d '{
    "transaction_id": "<transaction_id>",
    "event": "deposit.confirmed"
  }'
```

Request fields:

* `transaction_id`: target CashWeb partner transaction id returned by `POST /transactions`
* `event`: lifecycle event to simulate
* `deposit_id`: optional stable override for the simulated deposit identifier
* `blockchain_hash`: optional stable override for simulated deposit chain data

Supported simulated events:

* `deposit.detected`
* `deposit.confirmed`
* `transaction.completed`
* `transaction.failed`
* `transaction.expired`
* `transaction.refunded`
* `payout.settled`

Behavior notes:

* This endpoint exists only in staging and test environments.
* Production does not mount the route at all.
* `deposit.detected` creates or reuses a deposit record and emits the corresponding partner webhook.
* `deposit.confirmed` reuses the same transaction and deposit progression logic as normal deposit handling.
* `transaction.completed`, `transaction.failed`, `transaction.expired`, and `transaction.refunded` advance the transaction through the same lifecycle machinery used by normal processing.
* `payout.settled` emits the payout-settled partner webhook

## Staging vs Production

| Behavior    | Staging                     | Production                        |
| ----------- | --------------------------- | --------------------------------- |
| API keys    | Sandbox-only credentials    | Production credentials            |
| Rate limits | Relaxed                     | Enforced                          |
| Webhooks    | Delivered to test endpoints | Delivered to registered endpoints |
| Blockchain  | Mainnet deposits            | Mainnet deposits                  |
| Payouts     | Simulated                   | Real fiat settlements             |