Vouchers: how to

Introduction / overview

A voucher in cyclos has a unique identification ‘token’ that can consist of a number of digits. The token can be represented as a number or an image such as a QR code (for quick scanning). A voucher represents a certain amount, which can spend at shops or used by the user himself to top up his balance. Because of the flexibility of the voucher module there are many use cases. Typical uses of vouchers are gift cards and promotion coupons. Besides the unique token / QR code, a voucher has a title, a description, it can have an image and can be presented with a nice layout (html/pdf). A voucher can be printed on paper or a card, it can be downloaded as a pdf and it can be displayed directly from our mobile app / front-end (voucher wallet). The user can spend a voucher at an intake point, for example a shop or a restaurant, who will use the Cyclos mobile app or web interface to redeem the voucher (by either typing in the number or scanning the QR code). A user with a Cyclos account can send a gift voucher to an external user (without a cyclos account) via email. It is also possible to send vouchers to multiple users in one go (by importing a list with emails).

Note: The number of open vouchers you are allowed to have is limited, it's 10 times the number of users you are allowed to have in your system.

Voucher settings

There are two main places for the voucher settings. The voucher configurations, here you set the most basic settings, and the voucher type, here you set the more specific settings. Our idea is that each system will only have a few voucher configurations and multiple voucher types per configuration. If you only need a single kind of voucher in your system, you will have one voucher configuration with one voucher type. We created voucher configurations so that easily extra vouchers types can be created without the need to set all the basic settings each time.

With both this voucher configuration and type you can define the behavior of the voucher. A voucher can for example have an expiration date (that can be changed by an admin), it can be made partially redeemable, it can have a PIN number for security, and there can be various payment restrictions. You can for example restrict where vouchers of a specific type can be redeemed (at a specific shop, or a group of businesses, or all businesses in the Cyclos system), at what specific weekdays they can be used, the period in which it can be used, and the maximum amount of each voucher and max amount of vouchers per user. Each voucher type can have its own layout and content that can be easily customized.

Voucher generation (by admin)

Administrators can generate vouchers and distribute them (digitally or on cards/paper). Vouchers can be generated in bulk quantities and sent to users via a digital channel (mobile app and Cyclos web interface), or they can be exported to a CSV file (to be sent to a printing company or card maker). When a voucher is generated its amount can be reserved in the system. When the voucher is redeemed the reserved amount will be credited to the intake point (typically a shop). It is also possible create 'inactive' vouchers, meaning that there amount is not reserved upon creation, but only when the voucher is activated (explained in the next section).

Activate voucher

It is possible to generate ‘inactive’ vouchers, meaning that the vouchers do have a voucher type and a unique number (that can be presented as a QR code), but they do not have a reserved amount in Cyclos yet. The use of ‘inactive’ vouchers can make the logistics of voucher distribution easier. Vouchers can be sent to the customers, and only if they activate the vouchers online the amount will be reserved. If the vouchers are not activated by the customers they will just expire. It will work the same if vouchers are sent to shops or 'voucher points' (e.g. shops). When a customer wants to buy a voucher the shop operator can activate the voucher (‘load it’ with units) ’on the fly’ using the Cyclos mobile app or Cyclos voucher webpage. The advantage of this use case is that shops or 'voucher points' can be supplied with vouchers without the need to be bought first (there is no reserved payment, meaning they are 'un-backed' until they are sold). If inactive vouchers got lost or stolen there is no problem as they cannot be used, and accounting-wise they do not exist in the system, they will simply expire after a period (defined in the voucher type). When a shop activates a voucher the shop operator can put in the voucher amount (within the value range defined in the voucher type). The shop will be charged automatically (in Cyclos) when activating the voucher, and will usually ask the voucher buyer to pay the amount of the voucher in cash. This is a common 'gift voucher' use case, other use cases / flows are possible.

Top-up voucher

