Vii gift cards

Vii is a gift card platform. Connect it to StoreConnect and your customers can pay with a Vii gift card at web checkout, and staff can take Vii gift cards at the POS. The gift cards and their balances stay in Vii, so StoreConnect checks the balance and charges the card through Vii every time.

Vii gift cards are separate from StoreConnect vouchers, which you create and manage in Salesforce. A store can accept both.

Before you start

• A Vii merchant account, with an API key and API secret
• The AIIC (Acquirer Institutional Identification Code) and CATI (Card Acceptor Terminal Identification) codes that Vii issues for your business, plus a CAIC (Card Acceptor Identification Code) if Vii supplies one
• The production API URL for your account, from Vii
• If staff will refund gift card payments onto the card at the POS, refunds enabled on your Vii account. Only Vii can turn this on.

Add the Vii payment provider

:::warning Vii is missing from the Provider list on the payment provider record in the current package, so you cannot complete these steps yet. This is a known bug, and the steps work once the fix ships. :::

1. Go to the Payment Providers list.
2. Select New.

3. Complete the fields as follows.

   Field	Value
   Name	A name your team recognizes, for example Vii gift cards
   Provider	Vii
   Store	The store that accepts the gift cards
   API Mode	production. The field is required, but StoreConnect ignores it for Vii. The production_url API option sets which Vii environment StoreConnect uses.
   API Key	The API key from Vii
   API Secret	The API secret from Vii
   Channels	Include Web to accept gift cards at web checkout. See where gift cards are accepted.
   Active	Checked

4. In API Options, enter the codes and URL from Vii, one option per line.

   ```yaml

   aiic: “100012” cati: “SC000001” caic: “” production_url: “PRODUCTION_URL_FROM_VII” ```

5. Select Save.

:::warning Without production_url, every request goes to the Vii sandbox, where real gift cards are not recognized. Leave it out only while you test with the sandbox cards Vii gives you. :::

The Vii payment provider is now active for the store. If Channels includes Web, an Apply a gift card panel appears in the vouchers area at web checkout.

API options

Option	Required	Description
aiic	Yes	Acquirer Institutional Identification Code from Vii
cati	Yes	Card Acceptor Terminal Identification from Vii
caic	No	Card Acceptor Identification Code. Leave it blank if Vii has not issued one.
production_url	Yes, for live cards	The Vii production API URL. Without it, StoreConnect uses the Vii sandbox.
refunds_enabled	No	Set to true to let staff refund a Vii payment taken at the POS back onto the card. Vii must also enable refunds on your Vii account. Ask Vii to do this first, because StoreConnect cannot turn it on. If Vii has not enabled refunds, Vii declines the refund. Defaults to false.
pos_outlets	No	AIIC and CATI codes for individual outlets. See codes for individual outlets.

If the API key, API secret, aiic or cati is missing, Vii gift cards cannot be applied online, and the POS shows “Vii payment provider is not configured correctly”.

Where gift cards are accepted

Set Channels on the payment provider to choose whether customers can use Vii gift cards at web checkout:

• Web selected, or Channels left blank: the Apply a gift card panel appears at checkout.
• Only POS selected: gift cards are not offered online.

Channels has no effect at the POS. A register offers Gift Card (Vii) once the store has an active Vii payment provider and the pos.payment_options.vii.enabled store variable is true. See POS payment methods to add the store variable.

Keep one active Vii payment provider per store. The POS uses the store’s active Vii provider, and does not choose between several.

Codes for individual outlets

If Vii has issued different codes for some outlets, add them under pos_outlets, keyed by the outlet’s Salesforce ID. An outlet without an entry, or without one of the two codes, uses the top-level value. Web checkout always uses the top-level codes.

```yaml

aiic: “100012” cati: “SC000001” production_url: “PRODUCTION_URL_FROM_VII” pos_outlets: “a24ao000001lE6zAAE”: aiic: “100034” cati: “SC000002” “a24ao000001lE7aAAE”: cati: “SC000003” ```

To find an outlet’s Salesforce ID, open the Outlet record. The ID appears in the browser URL.

How customers pay with a gift card online

Vii gift cards do not appear in the list of payment methods at checkout. Customers apply them in the vouchers area, the same way they apply a StoreConnect voucher code.

1. In the Apply a gift card panel, the customer enters the card number and PIN, then selects Check.
2. The available balance appears, with an Amount to apply field filled in with the lower of the card balance and the amount payable. The customer can lower the amount to keep part of the card for later.
3. The customer selects Apply. StoreConnect checks the card with Vii again and adds it to the cart. No money moves at this point, and the customer can remove the gift card.
4. The gift card appears as a row showing the last four digits of the card and the amount applied, and the amount payable goes down by that amount.
5. The customer pays the rest with a payment method. If gift cards and vouchers cover the whole order, no payment method is needed.
6. When the customer places the order, StoreConnect charges the gift card through Vii.

For example, a customer with a $50 gift card buys $120 of products. They apply the full $50, and pay the remaining $70 by credit card.

A customer can apply more than one gift card to an order. Applying the same card again replaces the amount applied, rather than adding the card twice. Gift cards cannot pay for subscription products, so the amount payable by gift card excludes them.

To protect gift cards from guessing, StoreConnect limits balance checks. By default, one IP address can make 10 balance checks a minute, and one card can be checked 5 times an hour. Customers on the same network, such as an office or a shop Wi-Fi, share the per-address limit. Applying a gift card or voucher counts toward the same per-address limit as a balance check. A customer who reaches a limit waits before trying again.

Customers can also apply a gift card when they pay an order’s balance through a payment link, except on a subscription renewal order. See Use vouchers on an order’s payment page.

The Apply a gift card panel is part of the default checkout theme. If your theme overrides the checkout vouchers area, see the apply provider voucher form to add it.

When a gift card charge fails after the order is placed

StoreConnect charges gift cards last, after every other payment on the order, because Vii cannot reliably reverse a charge.

• If the customer’s card payment fails, checkout stops and the gift card is not charged.
• If the other payments succeed and the gift card charge then fails, the order still completes. The gift card amount stays owing on the order. For example, the charge fails if the card was spent elsewhere after the customer applied it.

To check whether a gift card was charged:

1. Open the Order record.
2. Go to the Payments related list.
3. Look for a payment with Method VII. A charged gift card has one, with the Vii transaction ID in Transaction Number.
4. If there is no VII payment for the gift card, collect the amount owing another way, for example with a payment link.

StoreConnect does not reverse a gift card charge made at web checkout, and staff cannot refund it onto the card at the POS. A POS refund onto a Vii gift card applies only to a gift card payment taken at the POS, and only when Vii has enabled refunds on your Vii account and refunds_enabled is true. See refunds at the POS.