--- title: "Vii gift cards" source: https://support.storeconnect.com/articles/vii-payment-provider type: article format: markdown site: StoreConnect Support — product and developer documentation for StoreConnect site_index: https://storeconnect.com/llms.txt docs_index: https://support.storeconnect.com/llms.txt note: Append .md to any page or article URL on this site to get its Markdown form. --- # 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](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](#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](#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](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](managing-and-spending-vouchers#use-vouchers-on-an-orders-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](apply-provider-voucher-form-reference) 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](salesforce-order-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](returns-refund-exchange-at-pos). --- ## Follow StoreConnect - [Email Newsletter](https://storeconnect.com/c/lp-newsletter) - [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464) - [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g) - [LinkedIn](https://www.linkedin.com/company/storeconnect) - [X / Twitter](https://x.com/storeconnecthq) ## Popular Links - [Partners](https://storeconnect.com/partners) - [Become a Partner](https://storeconnect.com/become-a-partner) - [News](https://storeconnect.com/articles/news) - [Events](https://storeconnect.com/articles/events) - [Feature Comparison](https://storeconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://storeconnect.com/contact) ## Documentation - [Help documentation](https://support.storeconnect.com/help-documentation) - [AI agents](https://support.storeconnect.com/ai) - [Videos & tutorials](https://support.storeconnect.com/videos-tutorials) - [Developer reference](https://support.storeconnect.com/developer-reference) - [Release notes](https://support.storeconnect.com/release-notes) - [Troubleshooting](https://support.storeconnect.com/troubleshooting) - [Trust Center](https://trust.getstoreconnect.com/) - [Status Page](https://status.storeconnect.com/) ## Contact - info@getstoreconnect.com - US +1 415 745 3230 - AUS +61 2 8365 2308 100 S Ashley Dr, Suite 600-2461 Tampa FL 33602-600 USA Level 22, Sydney Place 180 George Street Sydney, NSW, 2000, AUS ## Machine-readable - [Site index for agents](https://storeconnect.com/llms.txt): curated map of the StoreConnect site in llms.txt format - [Documentation index for agents](https://support.storeconnect.com/llms.txt): full technical and product documentation map Every page and article on this site has a Markdown rendering: append `.md` to its URL. Continue in Markdown: [Help documentation](https://support.storeconnect.com/help-documentation.md) · [Developer reference](https://support.storeconnect.com/developer-reference.md) · [Videos & tutorials](https://support.storeconnect.com/videos-tutorials.md) · [Release notes](https://support.storeconnect.com/release-notes.md) --- StoreConnect Support — https://support.storeconnect.com/articles/vii-payment-provider