---
updatedAt: 2025-01-31T00:37:38.000Z
agentTools:
  projectIndex: https://developers.e-guma.ch/llms.txt
---

# Integration Guide

For online Stores

## Configuration

You authenticate to the e-guma API by providing an API key in the request. Store that key in your system.

## Redeem a voucher

We recommend providing an input field for vouchers on the checkout page.

![](https://files.readme.io/f671c09-GiftVoucherCheckout.jpg "GiftVoucherCheckout.jpg")

Use the [Balance Endpoint](https://developers.e-guma.ch/docs/balance) to verify the entered voucher. The [Balance Endpoint](https://developers.e-guma.ch/docs/balance) 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](https://developers.e-guma.ch/docs/voucher2mobile-shortcode), which is only temporarily available.

If the field *is\_redeemable* is set to false, show an appropriate message. **Don't use the returned*message* field**.\
If the voucher is fine, you can determine the amount which has to be redeemed. The user doesn't have to enter the amount. The amount can be calculated like that: *min(remaining\_amount\_to\_pay, voucher\_balance)*. In order to redeem the voucher, call the [Redeem Endpoint](https://developers.e-guma.ch/docs/redeem)  with the calculated amount. An optional reference number can also be transmitted, which we will save and display on our side. Save the voucher code and the *redeem\_token* in your database.

## Cancelling the redeemed voucher

If the order has to be canceled, then you also need to cancel the redemption. Use the [Cancel Request](https://developers.e-guma.ch/docs/cancel-redemption) with the **redeemed code and amount** for that case.

## VAT

If you redeem a voucher don't reduce the VAT. Vouchers are not discount- / promo-codes.