Purchase vouchers for printing - WEBSALE Dokumentation

A purchase voucher is a voucher that the customer buys in the shop, usually to give as a gift. Its biggest advantage is speed: the buyer downloads it immediately after payment and prints it out, which makes it a useful last-minute gift. Technically, a purchase voucher is a completely ordinary product. It is added to the basket, goes through the normal ordering process, and is paid for like any other product. The special part happens in the background.

What the process looks like

Step	What happens
The customer adds the voucher product to the basket	The shop generates a voucher number or takes it from a previously created pool
The customer pays	The voucher number is displayed to them immediately
The customer downloads the voucher	For each voucher number, a PDF file with number, amount, and validity is created from a dedicated template

Because the buyer sees the number immediately after payment and can redeem it right away, purchase vouchers can be tied to secure payment methods. How to set this up is described in step 5.

If the customer changes the value after adding it to the basket, for example via a different variant, the shop draws the numbers again. The number that ends up on the voucher is therefore only final with the order.

Use case: Offer purchase vouchers for printing with multiple designs

The integration

Step 1: Activation

If you want to use the voucher generator, it must be activated for your shop. Contact your WEBSALE representative to do so.

If the vouchers come from an external system and are therefore not in WEBSALE format, add the entry ExternalVouchers-Allow = yes in the <Voucher-Txt> section of the shop.config.

Step 2: Integrating voucher entry

If your shop does not offer vouchers at all yet, the option to enter them is missing. Without it, nobody can redeem the purchased voucher later. Guide: Provide voucher entry

Step 3: Creating the purchase vouchers as products

Purchase vouchers are created like any other product. In addition, they need the product field InstantVoucherProduct, which consists of four values. All four are placed one after another in one field and enclosed by <g>.

<g><1>Gutscheinprodukt y/n</1><2>ChargenID</2><3>Vorlagenwert überschreiben y/n</3><4>Nummer neu generieren y/n</4></g>

Position	Meaning	Values
`<1>`	whether this product is a voucher product	`y` active. Any other value means inactive, and the remaining three values are not evaluated
`<2>`	the batch ID to which the vouchers belong	the name of the batch
`<3>`	where the voucher value comes from	`y` the product price is the voucher value and overrides the value from the template or pool. Any other value keeps the value from the template or pool
`<4>`	where the number comes from	`y` the shop generates a new number. Any other value takes it from the pool

<g><1>y</1><2>Kaufgutscheine</2><3>y</3><4>y</4></g>

The values are checked for y, not for n. A typo or an empty field at position 1 turns the product into an ordinary item that is sold without a voucher. The shop does not report this.

Variants are generally used for the value levels. A “voucher value” variant with the levels 10, 20, 50, 100, 200, and 500 euros is the usual setup. In combination with <3> set to y, the voucher value then results directly from the selected variant.

Step 4: Providing voucher numbers

The numbers come from one of two sources. Position 4 in the product field decides which one.

Position 4	Source	What you prepare
`y`	The shop generates a new number	a voucher template in the voucher generator of the online service area
anything else	The shop takes it from a pool	import of a voucher number pool from your merchandise management or ERP system

In both cases, each voucher must be assigned a batch ID, because this exact ID is what you enter at position 2 of the product field. Without a matching batch, the shop finds no numbers.

If you have specified at position 3 that the product price determines the voucher value, the shop overrides two values, regardless of the source:

The stored currency is replaced by the currency of the subshop.
The voucher value from the template or pool is replaced by the product price.

With a pool, your upstream system must ensure that enough numbers are always available. If none are left, the voucher product cannot be purchased. As a rule, the check only takes place when the order is placed and not when the product is added to the basket. The customer therefore goes through the entire ordering process before seeing the error message. Therefore, actively monitor the fill level of the pool instead of relying on the message.

The format of the import file is described in separate documentation, which you can request from WEBSALE AG.

Guide: Create or import vouchers

Step 5: Defining payment methods

