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

# Simulate transaction events

> How to create transaction events in sandbox environment

For testing purposes, Imprint's sandbox environment is not connected to card networks. This means that the sandbox environment does not receive or process real transaction messages.

Imprint offers a [sandbox endpoint to simulate transaction events](https://docs.imprint.co/api-reference/simulate-transaction-event/simulate-transaction-event-in-sandbox-environment) as though they came through the network (e.g., related to a specific payment method, merchant, etc.). Simulated transactions trigger Imprint's systems, such as transaction event notifications, transaction-based rewards, etc. - so it is a very helpful mirror of the Imprint production environment. 

Below, we have detailed how to simulate different [common transaction scenarios](https://docs.imprint.co/guide-event-notifications#common-transaction-scenarios):

## Simulate an `APPROVED` transaction 

* In the request, do not include a `transaction_id` value. The endpoint will create a new `APPROVED` transaction and return the corresponding `transaction_id `and `event_id`

<CodeGroup>
  ```json REQUEST theme={null}
  {
    "transaction_id": "",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
    "status": "APPROVED",
    "amount": 5000,
    "currency": "USD",
    "authorization_code": "645432",
    "network_transaction_id": "txn-789456",
    "purchase_method": "CHIP",
    "merchant": {
      "network_id": "234923454545",
      "name": "Target",
      "category": "Grocery Stores",
      "category_code": "5411",
      "address": {
        "city": "New York",
        "country": "USA",
        "postal_code": "10002",
        "state": "NY",
        "street_line1": "",
        "street_line2": ""
      }
    }
  }
  ```

  ```json RESPONSE theme={null}
  {
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "event_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "status": "APPROVED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATION theme={null}
  {
    "object": "TRANSACTION",
    "data": {
      "amount": 5000,
      "authorization_code": "645432",
      "created_at": "2025-02-27T18:11:32.358Z",
      "currency": "USD",
      "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
      "event_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "merchant": {
        "address": {
          "city": "New York",
          "country": "USA",
          "postal_code": "10002",
          "state": "NY",
          "street_line1": "",
          "street_line2": ""
        },
        "category": "Grocery Stores",
        "category_code": "5411",
        "network_id": "234923454545",
        "name": "Target"
      },
      "network_transaction_id": "txn-789456",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "purchase_method": "CHIP",
      "status": "APPROVED",
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496"
    }
  }
  ```
</CodeGroup>

## Simulate a `VOIDED` transaction

* You can void an `APPROVED` transaction

* The example voids an approved authorization.

<CodeGroup>
  ```json REQUEST theme={null}
  {
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "status": "VOIDED"
  }
  ```

  ```json RESPONSE theme={null}
  {
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "event_id": "47c7cbfd-ef76-48e7-98fd-4a5bb3e2a82e",
    "status": "CAPTURED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATION theme={null}
  {
    "object": "TRANSACTION",
    "data": {
      "amount": 400,
      "authorization_code": "645432",
      "created_at": "2025-02-27T18:11:32.358Z",
      "currency": "USD",
      "event_id": "47c7cbfd-ef76-48e7-98fd-4a5bb3e2a82e",
      "merchant": {
        "address": {
          "city": "New York",
          "country": "USA",
          "postal_code": "10002",
          "state": "NY",
          "street_line1": "",
          "street_line2": ""
        },
        "category": "Grocery Stores",
        "category_code": "5411",
        "network_id": "234923454545",
        "name": "Target"
      },
      "network_transaction_id": "txn-789456",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "purchase_method": "CHIP",
      "status": "VOIDED",
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "updated_at": "2025-02-30T12:00:00.000Z"
    }
  }
  ```
</CodeGroup>

## Simulate an `UPDATED` transaction

* The request must include an existing `transaction_id` that will be updated

* Below, the example updates an `APPROVED` transaction amount from \$50.00 to \$35.46

<CodeGroup>
  ```json REQUEST theme={null}
  {
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "status": "UPDATED",
    "amount": 3456
  }
  ```

  ```json RESPONSE theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "event_id": "cc1b6144-27bd-4b77-8c5c-e48977abe9a4",
      "status": "UPDATED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATION theme={null}
  {
    "object": "TRANSACTION",
    "data": {
      "amount": 3456,
      "authorization_code": "645432",
      "created_at": "2025-02-27T18:11:32.358Z",
      "currency": "USD",
      "event_id": "cc1b6144-27bd-4b77-8c5c-e48977abe9a4",
      "merchant": {
        "address": {
          "city": "New York",
          "country": "USA",
          "postal_code": "10002",
          "state": "NY",
          "street_line1": "",
          "street_line2": ""
        },
        "category": "Grocery Stores",
        "category_code": "5411",
        "network_id": "234923454545",
        "name": "Target"
      },
      "network_transaction_id": "txn-789456",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "purchase_method": "CHIP",
      "status": "UPDATED",
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "updated_at": "2025-02-28T12:00:00.000Z"
    }
  }
  ```
</CodeGroup>

## Simulate a `CAPTURED` transaction

* In the request, you can create one or multiple captures against the same `transaction_id` in `APPROVED` or `UPDATED` status.

* The example creates a \$4 capture linked to a previous \$4 approved authorization.

<CodeGroup>
  ```json REQUEST theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
      "status": "CAPTURED",
      "amount": 400
  }
  ```

  ```json RESPONSE theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "event_id": "47c7cbfd-ef76-48e7-98fd-4a5bb3e2a82e",
      "status": "CAPTURED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATION theme={null}
  {
      "object": "TRANSACTION",
      "data": {
          "amount": 400,
          "authorization_code": "645432",
          "created_at": "2025-02-27T18:11:32.358Z",
          "currency": "USD",
          "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
          "event_id": "47c7cbfd-ef76-48e7-98fd-4a5bb3e2a82e",
          "merchant": {
              "address": {
                  "city": "New York",
                  "country": "USA",
                  "postal_code": "10002",
                  "state": "NY",
                  "street_line1": "",
                  "street_line2": ""
              },
              "category": "Grocery Stores",
              "category_code": "5411",
              "network_id": "234923454545",
              "name": "Target"
          },
          "network_transaction_id": "txn-789456",
          "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
          "purchase_method": "CHIP",
          "status": "CAPTURED",
          "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
          "updated_at": "2025-02-30T12:00:00.000Z"
      }
  }
  ```
</CodeGroup>

* Alternatively, you can create a standalone capture (e.g., "force capture") by omitting `transaction_id` from the request.

* The example creates a standalone \$4 capture.

<CodeGroup>
  ```javascript REQUEST theme={null}
  {
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "transaction_id": "",
      "amount": 400,
      "status": "CAPTURED"
  }
  ```

  ```json RESPONSE theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "event_id": "57d8cbfd-ef76-48e7-98fd-1a5cc3e2a82e",
      "status": "CAPTURED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATION theme={null}
  {
    "object": "TRANSACTION",
    "data": {
      "amount": 400,
      "authorization_code": "645432",
      "created_at": "2025-02-27T18:11:32.358Z",
      "currency": "USD",
      "event_id": "57d8cbfd-ef76-48e7-98fd-1a5cc3e2a82e",
      "merchant": {
        "address": {
          "city": "New York",
          "country": "USA",
          "postal_code": "10002",
          "state": "NY",
          "street_line1": "",
          "street_line2": ""
        },
        "category": "Grocery Stores",
        "category_code": "5411",
        "network_id": "234923454545",
        "name": "Target"
      },
      "network_transaction_id": "txn-789456",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "purchase_method": "CHIP",
      "status": "CAPTURED",
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "updated_at": "2025-02-30T12:00:00.000Z"
    }
  }
  ```
</CodeGroup>

## Simulate a `REFUNDED` transaction&#x20;

* In the request, you can create one or multiple refunds against the same transaction in `CAPTURED` status. You will need to provide the `event_id` of the related capture. The API will return an error if the refunded amount exceeds the captured amount for the transaction.

* The example creates a \$4 refund linked to a previous \$4 capture.

<CodeGroup>
  ```json REQUEST theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "event_id": "57d8cbfd-ef76-48e7-98fd-1a5cc3e2a82e",
      "amount": 400,
      "status": "REFUNDED"
  }
  ```

  ```json RESPONSE theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "event_id": "c2f3f849-5ee0-46b3-8caa-70016a014126",
      "status": "REFUNDED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATIONS theme={null}
  {
      "object": "TRANSACTION",
      "data": {
          "amount": 400,
          "authorization_code": "645432",
          "created_at": "2025-02-27T18:11:32.358Z",
          "currency": "USD",
          "event_id": "c2f3f849-5ee0-46b3-8caa-70016a014126",
          "merchant": {
              "address": {
                  "city": "New York",
                  "country": "USA",
                  "postal_code": "10002",
                  "state": "NY",
                  "street_line1": "",
                  "street_line2": ""
              },
              "category": "Grocery Stores",
              "category_code": "5411",
              "network_id": "234923454545",
              "name": "Target"
          },
          "network_transaction_id": "txn-789456",
          "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
          "purchase_method": "CHIP",
          "status": "REFUNDED",
          "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
          "updated_at": "2025-03-01T12:00:00.000Z"
      }
  }
  ```
</CodeGroup>

* Alternatively, you can create a standalone refund (e.g., "blind return") by omitting `transaction_id` from the request.&#x20;

* The example creates a standalone \$5 refund.

<CodeGroup>
  ```json REQUEST theme={null}
  {
      "transaction_id": "",
      "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
      "status": "REFUNDED",
      "amount": 5000,
      "currency": "USD",
      "authorization_code": "645432",
      "network_transaction_id": "txn-789456",
      "purchase_method": "CHIP",
      "merchant": {
          "network_id": "234923454545",
          "name": "Target",
          "category": "Grocery Stores",
          "category_code": "5411",
          "address": {
              "city": "New York",
              "country": "USA",
              "postal_code": "10002",
              "state": "NY",
              "street_line1": "",
              "street_line2": ""
          }
      }
  }
  ```

  ```json RESPONSE theme={null}
  {
      "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "event_id": "e2806932-5f1b-4518-8b15-156d773e9496",
      "status": "REFUNDED"
  }
  ```

  ```json TRANSACTION EVENT NOTIFICATION theme={null}
  {
      "object": "TRANSACTION",
      "data": {
          "amount": 5000,
          "authorization_code": "645432",
          "created_at": "2025-02-27T18:11:32.358Z",
          "currency": "USD",
          "event_id": "e2806932-5f1b-4518-8b15-156d773e9496",
          "merchant": {
              "address": {
                  "city": "New York",
                  "country": "USA",
                  "postal_code": "10002",
                  "state": "NY",
                  "street_line1": "",
                  "street_line2": ""
              },
              "category": "Grocery Stores",
              "category_code": "5411",
              "network_id": "234923454545",
              "name": "Target"
          },
          "network_transaction_id": "txn-789456",
          "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
          "purchase_method": "CHIP",
          "status": "REFUNDED",
          "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496"
      }
  }
  ```
</CodeGroup>