Integration Guide

For POS and Access Systems


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/qr code which identifies the voucher. The human readable code has 2 dashes to group the digits - eg. L4FU-5LQT-KJR3. However, the barcode/qr code 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 o. It’s important that the virtual keyboard provides numbers, letters, dot and dash. On mobile devices, it should be possible to scan and read the QR code of a voucher with the device's camera. Use the Balance Endpoint to verify the entered voucher code 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)

When the order gets submitted, call the Redeem Endpoint with the calculated amount for each voucher. Save each voucher code and the redeem_token in your database. Finally, print the voucher codes 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.

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 Activate.

The user clicks on an item (e.g. "Gift Voucher") on the POS. A window appears where the user can enter the voucher code (by scanner or a virtual keyboard) and confirms it. On mobile devices, it should be possible to scan and read the QR code of a voucher with the device's camera. 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 canceled use Deactivate Status and Deactivate.

Charge a voucher

A voucher can be topped up with any amount multiple times. To check whether a voucher can be charged, use Charge Status. If can_be_charged of the response is true, the voucher is valid to be charged. Call
Charge with the provided amount.

To cancel the recharge of a voucher, call the endpoint Cancel Charge

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.