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.
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 temporarily 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 and the redeem_token in your database. Finally, print the voucher code and the new balance 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.
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 Activate.
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.
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.
Updated 4 months ago