# Simulate Issuing transactions

You can simulate different [transaction flows](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions.md) for an issued card in the sandbox environment before going live.
This enables you to test transactions without making a real purchase to check the merchant and card scheme experience.

Your sandbox Issuing balance is updated to demonstrate the impact on your total sandbox balance.

---

## Before you start

- You need a Checkout.com [test account](https://www.checkout.com/get-test-account) with Issuing enabled.
- You must set up [OAuth 2.0 authentication](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/oauth-2-0-client-credentials.md) to authenticate your API requests.
- [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) to receive [webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Issuing) for the various Issuing events.
- [Create a test cardholder](https://www.checkout.com/docs/card-issuing/create-and-manage-cardholders.md#Create_a_cardholder) in the sandbox.
- [Issue a test card](https://www.checkout.com/docs/card-issuing/issue-a-card.md) to the cardholder and make note of the card ID. This must be a single-use, virtual card that is activated on creation.

---

## How it works

You can test successful and declined transactions and the webhooks for different events.

In the Dashboard, you can simulate transactions and add events.

Using the API, you can simulate:

- Authorization and pre-authorizations
- Incremental authorizations
- Clearings
- Reversals
- Refunds

---

## Simulate transactions in the Dashboard

1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. If simulating a transaction:
    - Using a card, go to _Issuing_ > _Cards_, and then select the card you want to test with.
    - From the transactions list, go to _Issuing_ > _Transactions_. For this, you require a card ID.
3. Select _Simulate transaction_.
4. In the _Simulate transaction_ window > _Authorization type_ dropdown, if the final transaction amount is:
    - Estimated – Select `Pre_authorization`.
    - Known – Select `Authorization`.
5. In the _Amount_ box, provide the pre-authorization or authorization amount.
6. Optionally, provide the [merchant category code](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes.md).
7. Select _Simulate_.

Next, you can add events in the transaction journey:

1. Go to _Issuing_ > _Transactions_, and select the transaction you want to add events to.
2. On the _Transaction details_ page, select _Simulate event_.
3. Select the event type. This can be one of:
    - `Incremental authorization`
    - `Reversal`
    - `Clearing`
    - `Refund`
4. Provide the amount for the event type.
5. Select _Simulate_.

---

## Simulate an authorization or pre-authorization

Call the [Simulate authorization](https://api-reference.checkout.com/tag/Card-testing/#operation/simulateAuthorization) endpoint:

- `card.id` field – Provide the card ID from the `Create a card` response, and optionally the expiry information.
- `transaction` object:
  - `type` field – Set to `purchase`.
  - Optionally, provide the `amount`, `currency`, and `merchant.category_code`.
- `authorization_type` field – If the final transaction amount is:
  - Estimated – Set to `pre_authorization`.
  - Known – Set to `authorization`, or do not include this field.

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/simulate/authorizations`

### Request example

```json
{
  "card": {
    "id": "crd_fa6psq242dcd6fdn5gifcq1491",
    "expiry_month": 5,
    "expiry_year": 2025
  },
  "transaction": {
    "type": "purchase",
    "amount": 2500,
    "currency": "GBP",
    "authorization_type": "pre_authorization"
  }
}
```

If you’ve configured the [authorization relay](https://www.checkout.com/docs/card-issuing/manage-issuing-transactions/relay-authorization-requests.md) service, you receive an authorization request to approve or decline.
When the authorization request is processed, you receive an [Authorization approved](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authorization_approved.md) or [Authorization declined](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authorization_declined.md) webhook.

### Response example

```json
{
  "id": "trx_3vs4p7sagwlu3ejw7gkrssj2s4",
  "status": "Authorized"
}
```

A successful response returns the transaction `id`. You need this to simulate clearing the authorization.

The `status` can be one of the following:

- `Authorized` – The authorization was successful.
- `Declined` – The authorization was not successful – For example, due to insufficient [funds in your Issuing balance](https://www.checkout.com/docs/card-issuing/fund-your-issuing-balance.md), or [spending controls](https://www.checkout.com/docs/card-issuing/manage-controls.md) configured in your account.

> **Information**
>
> Single-use cards are automatically revoked after a single successful authorization.

---

## Simulate an incremental authorization

To simulate an incremental authorization:

1. [Simulate a pre-authorization request](#Simulate_an_authorization_or_pre-authorization).

2. Call the [Simulate incrementing an authorization](https://api-reference.checkout.com/tag/Card-testing/#operation/simulateIncrementalAuthorization) endpoint, and provide the transaction ID received in the pre-authorization response as the `{id}` path parameter.

In the request body, optionally provide the `amount` to increase the pre-authorization by in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md) of the transaction currency.

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/authorizations`

### Request example

```json
{
  "amount": 3500
}
```

If you’ve configured the authorization relay service, you receive an authorization request to approve or decline.
When the authorization request is processed, you receive an [Authorization approved](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authorization_approved.md) or [Authorization declined](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authorization_declined.md) webhook.

### Response example

```json
{
  "status": "Authorized"
}
```

A successful response returns the transaction `status`. This can be one of the following:

- `Authorized` – The authorization was successful.
- `Declined` – The authorization was not successful – For example, because the card is invalid or expired, or the cardholder has exceeded the spending limit.

---

## Simulate a clearing

To simulate clearing a successful authorization, call the [Simulate clearing](https://api-reference.checkout.com/tag/Card-testing/#operation/simulatePresentment) endpoint, and provide the transaction ID as the `{id}` path parameter.

Optionally, provide the `amount` to clear in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md) of the transaction currency. <br>
If the presentment amount is lower than the previously authorized amount, only the specified part of the authorized amount is cleared.
If not provided, the full authorization amount is cleared.

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/presentments`

### Request example

```json
{
  "amount": 2500
}
```

If the clearing is successful, you receive a `202` response code.

When an authorization is cleared, you receive a [Presentment received](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/presentment_received.md) webhook containing a `clearing_type` field.
This field indicates if your Issuing balance will be credited or debited.

The transaction status is updated in the Dashboard. To view the transaction timeline:

1. Sign in to the [Dashboard](https://dashboard.sandbox.checkout.com/login).
2. Go to _Issuing_ > _Transactions_, and select the transaction to view the _Transaction details_ page.

> **Information**
>
> Clearing times in the sandbox environment are different to the production environment due to acquirer and card scheme cut-off times.

---

## Simulate a reversal

To simulate reversing a previous authorization, call the [Simulate reversal](https://api-reference.checkout.com/tag/Card-testing/#operation/simulateReversal) endpoint:

- Provide the transaction ID as the `{id}` path parameter.
- Optionally, provide the `amount` to reverse in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md) of the transaction currency. <br>
If the reversal amount is lower than the previously authorized amount, only the specified part of the authorized amount is reversed. If not provided, the full authorization amount is reversed.

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/reversals`

### Request example

```json
{
  "amount": 2500
}
```

### Response example

```json
{
  "status": "Reversed"
}
```

A successful response returns the transaction `status`. This can be one of the following:

- `Reversed` – The reversal was successful.
- `Declined` – The reversal was not successful – For example, because the reversal amount is greater than the previously authorized amount, or if the authorization has already been cleared.

---

## Simulate a refund

To simulate a refund of a previous authorization:

1. [Simulate an authorization request](#Simulate_an_authorization_or_pre-authorization).
2. [Simulate clearing the authorization](#Simulate_a_clearing).
3. Call the [Simulate refund](https://api-reference.checkout.com/tag/Card-testing/#operation/simulateRefund) endpoint:

- Provide the transaction ID as the `{id}` path parameter.
- Optionally, provide the `amount` to refund in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md) of the transaction currency. <br>
If the refund amount is lower than the previously cleared amount, only the specified part of the cleared amount is refunded.
If not provided, the full cleared amount is refunded.

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/refunds`

### Request example

```json
{
  "amount": 2500
}
```

### Response example

If the refund is successful, you receive a `202` response code.