The Gift card types application is part of the Multi-channel Sales module of the Comarch ERP Enterprise system. The application is used to define gift card templates (types) that are used when creating individual gift cards. The gift card type determines the default settings and behaviour of all gift cards created on its basis, which ensures consistent configuration and reduces the effort required to set up each gift card.

Data entered in a gift card type is used, among others, in the Gift cards, List: Gift cards and Export gift cards applications. The gift card type configuration is also transferred to external systems (Comarch POS, Cloud) via the export applications.

Application description

The application consists of a header and a work pane divided into tabs. Some fields in the header and in the tabs depend on the configuration of other fields (for example, on whether the gift card is marked as external) – unavailable fields are greyed out or hidden.

Header

The header of the application contains fields that identify the gift card type and its basic business parameters. Header fields:

• Type – a three-character code that uniquely identifies the gift card type in the system. The field is mandatory and editable only before the type is saved for the first time. Once the first gift card has been created on the basis of this type, the code can no longer be changed.
• Number length – an integer that specifies the length of the gift card numbers generated for this type. The field is mandatory. The value must be greater than zero and not greater than 50.
• Prefix – an optional field that allows a prefix for the gift card numbers to be specified. The prefix can contain only uppercase letters, numbers and certain characters (for example, a hyphen).
• Suffix – an optional field that allows a suffix for the gift card numbers to be specified. The suffix can contain only uppercase letters, numbers and certain characters (for example, a hyphen).
• Regex – a text parameter that allows a regular expression identifying gift cards of this type to be defined directly. If the field is filled in, the adapter uses the entered value. If the field is empty, the POS adapter builds the regex on the basis of the Prefix, Number length and Suffix The field is available if the External parameter is selected.
• Item – the item that represents the gift card on sales documents. A gift card cannot be added directly as a line item on a document – it is represented by the assigned item. The field is mandatory for internal gift cards. Once the first gift card has been created on the basis of this type, the item can no longer be changed.
• Description – a short description of the gift card type.
• Long description – a long description of the gift card type. The long description can serve as default text printed on the gift card (e.g. “The card can only be used for items with 21% VAT”).
• Organization responsible – the organization responsible for the gift card type. The default value is the currently selected organization. The organization must match the responsible organization assigned to the item representing the gift card type. Once the first gift card has been created on the basis of this type, the organization can no longer be changed.
• Default value – the monetary value of the gift card (amount and currency) that will be preset on each gift card created for this type. A value of 0 means that the gift card has no default value and its value is determined during the sales process. The default currency is the leading currency taken from the Customizing The currency must correspond to an internal currency of the organization processing the gift card data.
• External – a boolean parameter that specifies whether the gift card is issued by the Comarch ERP Enterprise system (parameter deselected – internal gift card) or by an external entity (parameter selected – external gift card). For an external gift card, the system only plays a tracking role and is not responsible for validating the gift card. The value of the field cannot be changed after the first save.
• Assigned organization – the list of organizations in which gift cards of this type can be sold and redeemed. The field supports multiple selection using the diamond button. The field is mandatory.
• Generate Gift card number at adapter – when this field is selected, a new gift card number is created by the adapter at the moment the gift card is sold. The behaviour also depends on the Sell offline field: when both fields are deselected, the adapter must first have the entered number verified by the CEE system; when both are selected, the adapter creates the gift card number without CEE verification; when only the Sell offline field is selected, the number can be entered directly from a paper gift card without CEE verification. The field is editable only when the External field is set to No and the Sell offline field is set to Yes, and only as long as the gift card type has not been saved for the first time.
• Fixed characters for creator identification – the number of characters reserved in the gift card number for the identifier of the creation location (sales channel or POS terminal). The field is filled in automatically with the value from the Customizing application (the Fixed characters in gift card number parameter in the General function) during the first save of the type, when the Generate Gift card number at adapter parameter is selected. The field is not editable. After the first save the value is not updated.
• Active – a parameter indicating whether the gift card type can be used by adapters to create new gift cards. The value is set automatically by the system based on whether the configuration of the Fixed characters for creator identification field matches the highest sales channel or POS terminal identifier. Default value: Active. The field is not editable and cannot be changed by BIS import.

Work pane

The work pane of the application is divided into tabs that group the gift card type parameters according to their purpose: general parameters for the manner of use and accounting parameters.

General

The General tab contains the parameters that define how gift cards of this type are used in the sales and redemption process.

