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

# Simulating transactions: authorization, clearing, refunds, partial, multi-part, 3DS

> Walks through the fund-auth simulation endpoint scenario by scenario: authentication and request headers, request and response fields, which scenarios each of the three authorization directions (EXPEND / REFUND / REVERSAL) can drive, a recommended regression order, and the scenarios that have no dedicated simulation entry point yet. For the sandbox itself and its prerequisites, see Sandbox and testing overview.

## Simulating transactions

Whether you have just wired up the authorization callback or are running a final regression before go-live, a single sandbox endpoint lets you exercise the whole "card use, authorization, return, reversal" sequence and confirm that your `authUrl` decision logic and your `webhookUrl` posting logic are correct, with no real money and no real card network involved at any point. DCS is a licensed card issuer, and the sandbox shares the same authorization forwarding path as production, so whatever you get working in the sandbox migrates cleanly to production.

Under the Partner-Managed model, the limit is **held** by you and the authorization is **decided** by you. That is why the real value of sandbox simulation is that it **drives a genuine authorization forwarding round trip**: once DCS receives your simulated transaction, it forwards the authorization request to your configured `authUrl` exactly as it would for a real card use, waits for your approve-or-decline answer, and then calls your `webhookUrl` accordingly.

> Who does what
>
> * **DCS**: receives the simulation request, creates the transaction, forwards the authorization to `authUrl`, then calls back `webhookUrl` based on your decision.
> * **Partner**: sends the simulation request, returns the authorization decision at `authUrl`, then receives the callback at `webhookUrl` and posts it.

***

## Endpoint: simulate an authorization request

**`POST /open-api/simulation/v1/fund-auth`**

Simulates one authorization request (purchase, return or purchase reversal), which triggers the complete authorization forwarding and webhook notification chain in the sandbox.

> This endpoint is **sandbox-only (QA/DEV)**. A call against production is blocked and returns `OPERATION_NOT_SUPPORT`.

### Authentication and request headers

As with every `/open-api/` endpoint, you must send the authentication headers and set `Content-Type: application/json`. For the full rules, see [Authentication](../../integration-resources/authentication).

| Header             | Required | Description                                                        |
| ------------------ | -------- | ------------------------------------------------------------------ |
| `Content-Type`     | Yes      | Fixed value `application/json`                                     |
| `X-DAPI-API-KEY`   | Yes      | The `apiKey` DCS issued to you                                     |
| `X-DAPI-TIMESTAMP` | Yes      | Request timestamp (milliseconds, UTC), used for replay protection  |
| `X-DAPI-NONCE`     | Yes      | Random number in the range `[10000, 99999]`, for replay protection |
| `X-DAPI-SIGN`      | Yes      | HMAC-SHA256 signature (lowercase hexadecimal)                      |

### Request parameters

| Field      | Type   | Required | Description                                                                                        | Constraints                                     |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `cardId`   | string | Yes      | Card ID. The card must be in a usable state                                                        | —                                               |
| `authType` | string | Yes      | Authorization type: `EXPEND` purchase / `REFUND` return / `REVERSAL` purchase reversal             | One of the three values                         |
| `amount`   | number | Yes      | Amount as a decimal, positive, in the major unit of the currency                                   | Up to 10 integer digits, up to 2 decimal places |
| `currency` | string | Yes      | Transaction currency, ISO 4217 three-letter code (`USD` / `CNY` / `SGD` / `EUR` / `JPY` and so on) | —                                               |

> Field source: `POST /open-api/simulation/v1/fund-auth` (`APISimulationAuthRequest`). The endpoint currently does **not** accept parameters such as merchant name (`merchantName`), merchant category code (MCC) or an explicitly chosen decline reason (`declineReason`). If you need any of these later, talk to the DCS team.

### Request example (purchase)

```json theme={null}
{
  "cardId": "CARD_20250101XXXX",
  "authType": "EXPEND",
  "amount": 50.00,
  "currency": "USD"
}
```

### Response example

A successful call returns the standard response envelope, with the authorization outcome inside `data`:

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

When the authorization is declined, for instance because your `authUrl` returned a decline:

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

### Response fields

