Vouchers

Introduction

A voucher in the voucher server represents the concept of a set of alphanumeric (or numeric only) digits that if redeemed will provider the redeemer with some form of benefit or value. Within the server, the value of a voucher may be defined as being made up of buckets which provide cash or cash equivalents (e.g. bytes for use in data charging sessions).

Voucher value may also include sentinel data or non-monetary information, which may be used internally by the OCS to perform additional redemption, call control, rating and wallet/account actions.

Voucher Details

Voucher details can be viewed in the OCS administration GUI where the voucher can be moved between states according the voucher lifecycle.

Voucher Details

Fields

ID

The voucher ID is the internal unique UUID which refers to the voucher. The ID is used internally by the voucher server when a single voucher must be referenced uniquely during internal and system-to-system processing.

Generally, the serial number of the voucher is used to refer to a specific voucher by external systems (including business processes such as manual voucher redemption and other CSR-related functions), as the serial number is a simple number used by the system to also uniquely identify an individual voucher.

Serial Number

The voucher serial number is a unique numeric ID for the voucher. The voucher’s serial number is often used to refer to a voucher within business processes such as CSR-supported manual voucher redemption, and fraud or lost voucher processing. The serial number of a voucher is generally printed alongside the voucher’s unencrypted HRN when then voucher is given to a subscriber/customer so that in the case of an issue occuring during voucher redemption, the serial number can be shared with CSRs.

Vouchers in the N-Squared voucher server are generated within batches, and a batch will start with an unused serial number higher than any serial number previously used by the system. Each voucher then generated within the batch is given the next serial number in sequence and this allows vouchers within a voucher batch to be referred to and managed by serial number range.

Type

The type field shows the voucher type the voucher is associated with, and is stored per voucher. When redeemed the value according to the voucher type (as it is in the system at the time of redemption) is applied to the wallet.

While the voucher type details may be altered programmatically after the voucher is created, once the voucher is redeemed, the voucher type is only used for historical reference.

Batch

The voucher batch the voucher is associated with is stored per voucher. The primary purpose for the voucher batch reference is to determine whether the voucher is redeemeable based on the voucher batch’s “redeemable” flag.

Generator

The voucher generator the voucher is associated with determines how an unencrypted HRN provided to the voucher server during voucher redemption can be encrypted to match against the encrypted HRN stored in the database.

The voucher generator linked identifies how the voucher’s encrypted HRN was encrypted, however it is insufficient to give the unencrypted HRN from the encrypted HRN (since encryption is a one-way hash).

Encrypted HRN

The encrypted HRN is the unencrypted HRN that appears in the print file, in its encrypted form, with the encryption having been applied according to the associated voucher generator.

Redeemed Date

Only shown if the voucher has been redeemed

The timestamp for the date/time the voucher was redeemed.

Redeemed To

Only shown if the voucher has been redeemed

The redeemed to field is a reference to the redeeming entity of the voucher. If the redeeming entity is an account stored in the OCS, this reference will be to the account ID that received the value of the voucher.

Not Redeemable Flag

Only shown if the voucher has not been redeemed

Where a voucher is not yet redeemed, the voucher record will not show the Redeemed Date and Redeemed To fields. Instead, the Not Redeemable flag will be shown, and will be set to on or off depending on whether the voucher has been flagged as redeemeable according to its lifecycle.

unredeemed voucher details

This flag, and the eventual redemption action, are managed by the voucher lifecycle which will execute script code in the voucher server to perform actions such as redeem the voucher against an wallet, or mark a voucher as redeemable (or not).

Voucher’s State

The voucher lifecycle section of the voucher record displays the state(s) the voucher has transitioned through over the course of the voucher’s lifetime. The voucher states, and what each state means, depends on the configuration of the lifecycle used for vouchers.

A default voucher lifecycle is covered in the voucher lifecycle documentation.

It is possible to trigger a state transition for a voucher using the Trigger Event button. This button will show the triggering GUI:

event trigger GUI for voucher lifecycles

In most circumstances it is sufficient to select the Event (e.g. activate) and press the OK button to trigger the transition.

Redeeming a Voucher Manually

It is possible to redeem a voucher manually through the OCS administration GUI.

To perform a voucher redemption, the voucher must first be redeemable. This will require the voucher to have entered a state allowing redemption:

a redeemable voucher

In a redeemable state, the voucher will show Redeemable, and a voucher state transition will be available for performing the redemption. To trigger the redemption, trigger the event with Ancillary Information configured for the account name to redeem the value of the voucher type to:

redeeming a voucher

The format of the Ancillary Information will depend on the deployed solution, however in the default deployment this must be a JSON object with an account field. The account must refer to an OCS wallet’s id.

Triggering the transition, the voucher will be redeemed. The OCS account will gain the bucket values associated with the voucher (as defined on the voucher type).

It is possible that the redemption will fail. In such cases the redemption error will display in the GUI:

error redeeming a voucher

However if the redemption occurs successfully, the voucher transition will complete and the voucher will be marked as redeemed.