Because the buyer sees the voucher number immediately after payment and can redeem it right away, you should only sell purchase vouchers for online payment methods such as credit card, PayPal, or Sofortüberweisung. With invoice or cash on delivery, the customer would already have the equivalent value in hand before the money reaches you. You define the approval individually for each payment method, in the respective <PaymentXXX-Txt> section of the shop.config.

<PaymentXXX-Txt>
   InstantVoucherProducts-Allow = yes
</PaymentXXX-Txt>

XXX stands for the respective payment method, so the section is called <PaymentCreditCard-Txt>, for example. If at least one purchase voucher is in the basket, the shop only offers the payment methods for which this entry is set to yes.

Reference: PaymentXXX-Txt

Step 6: Marking purchase vouchers in the templates (optional)

Purchase vouchers can be enclosed separately to display them differently from ordinary products, for example with a notice about the immediate download.

Template	Section
Product overview page `ws_category.htm` and product detail view `ws_product.htm`	`PR-InstantVoucherProduct`
Basket page `ws_basket.htm`	`BASKET-PR-InstantVoucherProduct`

{PR-InstantVoucherProduct}
   Diesen Gutschein erhalten Sie sofort nach der Bezahlung zum Ausdrucken.
{/PR-InstantVoucherProduct}

Reference: PR-InstantVoucherProduct · BASKET-PR-InstantVoucherProduct

Step 7: Displaying the voucher number and download link

The generated number and the link to the PDF file can be output in three places: on the order confirmation page ws_confirm.htm, in the order confirmation email, and in the order history.

{@BASKET-PR-Data}
   {BASKET-PR-InstantVoucherProduct}
      {BASKET-PR-InstantVoucherProductData}
         {@BASKET-PR-InstantVoucherProductData}
            Gutscheinnummer: ~BASKET-PR-InstantVoucherProductData_VoucherNumber~
            <a href="~WS-Start~~BASKET-PR-InstantVoucherProductData_PDFLinkPart~">Gutschein herunterladen</a>
         {/@BASKET-PR-InstantVoucherProductData}
      {/BASKET-PR-InstantVoucherProductData}
   {/BASKET-PR-InstantVoucherProduct}
{/@BASKET-PR-Data}

The inner loop is necessary because a basket item can contain multiple vouchers. If someone buys five vouchers of the same kind, five numbers and five PDF files are created in a single item.

BASKET-PR-InstantVoucherProductData_PDFLinkPart only provides the latter part of the address. WS-Start must precede it, which is why the two tags appear directly one after the other in the example. The parameter is encrypted, provided with a checksum, and contains the shop ID, so other people’s vouchers cannot be retrieved through it.

Reference: BASKET-PR-Data · BASKET-PR-InstantVoucherProduct · BASKET-PR-InstantVoucherProductData · BASKET-PR-InstantVoucherProductData_VoucherNumber · BASKET-PR-InstantVoucherProductData_PDFLinkPart · WS-Start

Step 8: Creating the template for the PDF download

The voucher for printing is generated from a dedicated template. Three settings are required for this.

8.1 Assigning the template in the configuration

<Templates>
   InstantVoucherPDF = ws_instant_voucher.htm   # Template für den PDF-Download des Gutscheins
</Templates>

8.2 Creating the template

Create the template under the name you just assigned in your template directory, for example under benutzer/templates, or in a multilingual shop in the directory of the respective subshop.

Gutschein
Betrag:     ~INSTANTVOUCHER-Amount~ ~INSTANTVOUCHER-CurrencyCode~ ~INSTANTVOUCHER-CurrencySymbol~
Nummer:     ~INSTANTVOUCHER-VoucherNumber~
Gültig bis: ~INSTANTVOUCHER-ValidUntil_day~.~INSTANTVOUCHER-ValidUntil_month~.~INSTANTVOUCHER-ValidUntil_year~

The INSTANTVOUCHER- family comprises exactly these seven tags.