• Usage – defines whether gift cards of this type can be used once or multiple times. Available values: Single-use (the gift card is redeemed in full on a single document) and Multiple-use (the gift card can be redeemed partially on multiple documents until the balance is exhausted). Once the first gift card has been created on the basis of this type, the manner of use can no longer be changed.
• Days valid – the number of days for which the gift card is valid, counting from the day of sale. A value of 0 means that the gift card has no expiry date (it is valid indefinitely). The value must be greater than or equal to 0.
• Rechargeable – the parameter specifies whether it is possible to add money to a gift card after its initial purchase. The field is information passed to the adapters.
• Give cash back possibility – the field specifies whether cash back is allowed for the given gift card type. The field is available and editable, and its value can be changed even when gift cards of this type exist. Default value: No. The field is not editable when the Limit of usage field is selected.
• Sell offline – defines whether the gift card can be sold offline at a POS workstation. The field is information passed to the adapters.
• Redeem offline – defines whether the gift card can be redeemed offline at a POS workstation. The field is information passed to the adapters.
• Personalized – specifies whether gift cards of this type are assigned to a specific customer. For personalized gift cards, a customer (a partner with the Customer role) must be specified when the gift card is created. Redemption of a personalized gift card by another customer is controlled in accordance with the Redeem the gift card by other customer parameter in the Customizing application (Multi-channel Sales, General function).
• Usable x days after validity period – the number of days during which the gift card is accepted after the official validity period has expired. The field is editable only when the Limit of usage field (for meal vouchers) or the Service voucher field is selected. Default value: 0. Positive integers are permitted. If the Limit of usage field is deselected, the value is reset to 0.
• Limit of usage – a boolean parameter indicating that the external gift card is a meal voucher with a value limit and a restriction to specified items. The field is editable when the External parameter is selected. After the gift card type has been exported to an external system (Comarch POS), the parameter is not editable. If the External field is deselected, the field is reset to its default value. Selecting the parameter blocks editing of the Give cash back possibility and Days valid
• Service voucher – a boolean parameter indicating that the external gift card is a service voucher (e.g. a welfare voucher issued by public entities). The field is available only for external gift cards. Selecting the parameter enables the Usable x days after validity period
• Issuer code – the gift card issuer code compliant with the GS1-128 number structure. The field is editable only when the External and Active parameters are selected. Only digits with a length of 6 to 12 digits are allowed. Once the first gift card has been created on the basis of this type, the value can no longer be changed. The field can be set via BIS.
• Control of sell not required – a parameter that determines whether a gift card of this type must be sold before it is redeemed. Default value: parameter deselected – the gift card must be sold before redemption. When selected, the sell-before-redeem validation is skipped. The field is editable only for internal gift cards. For external gift cards, the control of sale is not performed regardless of the setting of this parameter.

Financial accounting

The Financial accounting tab contains parameters relating to the tax and accounting settlement of the sale and redemption of gift cards.

• Purpose – the field specifies the VAT settlement model for gift cards of the given type. It determines the moment at which tax is charged. Available values:
  • Multi-purpose – the gift card can be redeemed for the purchase of an item at any VAT rate. Tax is not charged at the time the gift card is sold, but only when it is redeemed, upon the supply of the goods or service.
  • Single-purpose – the gift card can be used only for the purchase of items at one specific VAT rate. Tax is charged already at the time the gift card is sold, not when it is redeemed.

The field is visible but not editable – it takes the fixed value Multi-purpose.

Cooperation with adapters

Gift cards are exchanged between the system and the adapters via the Export gift cards application as well as web services and BIS interfaces. The way a gift card is handled may differ depending on the adapter.

Comarch POS

The Comarch POS adapter supports the full life cycle of an internal gift card.

Information on handling gift cards in Comarch POS can be found in the document Handling of vouchers.

Cloud

The Cloud adapter provides the web service com.sem.ext.app.mcs.loyalty.giftcard.rest.GiftCardsService, which handles the creation and redemption of gift cards in online shops. Within the scope supported by the adapter:

• the online shop calls the web service requesting the creation of a new gift card (or several gift cards), specifying the gift card type and, optionally, the value and validity period; if the value or validity period are not provided, the default values from the gift card type are used
• after the gift card is created, the web service returns the gift card number and its status (initially Created)
• the gift card can be activated at any time after its creation (e.g. after payment confirmation) using the activateGiftCard method – the status changes from Created to Active
• when a gift card is added to the basket, the online shop may optionally call the web service that verifies the validity of the gift card and its available balance
• before the order is confirmed, the shop performs a mandatory verification of the gift card – this prevents the same gift card from being used in parallel in another channel
• after payment confirmation, the shop passes the gift card number and the amount used; the system updates the gift card balance and, if the balance reaches zero, automatically changes the gift card status to Disabled

REST

Base path: com.sem.ext.app.mcs.loyalty.giftcard.rest.GiftCardsService

All endpoints: POST

Input and output data format: application/json

Available methods:

• POST /createGiftCards
  • Creates one or more gift cards.
  • Request body: List<GiftCardCreateData> (JSON array).
  • Required field: type. Optional fields: value, valid from, valid to, customer.
• POST /isGiftCardValid
  • Returns the current state of an existing gift card.
  • Request body: a single GiftCardData object.
  • Required fields: number, type.
• POST /redeemGiftCard
  • Debits an amount from an active gift card and records an entry in the history.
  • Request body: GiftCardData.
  • Required fields: number, type, amount. Optional field: documentData.
• POST /activateGiftCard
  • Changes the gift card status from CREATED to ACTIVE.
  • Request body: GiftCardData.
  • Required fields: number, type.