Developers - REST API v1

Integration Guide for POS and Access Systems (Issue and Redeem)


You authenticate to the E-GUMA API by providing an API key in the request. Store that key in your system. If your system can be deployed to different outlets, each outlet gets its own API key. It is required that each outlet can store a different API key.

Redeem a voucher

Payment Method

The workflow to redeem a voucher should be the same as paying i.e by cash. Vouchers should be implemented like any other payment method. If the voucher payment button is clicked, the user can enter the voucher code.

Enter Voucher Code

On every voucher is a code and barcode which identifies the voucher. The human readable code has 2 dashes to group the digits - eg. L4FU-5LQT-KJR3. However the barcode doesn't have those dashes. By using a scanner you would get L4FU5LQTKJR3. The code can either be entered with a barcode scanner or on a virtual keyboard provided by your system. It’s important that the virtual keyboard provides numbers, letters, dot and dash. Use the Balance Endpoint to verify the entered voucher by checking is_redeemable field. The Balance Endpoint returns the voucher code. It’s very important to use the returned voucher code for further actions. The reason for that is the voucher2mobile ShortCode, which is only temporarly available.

Amount to redeem

Your system determines the amount which has to be redeemed. The user doesn’t have to enter the amount. The amount to redeem can be calculated like that: min(remaining_amount_to_pay, voucher_balance)


In order to redeem the voucher, call the Redeem Endpoint with the calculated amount. Save the voucher code in your database. Finally, print the voucher code and the new balace on the receipt.

Voucher is not redeemable

If the voucher is not redeemable (e.g. a wrong code was entered, the voucher is already redeemed, etc.) show the message of the Balance Response to the user.

Cancel the voucher payment

If the user voids the voucher payment or cancels the order, then use the Cancel Request with the redeemed code and amount.

Issue a Depot Voucher

A depot voucher looks like a normal voucher. In E-GUMA you create a stack (e.g. 100) of vouchers and print them. They are not yet activated, so they can’t be redeemed. In order to sell a depot voucher it has to be activated.


The user clicks on an item (e.g. "Gift Voucher") on your cashbox. A window appears where the user can enter the voucher code (by scanner or a virtual keyboard) and confirms it. Then your system calls Activate Status. In the response of this request we send if the depot voucher can be activated and the amount of the voucher. There is another flag the Activate Status returns, free_amount. If free_amount is set to true, E-GUMA doesn't return an amount. The user can enter the desired amount. Please provide an input field for the amount to the user. Finally add the voucher to the order, either with the returned amount or the entered amount by the user. The VAT for the order line has to be 0. When the order is being closed send the Activate Request.


If the order with a depot voucher is cancelled use Deactivate Status and Deactivate.

Check Balance Function

To check the balance of a voucher we highly recommend to implement a Check-Balance-Function. Display whether the voucher can be redeemed. If it is a valid voucher, then display the balance and the total amount. Use the Balance Endpoint for this case. Also add the possibility to print those information.


Idea Creation GmbH
Walchestrasse 15
8006 Zürich
Tel. +41 44 500 54 00

TeamViewer herunterladen

Social Media