Tag	Content
`INSTANTVOUCHER-Amount`	the voucher amount, already in the shop’s price format
`INSTANTVOUCHER-CurrencyCode`	the currency code, for example `EUR`
`INSTANTVOUCHER-CurrencySymbol`	the currency symbol
`INSTANTVOUCHER-VoucherNumber`	the voucher number
`INSTANTVOUCHER-ValidUntil_day`	the day of validity
`INSTANTVOUCHER-ValidUntil_month`	the month of validity
`INSTANTVOUCHER-ValidUntil_year`	the year of validity

The three date tags remain empty if no expiry date is stored for the voucher. The line “Valid until: ..” then appears with two bare dots on the printed voucher. Therefore, enclose the line, for example with {INSTANTVOUCHER-ValidUntil_year}, so that it only appears when a date is present.

For a physical store, you can additionally print the voucher number as a barcode on the template and have it scanned at the checkout. The tag WS-BarcodeURL generates the barcode as an image.

Reference: Templates section · INSTANTVOUCHER- · WS-BarcodeURL

8.3 Defining the file name of the PDF file

<PDFGenerator>
   InstantVoucherPDFFilename = gutschein.pdf
</PDFGenerator>

This name appears in the customer’s download dialog. A descriptive name like gutschein.pdf is worth more here than a technical designation, because the file should remain easy to find in the buyer’s download folder.

Reference: PDFGenerator section

Step 9: Providing the error message

If something goes wrong when drawing or generating a voucher number, the customer needs a text. Store it in the <NotifyMessages-Txt> section of the shop.config.

<NotifyMessages-Txt>
   InstantVoucherError = Es ist ein Fehler aufgetreten. Bitte versuchen Sie es erneut oder wenden Sie sich an den Shopbetreiber.
</NotifyMessages-Txt>

This message is the only notice the customer receives in the event of an error, and it typically only appears when the order is placed. Without a stored text, the ordering process aborts without explanation.

Reference: NotifyMessages-Txt

Step 10: Offering the download in the order history

If the customer deletes the confirmation email, without this step they have no way of getting to their voucher. Therefore, add the download to the order history ws_order_history.htm.

{@OH-S-Item}
   {@OH-S-InstantVoucherProduct}
      <a href="~WS-Start~~OH-P-PDFLinkPart~">Gutschein ausdrucken</a>
      Gutscheinnummer: ~OH-P-Number~
   {/@OH-S-InstantVoucherProduct}
{/@OH-S-Item}

Reference: OH-S- · OH-P- · WS-Start

What you should keep in mind

The purchase voucher can not be attached as a PDF to the order confirmation email. The customer can only access it via a download link, either in the order confirmation from step 7 or in the order history from step 10. Therefore, set up both options if possible.

If you have questions about the setup, contact the WEBSALE support team.

Guide: Offering vouchers: Overview
Guide: Create or import vouchers
Guide: Provide voucher entry
Use case: Offer purchase vouchers for printing with multiple designs

​What the process looks like

​The integration

​Step 1: Activation

​Step 2: Integrating voucher entry

​Step 3: Creating the purchase vouchers as products

​Step 4: Providing voucher numbers

​Step 5: Defining payment methods

​Step 6: Marking purchase vouchers in the templates (optional)

​Step 7: Displaying the voucher number and download link

​Step 8: Creating the template for the PDF download

​8.1 Assigning the template in the configuration

​8.2 Creating the template

​8.3 Defining the file name of the PDF file

​Step 9: Providing the error message

​Step 10: Offering the download in the order history

​What you should keep in mind

​Related topics

What the process looks like

The integration

Step 1: Activation

Step 2: Integrating voucher entry

Step 3: Creating the purchase vouchers as products

Step 4: Providing voucher numbers

Step 5: Defining payment methods

Step 6: Marking purchase vouchers in the templates (optional)

Step 7: Displaying the voucher number and download link

Step 8: Creating the template for the PDF download

8.1 Assigning the template in the configuration

8.2 Creating the template

8.3 Defining the file name of the PDF file

Step 9: Providing the error message

Step 10: Offering the download in the order history

What you should keep in mind

Related topics