Generate accounts and vouchers with patterns

When you sell prepaid cards or vouchers, you need hundreds of records with unique, random numbers and PINs. Instead of preparing them in a spreadsheet, you put a pattern in a field and let the switch fill it with a new random value for every record. This tutorial generates a batch of top-up vouchers in the panel and shows the same patterns for accounts created through the API. Allow 10 minutes.

Before you start

• You have Administrator access to the panel, with the right to add top-up vouchers.
• You know the value, currency and expiration date of the batch.

Step 1: Choose the patterns

A field contains either a fixed value or exactly one pattern. A pattern cannot be combined with fixed text in the same field.

Pattern	Generates	Example	Result
${N:n}	n random digits; the first digit is never 0	${N:10}	4093817265
${N:[…][…]…}	One digit per bracket: a range [0-6], a list [0,4,9] or a fixed digit [5]	${N:[2,3,4][0-8][0-9][0-9]}	2000–2899, 3000–3899 or 4000–4899
${P:n}	A random password of n letters and digits, with at least one digit	${P:12}	k3XbQ9pLm2Ra
${C:Field}	A copy of the value generated for another field of the same record	${C:Account Name}	The same value as Account Name

To start every number with a fixed prefix, give each prefix digit its own bracket: ${N:[7][7][0-9][0-9][0-9][0-9][0-9][0-9]} gives eight-digit numbers that start with 77.

Caution

The switch tries 10 times to find a value that is not taken yet, then gives up. Leave plenty of room: a pattern with 1,000 possible values is exhausted long before 1,000 records. For card numbers and PINs that customers must not guess, use at least 10 random digits.

Step 2: Generate top-up vouchers

1. Open Payments → Top-Up Vouchers.
2. Click Generate.
3. Keep or change Voucher ID. The default ${N:[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]} gives ten random digits.
4. Enter Book Value, select Currency and set Expiration Date and Credit Lifetime, days.
5. Enter a Batch Tag, for example promo-2026-11, to find the batch later.
6. Select Use Secret PIN if the customer must enter a PIN as well, and keep or change the Secret PIN pattern. The default gives four random digits.
7. Enter Number of Top-up Vouchers, from 1 to 10000.
8. Click Generate.

Screenshot "tutorials/vouchers-generate" has not been generated yet — see scripts/screenshots/screens.yml.

Result: the browser downloads a Top-up Vouchers file with one row per voucher, including the generated Voucher ID and Secret PIN. The vouchers appear in the list with the batch tag.

Caution

The file is the only place where you see the PINs in plain text. Store it safely, give it to the printer and delete it afterwards. If a pattern has a syntax error, or not all vouchers could be generated, the file has fewer rows than you asked for: count them.

Step 3: Generate accounts through the API

createAccount of the XML-RPC API accepts the same patterns in its parameters and returns the generated credentials. Call it once per card, for example from a script:

request

call("createAccount", {
    "username": "${N:[1-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]}",
    "authname": "${C:username}",
    "voip_password": "${N:[0-9][0-9][0-9][0-9]}",
    "web_password": "${P:12}",
    # … the other required parameters of createAccount
})

In the API, ${C:…} takes the name of another parameter, not a panel label. See Creating accounts for the other parameters. To load accounts from a file instead, use Upload… on the Accounts screen; the file takes fixed values only. See Accounts.

Step 4: Test it

1. Open Payments → Top-Up Vouchers and filter by the Batch Tag of the batch.
2. Check that the number of vouchers, the Book Value and the status Active are as expected.
3. Redeem one voucher on a test account and check that its balance grows by the book value.

What’s next

• Top-up vouchers: how customers redeem vouchers.
• Set up a calling card product: a complete prepaid card setup.
• Accounts: the account form and bulk upload.