A shop can also be given permissions to 'top-up' an existing voucher. This allows emitting 'reusable vouchers' that work much like debit cards. Because normally on the vouchers there will be a printed amount, these reusable vouchers should have the inactive status on generation. Reusable vouchers, that would be typically printed on plastic cards, are an interesting way to deploy quickly large amounts of 'micro accounts'. These accounts can be used by customers to do payments at shops, top-up their cards, and access a simple page (for example https://demo.cyclos.org/voucher/) that shows the voucher details (status, voucher balance, expire date etc.) and a list with all voucher transactions (top-ups and redeems). Information about the voucher information page can be found further below at this section .
In case of reusable vouchers it is advised to use a voucher PIN for extra security. Information about the voucher PIN can be found further below at this section.

Voucher buying (by user)

Users can also buy vouchers themselves online in Cyclos (setting in the voucher type). A user that buys a voucher in Cyclos can print it out and use it at the shop or business, or use their voucher wallet in the mobile app. The voucher details in the app will show the details and a QR code, that can be scanned/redeemed by the shop in the same way as a paper voucher. In order to be able to buy vouchers online in Cyclos the user will need a Cyclos account. The purpose of buying vouchers in Cyclos and using them at shops (instead of paying the shop directly) is that it gives the shops the possibility to emit a limited amount of ‘promotion vouchers’ with spendiblity rules. For example a restaurant can offer a certain amount of vouchers to be spent during a specific period and for specific weekdays/hours, and a max amount of vouchers per user. Users can search for vouchers at the cyclos marketplace. A list of voucher types is shown (with image and description), and for systems with many voucher types it is possible to create voucher categories to make the voucher search easier. There is also a keyword search that searches for text in all vouchers.
A user can also buy a voucher and send it directly to an external user (as a gift), by putting in an email address or phone number of the receiver. The email recipient will receive the vouchers with instructions how and where it can be spent. It is also possible to send multiple gift vouchers at once with an import file.

Finally, a user can also buy a voucher and print it himself as a gift (depending on the setting in the voucher type). When a voucher is set to gift, the user can't track the purchases made with the voucher. When a voucher is not set to be a gift a text will be displayed on the voucher that it is only for personal use. It is also possible to send multiple gift vouchers in one go, this can be done by importing a file with the usernames, emails, voucher type and amount.

Voucher intake (redeeming)

The voucher intake point (e.g. shop) will type in the number or scan the QR code. This can be done via the mobile app and web interface and is a dashboard action. After scanning the voucher details will show up. Custom voucher fields will be shown if configured (read only or input depending on the configuration).
In case a voucher PIN is configured in the voucher type the buyer (voucher owner) will have to type in the PIN first and click on ok. After a successful voucher redeeming a confirmation page is shown, the shop is credited with the voucher amount and notifications will be sent to both shop and voucher owner (payer).

Voucher PIN

As described in the section above a PIN can be required upon each voucher redeeming. Especially when a voucher can be partially redeemed (voucher configuration setting) it is advised to use a voucher PIN, as a malicious shop operator could copy the QR code and use it at another shop. If a PIN is configured in the voucher type it is usually generated upon voucher creation. There are various options to deliver the PIN to the voucher receiver. It can be delivered on paper together with the voucher. This will require some logistics as the voucher and PIN will need to be printed and delivered together with the voucher. Another option is that the voucher buyer can type in the PIN at a PINpad (or keyboard) when the voucher is activated. It is also possible that the voucher buyer will provide an email or mobile phone number when buying a voucher. The voucher point operator will fill in the email and/or SMS, and the PIN will be sent automatically to the voucher buyer. An advantage of sending the PIN by email or SMS is that the email or/and SMS will be also be used for the voucher notifications.
When a PIN is configured (in the voucher configuration) the customer will be asked to fill it in when accessing the voucher information page (see section directly below). This adds extra security.
If a voucher type is set to be a 'gift' (in the voucher type) the PIN is not generated on voucher creation, but on voucher activation (by the receiver of the gift voucher). The reason for this is that the person that sends the gift voucher should not have access to the voucher PIN. So in this case the receiver of the voucher will be asked to define a PIN upon voucher activation (or provide an email/SMS so that the PIN can be sent automatically).
Another feature of the voucher PIN is that it can be used for unblocking vouchers. There are use cases where vouchers are sent by post to the customers. Before the voucher can be used the card must be unblocked by the customer. This is a simple operation and can be done with the voucher PIN at the voucher information page. The PIN can be sent with an enclosed letter with the voucher or via another channel such as email. It will contain instructions how to unblock the voucher (card or paper voucher). Logging in with the PIN at the information page with an 'blocked' voucher will unblock the voucher (a information message will be shown). It is possible to configure a voucher type to require a voucher PIN just for unblocking and accessing the information page, or to use the PIN also for every redeem at the shop (in case multiple redeems per voucher is configured in the voucher type).
It is also possible to add custom voucher fields, and an input field for email/sms to send the voucher PIN and voucher notifications.

Voucher information page

Users that have a Cyclos account can access their voucher wallet in the mobile app or online. Both the app as the web interface have an overview of the bought and spent vouchers, and for each voucher the user can see the voucher status, the remaining amount (for partially redeemable vouchers), where the vouchers can be spent, and any possible usability restrictions.
Vouchers are an interesting means to include ‘external’ users in the system. These are typically occasional users, for example users that received a gift voucher, and those users do not have (or need) an account in Cyclos. With this use case the vouchers are not 'personalized' (assigned to a Cyclos user). Those external users however can still check their voucher status at a specific page where they can type in the voucher code (or scan the QR code) to see the voucher details (status, remaining amount, expiry date, redeem transactions and top-ups). If a PIN is configured (in the voucher configuration) the user must fill in the voucher code (or scan it) and provide the PIN. The details page has a button to change the voucher PIN and the email address.

The page is available at www.yourdomain.com/instancename/voucher
For example: https://demo.cyclos.org/voucher/

Administrators can also check voucher status, and they have access to a complete overview of all vouchers, (admin menu: Banking - Vouchers - Search vouchers). There are various search filters (voucher type, status, voucher fields, redeemer, group, creation/expiration dates, amount range etc. The overview will show the totals (users, amounts) for each search result, and will give a clear idea about the vouchers in circulation, and their status.

How to set-up

Before starting to configure the voucher module it is good to have a clear idea about the service you want to provide. For example how are the vouchers distributed, how many intake points will there be etc.

Voucher configuration

The first step is to create a ‘voucher configuration’ (admin menu: System - Vouchers - Voucher configurations). It defines the four payment types involved in vouchers, the redeeming payment (to the shop) and the payment type used when users buy vouchers in Cyclos, the payment type for top-ups and the one for refunding (in case of lost or canceled vouchers).
The redeeming payment type is the payment to the voucher redeemer (usually a shop). When a voucher is created by an admin, the amount will be reserved on the account the payment is debited from when the voucher is redeemed. When a voucher is bought by a user, the amount the user paid is stored on an account (using the Payment type for buying). Whether the amount needs to be reserved can be configured. This depends if the system needs a 100% reserve.

It is possible to choose a redeeming payment type that comes from a ‘positive only’ system account, or a payment type coming from the ‘Debit’ (negative only) system account. It is advised to use a ‘positive only’ system account for voucher redeeming, because an admin can preload that account with a maximum amount, and this way there is a control of the total of vouchers that can be generated (this is not possible with the Debit account because it can go indefinitely negative).
The voucher configuration contains settings that are considered 'static' information, and should not change much (mostly just one time at system setup). The 'operational' settings are defined in the voucher type.

Voucher type

The voucher type has most of the settings of the vouchers. Voucher types can be created and managed in the admin menu: System - Vouchers - Voucher types. The choice of voucher types depends very much on the use case. There are systems that have just a single voucher type for the whole system, and there are systems where each shop/merchant has their own voucher type. The voucher type options are mostly self explanatory. In case of doubts the wiki page can be consulted. As the voucher type specifies both the payer and the receiver (redeemer), there was no need to have permissions for voucher types (in the product).

Please be aware that the voucher expiration is not exact. The voucher can expire maximal 1 hour after the expiration interval. In the system a scheduled task that runs each hour expires the vouchers, so "Expiration interval" is not exact. This setup is far more scalable/efficient for large systems.

Voucher template

A voucher templates defines the layout of a voucher, and is assigned to a voucher type. They can be created and assigned to a voucher type at any stage (admin menu: Content - Content management - Voucher templates). Shops (or other voucher emission/intake members) are likely to want to have their customized voucher layout. Cyclos comes with built-in voucher templates and it is possible to create your own templates. There is a 'preview' option to see how the voucher/template will look like, and there is a 'debug html' option that you can open in a browser and adjust the layout in real time using the browser debugger. It is also possible to import and export templates (including images). The voucher templates can be written using the template framework Thymeleaf.
For more information, refer to Customizing_PDF_templates.

Custom voucher fields

It is possible to add custom voucher fields to a voucher type. The fields show up when creating or assigning a voucher. The fields can be read only or input fields. So the shop or 'voucher point' could fill in a voucher field or make a selection from a list (all custom fields are supported). Depending on the custom field permissions the field will be visible/editable by the admins/brokers and the buyer, or admin/brokers only.

Voucher categories

When there are many voucher types (e.g. tens of voucher types) and users can buy vouchers in Cyclos (as described above) , it is advised to create voucher categories for easy searching (admin menu: System - Account configuration - Voucher categories). When there are no categories it means that the buy vouchers page shows directly a list with all voucher types. As soon as there is a voucher category configured a voucher category page will show up when users click on ‘buy vouchers’. Clicking on the category will open a list with the voucher types that are configured with that category (in the voucher type).

Voucher extension point

There are many ways to configure vouchers, but if there is a use case that is not supported than it is possible to implement a voucher extension point. You can write your own code (script) that will run when a specific voucher event happens (generate, buy, redeem, top-up, cancel, unblock, expire). It is possible to bind multiple voucher extensions points to specific events and voucher configurations/voucher types.