Top-up vouchers

A top-up voucher is a prepaid code with a fixed value, the Book Value. You create vouchers in advance, print or sell them, and an account redeems one to add its value to the balance. Redemption works in the self-care portal under Make Payment and through the XML-RPC API. Each voucher can be redeemed once, and only by an account of the customer that created it.

Where to find it

Open Payments → Top-Up Vouchers in the left sidebar. The URL is /vouchers.php. The item is shown when you may add vouchers or already own some, and not to web users with a restricted access level. Add, Generate, editing and Delete follow your add, edit and delete rights for vouchers.

Screenshot "admin-panel/vouchers-list" has not been generated yet — see scripts/screenshots/screens.yml.

Before you start

Accounts can redeem vouchers only through a payment processor. Add one in Payments → Payment Processors with the gateway that matches your vouchers. See Payments.

Payment Gateway	Accepts	In the portal the account enters
Vouchers	Vouchers without a PIN	Voucher ID
Vouchers with PIN	Vouchers with Use Secret PIN only	Voucher ID and Secret PIN

The processor’s Currency must equal the account’s Payment Currency. A voucher that does not match the processor type is refused: a PIN voucher cannot be redeemed through Vouchers, and a voucher without a PIN not through Vouchers with PIN. Choose one kind for all vouchers of a currency.

What you see

Column	Meaning
Voucher ID	The code printed on the voucher, linking to the form
Book Value	Value converted to the Display Currency of the filter, your base currency by default
Batch Tag	Label of the batch the voucher belongs to
Status	Active with the expiration date or does not expire; Expired on a date; or Redeemed by an account on a date, with a link to the payment

The quick filter matches Voucher ID with is like / is not like and the status Any Status, Not Redeemed or Redeemed. Filters adds Batch Tag, Book Value, Display Currency, Redeemed by, Redemption Date (Redeemed before, Redeemed after) and Expiration Date (Expired before, Expired since, Expires by, Expires not earlier than). Text patterns match the whole value; use % as a wildcard, for example 2025-06% for a batch tag.

Create a voucher

1. Click Add.
2. Enter Voucher ID. It must be unique.
3. Enter Book Value and select Currency.
4. Set Expiration Date, or keep never.
5. Set Credit Lifetime, days. See the table below.
6. Enter a Batch Tag to group the voucher with others.
7. Check Use Secret PIN and enter Secret PIN, digits only, if the voucher is protected by a PIN.
8. Click Save & Close.

Field	Meaning
Book Value	Amount added to the balance, in the voucher’s Currency. Converted to the account’s currency with your exchange rates on redemption. Must be positive
Expiration Date	Last day the voucher can be redeemed. never for no limit
Credit Lifetime, days	How long the account stays usable after the top-up: a number of days from redemption, From Account to use the account’s Lifetime (days), or Never Expires. The account’s expiration date moves to the new date unless the account already expires later; an account with a fixed lifetime never becomes unlimited this way
Batch Tag	Free label, offered again in later vouchers and in the filter
Use Secret PIN, Secret PIN	Require a PIN on redemption. The PIN is stored encrypted and never shown again

A redeemed voucher is read-only.

Generate vouchers in bulk

1. Click Generate.
2. Keep or change the patterns in Voucher ID and Secret PIN.
3. Enter Book Value, Currency, Expiration Date, Credit Lifetime, days and a Batch Tag for the batch.
4. Check Use Secret PIN if the vouchers need a PIN.
5. Enter Number of Top-up Vouchers, from 1 to 10000.
6. Click Generate.

The patterns produce random digits: ${N:[0-9][0-9][0-9][0-9]} gives four digits, one bracket per digit. A bracket holds a range such as [1-9] or a list such as [2,3,4], so ${N:[1-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]} gives ten digits without a leading zero. The defaults are a 10-digit Voucher ID and a 4-digit Secret PIN. Each generated ID is checked against the existing vouchers; if the pattern leaves too few free combinations, generation stops with an error. The same syntax is used by the accounts generator, see Accounts generator.

When generation finishes, the browser downloads a Top-up Vouchers file with the new vouchers.

Caution

The generated file is the only place where the PINs of the batch appear in clear text. Download from the list leaves the Secret PIN column empty, and the form shows only a mask. Store the file safely before you close the page.

Upload and download

Download exports the vouchers that match the filters in your download format: Id, Voucher ID, Book Value, Expiration Date, Currency, Credit Lifetime, Batch Tag, Use Secret PIN, Redemption Date and the account that redeemed it. Upload takes the same file back with an Action [A|D|U] column: A adds the row, U updates the voucher with the given Id, D deletes it. Rows that fail come back as a Top-up Vouchers errors file.

Delete a voucher

The trash icon in a row deletes a voucher after confirmation. Delete vouchers that were lost or stolen before they are redeemed; a redeemed voucher has already credited the balance and deleting it does not take the money back.

Vouchers for resellers

A reseller can sell its own vouchers to its own accounts:

1. Open My Customers → Permissions and tick Vouchers +, e and - for the reseller. See Users and permissions.
2. Click Set in that row.
3. Ask the reseller to add a Vouchers or Vouchers with PIN processor in its own Payment Processors and create its vouchers in its panel.

Vouchers of one customer cannot be redeemed by accounts of another, including the accounts of its sub-resellers.

Tip

Use one Batch Tag per print run or distributor. If a batch goes missing, filter by the tag and Not Redeemed, then Download and upload the same file with D in the action column to cancel the whole batch at once.

Related pages

• Payments
• Top up an account with a voucher
• Top-up cards
• Accounts
• Exchange rates