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

# Transaction simulators

Payment simulators are provided for card, PayPal, and SPEI payments, allowing you
to test card payments, redirect payments, and push payments respectively.

These simulators do not connect to any PSP and instead provide mocked responses
based on the amounts or other values passed in.

<Note>
  An [anti-fraud
  simulator](/guides/features/anti-fraud/simulator), [gift card
  simulator](/guides/features/gift-cards/simulator) and a way to [simulate
  real-time account
  updates](/guides/features/account-updater/real-time#simulator) are also provided.
</Note>

## Setup

To set up a simulator, head over to your sandbox dashboard and go to the connections catalog.
Once there, each simulator is available to set up with a custom merchant ID. This ID does
not serve any purpose.

Please note that simulators are not available in production environments.

## Test values

### Payments

When creating a payment, the following test values can be used to simulate various error codes.

| Simulator amount | `error_code` |
| :- | :- |
| 200001 | `canceled_payment_method` |
| 200002 | `disputed_transaction` |
| 200003 | `duplicate_transaction` |
| 200004 | `expired_authorization` |
| 200005 | `expired_payment_method` |
| 200006 | `incorrect_billing_address` |
| 200007 | `incorrect_country` |
| 200008 | `incorrect_currency` |
| 200009 | `incorrect_cvv` |
| 200010 | `incorrect_expiry_date` |
| 200011 | `insufficient_funds` |
| 200012 | `issuer_decline` |
| 200013 | `other_decline` |
| 200014 | `requires_buyer_authentication` |
| 200015 | `refused_transaction` |
| 200016 | `service_decline` |
| 200017 | `suspected_fraud` |
| 200018 | `unavailable_payment_method` |
| 200019 | `unknown_payment_method` |
| 200020 | `unsupported_transaction` |
| 200021 | `unsupported_payment_method` |
| 200022 | `cancelled_buyer_approval` |
| 300001 | `insufficient_service_permissions` |
| 300002 | `invalid_amount` |
| 300003 | `invalid_payment_method` |
| 300004 | `invalid_service_configuration` |
| 300005 | `invalid_service_credentials` |
| 300006 | `invalid_service_response` |
| 300007 | `invalid_tax_identifier` |
| 300008 | `missing_billing_address` |
| 300009 | `missing_cvv` |
| 300010 | `missing_shipping_address` |
| 300011 | `missing_tax_identifier` |
| 300012 | `refund_period_expired` |
| 300013 | `service_error` |
| 300014 | `service_network_error` |
| 300015 | `service_rate_limit` |
| 400001 | `internal_error` |
| 400002 | `invalid_billing_address` |
| 400003 | `invalid_operation` |
| 400004 | `invalid_request_parameters` |
| 400005 | `invalid_service_request` |
| 400006 | `invalid_shipping_address` |
| 400007 | `service_resource_conflict` |
| 400008 | `unexpected_state` |
| 400009 | `unknown_error` |
| 400010 | `unknown_service_resource` |
| 400011 | `unsupported_country` |
| 400012 | `unsupported_currency` |
| 400013 | `unrecognised_country` |
| 400014 | `unrecognised_currency` |
| 400015 | `unrecognised_payment_method` |
| 400016 | `unrecognised_scheme` |
| 400017 | `unsupported_scheme` |

The following amounts can be used to test pending outcomes:

| Simulator amount | Outcome | New transaction `status` |
| :- | :- | - |
| 408 | Connector request times out. An asynchronous retry if scheduled idempotent retries are supported. | `processing` or `authorization_failed` |
| 102 | Connector returns a pending status. | `processing` |

### 3-D Secure

The card simulator supports PSP-hosted [3-D Secure](/guides/features/3ds/overview),
where the payment service performs the authentication as part of the transaction.

To simulate an authentication outcome, include a `metadata` value in the request with `"require_three_d_secure": "true"`
and prefix the simulator amount with one of the following values:

| Prefix | Outcome | Redirect |
| :- | :- | :- |
| 90 | Challenge success | Yes |
| 91 | Frictionless success | Yes |
| 92 | Challenge failed | Yes |
| 93 | Authentication failed | Yes |
| 94 | Frictionless success | No |
| 95 | Authentication failed | No |

Prefixes `90` to `93` return a `buyer_approval_pending` transaction with a redirect URL, and the
authentication outcome is applied when the buyer returns from it. Prefixes `94` and `95` complete
the authentication as part of the create request, so the 3-D Secure data is returned in the
initial response without a redirect.

You can combine one of these prefixes with another simulator amount to control both the authentication
outcome and the payment result. For example, an amount of `90200001` returns the
challenge success data together with a `canceled_payment_method` error code.

### Captures

When capturing an authorized payment, the following responses can be simulated.

When capturing a payment, the following test values can be used to simulate various error codes.

| Simulator amount | New transaction `status` | `code` |
| :- | :- | - |
| 10 | `authorization_declined` | `issuer_decline` |
| 20 | `capture_pending` | - |
| 30 | `authorization_succeeded` | `service_error` |
| 40 | `authorization_succeeded` | `internal_error` |

Additionally, the `408` amount can be used to simulate a connector request that times out.
An asynchronous retry is scheduled if idempotent retries are supported.

<Warning>
  Transactions in a `capture_pending` state can be moved to the next state using
  [webhooks](./webhooks).
</Warning>

### Void

When voiding an authorized payment, the following responses can be simulated.

When creating a payment, the following test values can be used to simulate various error codes.

| Simulator amount | New transaction `status` | `code` |
| :- | :- | - |
| 10 | `authorization_declined` | `issuer_decline` |
| 20 | `authorization_void_pending` | - |
| 30 | `authorization_succeeded` | `service_error` |
| 40 | `authorization_succeeded` | `internal_error` |

<Warning>
  Transactions in a `authorization_void_pending` state can be moved to the next
  state using [webhooks](./webhooks).
</Warning>

### Refunds

When refunding a card payment, the following responses can be simulated.

When creating a payment, the following test values can be used to simulate various error codes.

| Simulator amount | `status` |
| :- | :- |
| 1 | `declined` |
| 2 | `processing` |
| 3 | `failed` |
| 4 | `failed` |

### Scheme transactions

When creating a card payment, random `scheme_transaction_id` and `transaction_link_id` values are generated.
An amount of 10001 can be used to simulate a missing `scheme_transaction_id` and `transaction_link_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.