| Field            | Type    | Description                                                                                   |
| ---------------- | ------- | --------------------------------------------------------------------------------------------- |
| `data.approved`  | boolean | Whether the simulated authorization was ultimately approved                                   |
| `data.errorCode` | string  | The error code when it was not approved (see the error code dictionary for individual values) |

> About the standard response envelope `{code, message, messageDetail, data}`: `code` is the system-level status (such as `SYS_SUCCESS`), while `message` and `messageDetail` carry prompt text.

<Warning>
  Note: **a successful HTTP call plus `code=SYS_SUCCESS` does not mean the authorization was approved.** For this endpoint, whether the authorization passed is determined by `data.approved`; an `approved=false` result comes back inside the very same `SYS_SUCCESS` envelope. Never judge the business outcome from the envelope alone. For how the error codes are classified, see [Error code dictionary](../transactions/decline-codes).
</Warning>

***

## What the simulation can drive

The DCS sandbox uses `authType` to distinguish three authorization directions, which together cover the core authorization forwarding loop:

| authType   | Simulated action  | Direction of funds                             | Typical use                                                         |
| ---------- | ----------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| `EXPEND`   | Purchase          | OUTGOING (consumes limit)                      | Test your `authUrl` approve or decline decision and webhook posting |
| `REFUND`   | Return            | INCOMING (money back)                          | Test the return callback and the reconciliation direction           |
| `REVERSAL` | Purchase reversal | INCOMING (reverses the original authorization) | Test how you handle a reversal and the release of a hold            |

### Recommended regression order

1. **Create a usable card**: complete the card issuance flow in the sandbox first (see [Virtual card application](../cards/virtual-card)) and keep the `cardId`.
2. **Configure your callback URLs**: confirm `authUrl` and `webhookUrl` are configured and reachable (see [Webhook configuration](../webhooks/configuration)).
3. **Simulate a purchase**: send `authType=EXPEND`, approve at `authUrl`, then check that `data.approved=true` and that `webhookUrl` received the matching event.
4. **Simulate a decline**: return a decline at `authUrl`, then check `data.approved=false` and the `errorCode`.
5. **Simulate a return and a reversal**: use `REFUND` and `REVERSAL` to verify the callbacks and reconciliation on the INCOMING side.

> Simulated transactions create **real transaction and authorization records** and fire **real webhooks**, built to the same shape as production, so they are suitable for end-to-end verification as they stand. For the fields on authorization and transaction records and the structure of webhook events, see [Events and data structures](../webhooks/events-and-schema) and [Authorization and clearing scenarios](../transactions/auth-and-settlement).

***

## Scenarios with no dedicated simulation yet

The DCS sandbox currently offers a single simulation entry point, `fund-auth`, covering purchase, return and reversal. The scenarios below have **no dedicated simulation endpoint**; test against the callback structures documented for them, or ask the DCS team to help construct a case:

| Scenario                                                               | Status         | Description                                                                                                                                                                                                                          |
| ---------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Standalone clearing or settlement (settlement/capture) simulation      | Not available  | There is no standalone clearing simulation endpoint today; for clearing behavior, test against the real callback structures described in [Clearing scenarios: partial, over-clearing, multi-part](../transactions/capture-scenarios) |
| Incremental authorization (authorization update, such as adding a tip) | Not available  | No standalone entry point for incremental authorization                                                                                                                                                                              |
| Partial, over- and multi-part clearing                                 | Not available  | No standalone entry point; for the semantics see [Clearing scenarios](../transactions/capture-scenarios)                                                                                                                             |
| 3DS challenge (OTP/challenge) simulation                               | Not available  | No standalone 3DS simulation endpoint; for the 3DS forwarding mechanism see [3DS forwarding](../transactions/3ds)                                                                                                                    |
| Collateral or deposit funding simulation                               | Not applicable | Under the Partner-Managed model the limit is held by you and the authorization is decided by you, so the sandbox offers no end-user funding simulation entry point                                                                   |

> Today DCS covers the main authorization forwarding loop with a single `fund-auth` endpoint and its three `authType` values. If you need to test any of the scenarios above that lack a dedicated simulation entry point, contact the DCS team for help.

***

## Next steps

Once the simulation runs cleanly, check the posting direction of each `authType` in your own system against [Authorization and clearing scenarios](../transactions/auth-and-settlement), and complete the final regression in [Pre-go-live checks](../../customer-success/pre-go-live).