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

# Qwikcilver (Gift Cards)

> Configure Qwikcilver gift card payments in Gr4vy to accept gift cards at checkout, including balance checks and split tender.

Qwikcilver is a gift card platform that enables buyers to pay at checkout using one or more
gift cards. Gift cards can be used alone or split across a traditional payment method.

For a full overview of how gift cards work in Gr4vy, see the
[Gift cards guide](/guides/features/gift-cards/overview).

## Setup

Qwikcilver does not provide self-service sign-up. Please work with Qwikcilver
to get set up with an environment.

## Credentials

Once set up, the Qwikcilver team provides
the following information.

* The **Username** for the instance
* The **Password** for the instance
* The **Terminal ID** for the integration
* And finally the **Subdomain** of the instance. This is prefixed to the
  Qwikcilver domain name of the instance, for example `https://{subdomain}.qwikcilver.com`

These credentials can be configured in the dashboard directly when setting up a Qwikcilver
connection, or the details can be securely shared with the solution engineering team
for them to set up.

## Features

* **Balance checks** - Query the balance of one or more gift cards before checkout
* **Gift card-only payments** - Accept payments funded entirely by gift cards
* **Split tender** - Split a payment across one or more gift cards and a standard payment method
* **Stored gift cards** - Vault gift cards against a buyer for reuse
* **Automatic reversal** - Automatically revert all gift card charges if any single card fails

## Integration

### Check a gift card balance

Before processing a payment, you can check the balance of one or more gift cards.
You can query by stored gift card ID or by raw card number and PIN.

<CodeGroup>
  ```csharp C# theme={"system"}
  var res = await sdk.GiftCards.Balances.ListAsync(giftCardBalanceRequest: new GiftCardBalanceRequest() {
      Items = new List<Item>() {
          Item.CreateGiftCardRequest(
              new GiftCardRequest() {
                  Number = "4123455541234561234",
                  Pin = "1234",
              }
          ),
      },
  });

  // handle response
  ```

  ```go Go theme={"system"}
  res, err := s.GiftCards.Balances.List(ctx, components.GiftCardBalanceRequest{
      Items: []components.Item{
          components.CreateItemGiftCardRequest(
              components.GiftCardRequest{
                  Number: "4123455541234561234",
                  Pin:    "1234",
              },
          ),
      },
  })
  if err != nil {
      log.Fatal(err)
  }
  if res != nil {
      // handle response
  }
  ```

  ```java Java theme={"system"}
  ListGiftCardBalancesResponse res = sdk.giftCards().balances().list()
          .giftCardBalanceRequest(GiftCardBalanceRequest.builder()
              .items(List.of(
                  Item.of(GiftCardRequest.builder()
                      .number("4123455541234561234")
                      .pin("1234")
                      .build())))
              .build())
          .call();

  if (res.giftCardSummaries().isPresent()) {
      System.out.println(res.giftCardSummaries().get());
  }
  ```

  ```php PHP theme={"system"}
  $giftCardBalanceRequest = new Gr4vy\GiftCardBalanceRequest(
      items: [
          new Gr4vy\GiftCardRequest(
              number: '4123455541234561234',
              pin: '1234',
          ),
      ],
  );

  $response = $sdk->giftCards->balances->list(
      giftCardBalanceRequest: $giftCardBalanceRequest
  );

  if ($response->giftCardSummaries !== null) {
      // handle response
  }
  ```

  ```python Python theme={"system"}
  res = g_client.gift_cards.balances.list(items=[
      {
          "number": "4123455541234561234",
          "pin": "1234",
      },
  ])

  # Handle response
  print(res)
  ```

  ```typescript TypeScript theme={"system"}
  const result = await gr4vy.giftCards.balances.list({
    items: [
      {
        number: "4123455541234561234",
        pin: "1234",
      },
    ],
  });

  console.log(result);
  ```
</CodeGroup>

See the [balance check API reference](/reference/gift-cards/list-gift-card-balances) for the full list of request and response fields.

### Store a gift card

You can store a gift card in the vault to use it in future transactions without
re-entering the card details. Optionally, associate the card with a buyer.

<CodeGroup>
  ```csharp C# theme={"system"}
  var res = await sdk.GiftCards.CreateAsync(giftCardCreate: new GiftCardCreate() {
      Number = "4123455541234561234",
      Pin = "1234",
  });

  // handle response
  ```

  ```go Go theme={"system"}
  res, err := s.GiftCards.Create(ctx, components.GiftCardCreate{
      Number: "4123455541234561234",
      Pin:    "1234",
  })
  if err != nil {
      log.Fatal(err)
  }
  if res != nil {
      // handle response
  }
  ```

  ```java Java theme={"system"}
  CreateGiftCardResponse res = sdk.giftCards().create()
          .giftCardCreate(GiftCardCreate.builder()
              .number("4123455541234561234")
              .pin("1234")
              .build())
          .call();

  if (res.giftCard().isPresent()) {
      System.out.println(res.giftCard().get());
  }
  ```

  ```php PHP theme={"system"}
  $giftCardCreate = new Gr4vy\GiftCardCreate(
      number: '4123455541234561234',
      pin: '1234',
  );

  $response = $sdk->giftCards->create(
      giftCardCreate: $giftCardCreate
  );

  if ($response->giftCard !== null) {
      // handle response
  }
  ```

  ```python Python theme={"system"}
  res = g_client.gift_cards.create(
      number="4123455541234561234",
      pin="1234",
  )

  # Handle response
  print(res)
  ```

  ```typescript TypeScript theme={"system"}
  const result = await gr4vy.giftCards.create({
    number: "4123455541234561234",
    pin: "1234",
  });

  console.log(result);
  ```
</CodeGroup>

See the [stored gift cards API reference](/reference/gift-cards) for managing and listing vaulted gift cards.

## Reversals

In the case of multiple gift cards for a transaction, all gift cards are processed
using the Qwikcilver batch API. This means that all gift cards are attempted in parallel,
at the same time.

If any of them fail due to insufficient funds, or any other reason,
then none of the gift cards are charged, but because of the parallel nature of Qwikcilver,
each card is marked as failed, even when some of them were never attempted.

For a full description of the reversal logic across all gift card providers, see
[Reversals](/guides/features/gift-cards/overview#reversals) in the gift cards guide.

## Testing

Use the [gift card simulator](/guides/features/gift-cards/simulator) to test balance checks,
redemptions, and error codes in your sandbox environment without a live Qwikcilver connection.