Integration Guide

Configuration

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 implemented like any other payment method.

Enter Voucher Code
If the voucher payment button is clicked, the user can enter the voucher code. On each voucher is a code and barcode/qr code which identifies the voucher. The human readable code has 2 dashes to group the digits - e.g. 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. 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 the is_redeemable field. The Balance Endpoint also returns the voucher code. It’s 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)

Redeem
When the order gets submitted, call the Redeem Endpoint with the calculated amount for each voucher. An optional reference number can also be transmitted, which we will save and display on our side. 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 redeem token and amount.

Issue a Depot Voucher

A depot voucher is 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.

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 you will see if the depot voucher can be activated. The response also contains the financial amount of the voucher. There is another flag the Activate Status returns, free_amount. If free_amount is set to true, the e-guma API doesn't return an amount. Your system must provide an input field where the user enters the balance of the voucher. 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.

Deactivate
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 given amount. 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.

Displaying the balance of a voucher

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.

To enable a user the ability to check the balance of a voucher, a simple way to enter a voucher code must be provided. Use the Balance Endpoint to get the necessary data. Display the current balance of the voucher to the user.