> ## Documentation Index
> Fetch the complete documentation index at: https://gnosispay-feat-v2-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate Card Transactions

> Simulate card transactions for testing purposes as part of the sandbox environment

<Note>
  New to the sandbox environment? Read [Sandbox vs Production](/guides/configuring-environment) to understand more about sandbox environment.
</Note>

## Card Transaction Simulator

The Card Transaction Simulator allows you to test full card transaction lifecycles in the sandbox environment, without sending transactions to the live card network.

When you send a transaction request:

1. The simulator authenticates the request
2. It checks available balance
3. It applies lifecycle logic:
   * **Authorization** creates a hold
   * **Reversal** releases a hold
   * **Replacement** adjusts an existing hold
   * **Clearing** confirms/settles a transaction
   * **Clearing Cancellation** cancels via clearing
4. It returns an approval or denial response with production-like fields

```
https://core.sandbox.gnosispay.in/docs/simulator-api
```

## How to Simulate a Card Transaction

<Steps>
  <Step title="Authenticate with the Simulator API">
    Use HTTP Basic Auth:

    * **Username:** `simulator`
    * **Password:** Provided during onboarding

    All simulator endpoints require authentication.
  </Step>

  <Step title="Choose the Card Identifier">
    You can simulate transactions using:

    * `card_id` → `POST /transactions/simulate`
    * `pan` → `POST /transactions/simulate-by-pan`

    Both endpoints behave identically.
  </Step>

  <Step title="Understand Request Fields">
    All simulation requests use these fields:

    | Field                | Type   | Required    | Description                                                                        |
    | -------------------- | ------ | ----------- | ---------------------------------------------------------------------------------- |
    | `transaction_type`   | string | Yes         | `authorization`, `reversal`, `replacement`, `clearing`, or `clearing_cancellation` |
    | `card_id`            | uuid   | Yes\*       | Card UUID (use `pan` instead on the by-PAN endpoint)                               |
    | `pan`                | string | Yes\*       | Card PAN (only on the by-PAN endpoint)                                             |
    | `amount`             | string | Yes         | Amount in major units (e.g., `"100.50"`)                                           |
    | `currency`           | string | Yes         | `USD`, `EUR`, or `GBP`                                                             |
    | `authorization_code` | string | Conditional | Required for `reversal`, `replacement`, `clearing`, and `clearing_cancellation`    |
    | `replacement_amount` | string | Conditional | Required for `replacement`                                                         |
    | `merchant_name`      | string | No          | Defaults to `"TEST MERCHANT"`                                                      |
    | `merchant_code`      | string | No          | MCC code. Defaults to `"5541"`                                                     |
  </Step>
</Steps>

## Transaction Types

The simulator supports five transaction types that form a complete lifecycle: **authorization**, **reversal**, **replacement**, **clearing**, and **clearing cancellation**.

### Simulate an Authorization

Authorization creates an initial hold on the card balance.

<Steps>
  <Step title="Send Authorization Request">
    ```json theme={null}
    {
      "transaction_type": "authorization",
      "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.50",
      "currency": "USD"
    }
    ```

    **Required:** `transaction_type`, `amount`, `currency`, and `card_id` or `pan`.
  </Step>

  <Step title="Simulator Validation">
    The simulator will:

    * Confirm the card exists
    * Verify the card is active
    * Check sufficient available balance
    * Place a hold for the requested amount
  </Step>

  <Step title="Store Authorization Code">
    If approved, the response includes `authorization_code` and `authorization_id`.

    <Warning>
      **Save the `authorization_code`** as it's required for reversals, replacements, and clearing operations.
    </Warning>
  </Step>
</Steps>

### Simulate a Reversal

Reversal cancels a previous authorization entirely and releases the held amount.

<Steps>
  <Step title="Provide Authorization Code">
    You must use the `authorization_code` returned from the original authorization.
  </Step>

  <Step title="Send Reversal Request">
    ```json theme={null}
    {
      "transaction_type": "reversal",
      "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.50",
      "currency": "USD",
      "authorization_code": "ABC123"
    }
    ```
  </Step>

  <Step title="Simulator Behavior">
    The simulator will:

    * Validate the original authorization exists
    * Confirm the amount matches
    * Release the full held balance
  </Step>
</Steps>

### Simulate a Replacement

Replacement adjusts a previous authorization to a different amount.

