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

# Sandbox and testing overview

> An overview of the sandbox: which simulation capabilities the backend supports, the sandbox and production base URLs, what you need in place before you simulate, and a minimal request and response for the fund-auth simulation endpoint. For scenario-by-scenario cases, see Simulating transactions.

## 📄 Guide

Whether you want to check that an authorization callback parses correctly or to run the whole chain from card use through authorization forwarding to posting before you go live, you can do it all in the sandbox, with no real card network, no real money, and no real cardholder ever involved. As a licensed card issuer, DCS gives partners a sandbox built to the same shape as production, so you can rehearse your authorization decision logic from the earliest days of integration.

### Does the backend support simulation?

**Yes, but only within limits.** As of the current release, the Partner-Managed API provides **one simulation endpoint**:

| Capability                                                                | Endpoint                                 | Status                     |
| ------------------------------------------------------------------------- | ---------------------------------------- | -------------------------- |
| Simulate an authorization request (purchase / return / purchase reversal) | `POST /open-api/simulation/v1/fund-auth` | ✅ Available (sandbox only) |
| Simulate clearing (capture / settlement)                                  | —                                        | Planned                    |
| Simulate partial clearing / multi-part clearing                           | —                                        | Planned                    |
| Simulate a 3DS challenge                                                  | —                                        | Planned                    |
| Simulate a deposit top-up or limit change                                 | —                                        | Planned                    |

> Sandbox simulation today focuses on the authorization stage; dedicated endpoints for clearing, 3DS, deposits and the like are still planned. If your testing needs any of those scenarios, talk to the DCS team about a workable alternative.

### What the sandbox does for you

The `fund-auth` simulation endpoint triggers a **genuine authorization forwarding flow**: once DCS receives your simulated request, it pushes the authorization notification to the `authUrl` you configured over exactly the same path as production, and you return the approve-or-decline decision. That makes it a good fit for:

* checking that **RSA two-way signing plus encryption and decryption** on the authorization notification works end to end;
* checking your own **authorization decision logic** (limit checks, risk rules, timeout fallbacks);
* checking that your system transitions state correctly across all three scenarios: `EXPEND` (purchase), `REFUND` (return) and `REVERSAL` (purchase reversal).

### Base URLs

| Environment | Base URL                            |
| ----------- | ----------------------------------- |
| Sandbox     | `https://api.thedecard-sandbox.com` |
| Production  | `https://api.thedecard.com`         |

<Note>
  the simulation endpoint is available in the **sandbox only**. Production blocks the path outright and returns `OPERATION_NOT_SUPPORT`, so never call a `simulation` endpoint against production.
</Note>

### What you need before you simulate

| Prerequisite             | Description                                                                                       | Owner             |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ----------------- |
| Sandbox API credentials  | `api_key` + `secret_key`, used for HMAC-SHA256 authentication                                     | Provided by DCS   |
| RSA key pair             | You generate and upload `external_public_key`; DCS gives you the DCS-side public key              | Partner + DCS     |
| `authUrl`                | The callback URL that receives authorization notifications; it must be reachable from the sandbox | Partner           |
| A usable card            | Complete "create user, KYC, apply for card" in the sandbox first and keep the `cardId`            | Partner           |
| Enterprise deposit limit | The sandbox side needs available limit, otherwise authorizations are declined                     | Configured by DCS |

> For the full explanation of the authentication headers, RSA key generation with `openssl`, and the IP whitelists, see [Authentication](../../integration-resources/authentication).

### Minimal request

```bash theme={null}
curl -X POST https://api.thedecard-sandbox.com/open-api/simulation/v1/fund-auth \
  -H "Content-Type: application/json" \
  -H "X-DAPI-API-KEY: <your_api_key>" \
  -H "X-DAPI-TIMESTAMP: <timestamp-ms>" \
  -H "X-DAPI-NONCE: <10000-99999>" \
  -H "X-DAPI-SIGN: <signature>" \
  -d '{
    "cardId": "<the card ID you created in the sandbox>",
    "authType": "EXPEND",
    "amount": 12.50,
    "currency": "USD"
  }'
```

**Request fields** (source: `POST /open-api/simulation/v1/fund-auth`):

| Field      | Type   | Required | Description                                                                                  |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `cardId`   | string | Yes      | Card ID                                                                                      |
| `authType` | string | Yes      | Authorization type: `EXPEND` (purchase) / `REFUND` (return) / `REVERSAL` (purchase reversal) |
| `amount`   | number | Yes      | Amount as a decimal, in major currency units                                                 |
| `currency` | string | Yes      | Transaction currency, 3-letter ISO currency code (such as `USD` / `SGD` / `EUR` / `JPY`)     |

### Minimal response

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "approved": true,
    "errorCode": null
  }
}
```

**Response fields**:

| Field            | Type    | Description                                                                                  |
| ---------------- | ------- | -------------------------------------------------------------------------------------------- |
| `data.approved`  | boolean | Whether the authorization was approved, that is, the decision you returned at your `authUrl` |
| `data.errorCode` | string  | The error code when declined                                                                 |

> **The standard response envelope**: every endpoint returns `{ code, message, messageDetail, data }`. `code` reports the outcome of the system call (`SYS_SUCCESS`, for example), while the business outcome must be read from inside `data`, here `approved`. A `code=SYS_SUCCESS` means only that the request was accepted correctly, not that the authorization was approved, so never judge the business outcome from `code` alone. `messageDetail` is a prompt object aimed at end users and is often `null`. For the full contract of the envelope, see [Authentication](../../integration-resources/authentication).

### A suggested verification loop

1. Call `fund-auth` with `authType=EXPEND` and watch for DCS pushing an authorization notification to your `authUrl`.
2. At `authUrl`, verify the signature, decrypt, make your decision, then sign and return it.
3. Check that `data.approved` in the `fund-auth` response matches the decision you returned.
4. Repeat with `authType=REFUND` and `REVERSAL` to exercise the return and reversal paths.

## Next steps

For scenario-by-scenario simulation cases (purchase, return and reversal, plus how to handle clearing, partial and multi-part clearing, 3DS and other capabilities still to be confirmed), see [Simulating transactions](./simulating-transactions).