Skip to main content

​
What is it?

The Vii connected app lets your workflows create and load Vii digital gift cards, for example for prize winners. It adds an Issue Vii card workflow step. The step saves a link to each new card in a workflow variable, so you can send it to the contact in an email or SMS.
Vii is only available on certain Komo plans. You also need a Vii gift card program. Vii gives you the API username, password and endpoint URL, plus the Store ID, BIN and card design code used in the workflow step. Ask Vii for a digital card design, which returns a link to the card.

​
How do I set it up?

​
Step 1: Connect Vii

  • Click the Workspace initials in the top right corner, then click Company Settings.
  • Click Connected Apps in the left-hand menu.
  • Click Connect on Vii.
  • Enter the Username, Endpoint (your Vii endpoint URL) and Password from Vii.
  • Click Connect.
Update Vii connection window with Username, Endpoint and a masked Password The connection applies to every workspace in your company. To change the credentials, click Update on the Vii tile. To remove the connection, click Disconnect.

​
Step 2: Build your workflow

  • Create a workflow at the card, hub or workspace level. See Workflows.
  • Set the trigger. For prize winners, use Prize Awarded and filter to your gift card prize.
  • Search the Steps panel for Vii, drag in Issue Vii card and connect it to the trigger. It’s in the Cards and Coupons group.
  • Click the pencil icon on the step and fill in the fields below.
The Issue Vii Card step with Amount, Card Design Type, Store ID, BIN, Created Card URL set to a vii_link String variable, Limit per contact, Card Expiry Date and Grace Period Days
  • Add a Send email or Send SMS step after Issue Vii card on the Success path, and include the card link, for example {{variables.vii_link}}.
  • Click Save, then Save in the top right-hand corner.
  • To start the workflow, click the 3 dots next to it, select Run, then Yes, start it.
Test with a manually awarded test prize and a low Amount before you go live. See Prizes and Comms.

​
Step 3: Check your workflow runs

The step has two paths:
  • Success: Vii created and loaded the card. The link is saved to your Created Card URL variable.
  • LimitExceeded: the contact has already reached Limit per contact, so no card is issued. Connect a step here if you want to tell them, or leave it empty.
Open Workflow Runs, or Usage under the Workflows dropdown in Card settings, then open a run. A successful step shows the card number, linked to the card. If Vii rejects the request, the step and the run show as Errored with Vii’s response code and message. Komo automatically retries temporary errors, such as timeouts or Vii being briefly out of card stock, for a few minutes before it gives up. Fix the cause, then retry the run from Workflow Runs.

​
FAQ

Why does Connect say “Vii is not available on your current plan”? Vii isn’t included in your Komo plan. Contact your Komo account manager to enable it. Why can’t I see the Issue Vii card step in my workflow? Vii isn’t connected for your company yet. Connect it in Company Settings > Connected Apps first. How does Limit per contact count cards? It counts the cards this step has issued to the contact across all runs of this workflow. Runs that errored or went down LimitExceeded don’t count. The workflow needs a trigger with a contact, such as Prize Awarded, for the limit to work. Will retrying a run issue a second card? No. Komo sends Vii the same transaction ID every time it retries a run, including automatic retries, and Vii creates only one card per transaction ID. If the first attempt already created a card, the retry gets that same card back. Why is my Created Card URL variable empty? Your Card Design Type isn’t a digital design hosted by Vii, so Vii returned a card without a link. Ask Vii to set up a digital design. Why did the step fail with “Invalid step data”? A required field is missing, or Amount is outside $5 to $1,000. Open the step, fix the field, then retry the run. Why did the step fail with a Vii error? If the error shows a Vii response code, Vii rejected the card, for example because of a wrong Store ID, BIN or card design code. If it has no response code, Vii didn’t accept the request at all, so check the connection’s username, password and endpoint. Fix the values with Vii, then retry the run.