> ## 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 and gift card redemptions and refunds. 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`          |

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

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