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

# Gift card simulator

The gift card simulator is a sandbox-only connector that can be used to simulate
responses for balance checks, gift card redemptions and refunds, and
[issuing](/reference/gift-cards/issue-gift-card) and [activating](/reference/gift-cards/activate-gift-card)
gift cards. The values for the `error_code`, `balance` and `expiration_date` can be simulated by
passing in different pin and gift card numbers. This can be used when testing your integration.

## Credentials

To configure the connection, you need to set the following credentials.

| Credential | Description |
| - | - |
| API Key | This is not validated and can be set to any string |

## Error codes

The `pin` field is used to simulate error codes:

* Starts with `0`: Reserved for successful responses. Example: `01000`.
* Starts with `1`: Validation error returned by the provider, `error_code` populated as explained below. Example `10001`.
* Starts with `2`: Server error, `error_code` populated as explained below. Example: `20010`.
* Starts with `3`: Client error, `error_code` populated as explained below. Example: `30003`.

The rest of digits of the `pin` number are used to determine the `error_code`:

| `error_code` | Description | PIN last digits |
| :- | :- | :- |
| `invalid_gift_card` | Gift card details are invalid, for example number or pin. | `0000` |
| `expired_card` | Gift card expired. | `0001` |
| `inactive_card` | Gift card is inactive. | `0002` |
| `invalid_service_credentials` | Service credentials are not valid. | `0003` |
| `invalid_amount` | Amount is invalid. | `0004` |
| `incorrect_currency` | Currency was rejected by service. | `0005` |
| `insufficient_funds` | Amount exceeds available balance. | `0006` |
| `invalid_service_configuration` | Service is incorrectly configured. | `0007` |
| `operation_canceled` | Operation was canceled as part of the batch. | `0008` |
| `service_error` | Internal server error or upstream processing error. | `0009` |
| `service_network_error` | Service was unreachable or experienced a timeout. | `0010` |
| `unknown_error` | Mapping to a more specific error code failed. | `0011` |
| `max_gift_cards_reached` | Buyer reached the maximum number of stored gift cards. | `0012` |
| `suspected_fraud` | Service flagged the transaction as suspected fraud. | `0013` |
| `canceled_payment_method` | Gift card reported lost, stolen, or otherwise canceled. | `0014` |
| `duplicate_transaction` | Transaction is a duplicate of a previous transaction. | `0015` |
| `unexpected_state` | Service or account is in an unexpected state. | `0016` |

Any other value is mapped to `unknown_error` too.

## Refunds

Similar logic is applied to trigger error cases for refunds, but the last digit of the refund amount is used, rather than the PIN.

* Ends with `0`: Reserved for successful responses. Example: `1000`.
* Ends with `1`: Validation error returned by the provider. Example `1001`.
* Ends with `2`: Server error. Example: `1002`.
* Ends with `3`: Client error. Example: `1003`.

## Balance

For endpoints returning the gift card balance, its value is the `pin` number as an integer.
The recommendation is that it starts with `0`, so it's always considered a successful response.

For example, a PIN of `01234` results in a gift card balance of `12.34`.

## Activation

[Activating](/reference/gift-cards/activate-gift-card) a gift card uses the `pin` to simulate
errors, and the `error_code` is taken from the remaining digits as described in the error codes
section. The prefixes differ slightly from a balance check.

* Omit the `pin`: successful activation.
* Starts with `1`: Client error. Example: `10001`.
* Starts with `2`: Server error. Example: `20010`.
* Starts with `3`: Client error. Example: `30003`.
* Starts with `4`: Validation error returned by the provider. Example: `40006`.

On a successful activation, the resulting balance is the `amount` you send. Omit the amount and
the balance is derived from the `pin` exactly as described in the [Balance](#balance) section.

## Issuance

[Issuing](/reference/gift-cards/issue-gift-card) a virtual gift card has no `pin` or `number` to
simulate errors with, so the `amount` is used instead. The last digit selects the type of error and
the remaining digits determine the `error_code`.

* Ends with `0`: Reserved for successful responses. Example: `5000`.
* Ends with `1`: Client error. Example: `10001`.
* Ends with `2`: Server error. Example: `10002`.
* Ends with `3`: Client error. Example: `10003`.
* Ends with `4`: Validation error returned by the provider. Example: `10004`.

## Expiration date

For endpoints returning the expiration date, the gift card `number` is considered.

* A gift card number that starts with `0` results in an expiration date in the past. For example: `0000444455556666` results in an expiration date set in the past. Currently, this is set to a month in the past, but this behavior may change.
* A gift card number that starts with `1` results in an expiration date in the future. For example: `1000444455556666` results in an expiration date set in the future. Currently, this is set to a month in the future, but this behavior may change.
* Otherwise, any other gift card has no expiration date. For example: `9000444455556666` results in a gift card without an expiration date.


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