<Steps>
  <Step title="Provide Authorization Code">
    Use the `authorization_code` from the original authorization.
  </Step>

  <Step title="Send Replacement Request">
    ```json theme={null}
    {
      "transaction_type": "replacement",
      "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.50",
      "currency": "USD",
      "authorization_code": "ABC123",
      "replacement_amount": "75.00"
    }
    ```

    **Required:** `authorization_code` and `replacement_amount`.
  </Step>

  <Step title="Simulator Behavior">
    The simulator will:

    * Validate the original authorization
    * Reduce or increase the held amount
    * Update the balance accordingly
  </Step>
</Steps>

### Simulate a Clearing

Clearing confirms a previous authorization (settlement/Base II) and finalizes the transaction.

<Steps>
  <Step title="Provide Authorization Code">
    Use the `authorization_code` from the original authorization.
  </Step>

  <Step title="Send Clearing Request">
    ```json theme={null}
    {
      "transaction_type": "clearing",
      "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.50",
      "currency": "USD",
      "authorization_code": "ABC123"
    }
    ```
  </Step>

  <Step title="Simulator Behavior">
    The simulator will:

    * Validate the original authorization
    * Process the settlement
    * Finalize the transaction

    <Warning>
      The simulator requires a minimum 2-minute gap between clearing messages for the same authorization. Sending a second clearing before this window elapses will result in a `409` error.
    </Warning>
  </Step>
</Steps>

### Simulate a Clearing Cancellation

Clearing cancellation cancels a transaction via clearing. For partial cancellation, send an amount lower than the original authorization.

<Steps>
  <Step title="Provide Authorization Code">
    Use the `authorization_code` from the original authorization.
  </Step>

  <Step title="Send Clearing Cancellation Request">
    ```json theme={null}
    {
      "transaction_type": "clearing_cancellation",
      "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.50",
      "currency": "USD",
      "authorization_code": "ABC123"
    }
    ```
  </Step>

  <Step title="Simulator Behavior">
    The simulator will:

    * Validate the original authorization
    * Process the cancellation
    * Adjust balances accordingly

    <Note>
      For partial cancellations, use an amount lower than the original authorization amount.
    </Note>
  </Step>
</Steps>

## Response Handling

### Approved (Authorization)

An approved authorization response includes full transaction details:

```json theme={null}
{
  "status": "approved",
  "authorization_code": "ABC123",
  "authorization_id": 98765432,
  "authorization_date_time": "2025-06-15T14:30:00Z",
  "settlement_amount": "100.50",
  "mode_type": "DEBIT",
  "card_mode": "CHIP",
  "is_domestic_transaction": true
}
```

### Approved (Clearing / Clearing Cancellation)

Clearing responses are sparse as most fields will be empty or zero-valued:

```json theme={null}
{
  "status": "approved",
  "authorization_code": "",
  "authorization_id": 0,
  "authorization_date_time": "0001-01-01T00:00:00Z",
  "settlement_amount": "",
  "mode_type": "",
  "card_mode": "",
  "is_domestic_transaction": false
}
```

### Denied

If denied, the response includes detailed denial information:

```json theme={null}
{
  "status": "denied",
  "authorization_code": "",
  "authorization_id": 98765432,
  "authorization_date_time": "2025-06-15T14:30:00Z",
  "settlement_amount": "0.00",
  "mode_type": "DEBIT",
  "card_mode": "CHIP",
  "is_domestic_transaction": true,
  "denial_code": "810",
  "denial_reason": "Insufficient balance"
}
```

<Note>
  `denial_code` and `denial_reason` use the same codes documented in [Card Decline Reasons](/concepts/card/decline-codes), use the simulator to test the responses and showcase the right mapping according to the guide.
</Note>

## Error Handling

Validation and authentication errors return structured error objects:

```json theme={null}
{
  "code": 400,
  "message": "authorization_code is required for reversal, replacement, and clearing transactions"
}
```

**Possible HTTP status codes:**

| Status | Cause                                                                                                                                        |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Invalid credentials                                                                                                                          |
| `400`  | Validation error (missing fields, invalid amount/currency)                                                                                   |
| `404`  | Card or account not found                                                                                                                    |
| `409`  | Clearing collision — a clearing message is already being processed for this authorization. Wait at least 2 minutes between clearing messages |