Skip to main content


docs image


Get to know giftcards

EVA supports all the giftcards you could possibly ever want. We support them; we are not a giftcard provider. When first starting out, we built some dedicated integrations with certain giftcard providers. However, as we grew, we got more requests for additional integrations with more providers. In order for us to scale more easily, we built a generic giftcard integration which can be used to connect any provider we don't support.

With all giftcards and it heavily depends on the giftcard providers we are working with.

When it comes to giftcards, we make a very clear distinction between physical giftcards and digital giftcards. Physical giftcards keep stock and require a serial number, while digital giftcards are sent out via mail. This document has separate sections for physical and digital giftcards.

Additionally, we make a distinction between selling giftcards and using giftcards as a payment method. Sometimes, you maybe want to sell giftcards but not accept them for payments. Both situations require a giftcard configuration though.


In order to be able to access this chapter, you need the GiftCardConfigurations permission.

Giftcard configurations

A giftcard configuration essentially describes your giftcard using the following properties:

NameName for your giftcard.
HandlerExplained later on.
Card typeSome handlers support multiple card types.
Usage typeWhether you want to sell cards, or use them as payment.


Your handler is kind of your giftcard 'provider'. We used to have a lot of these, but the requests to add more and more handlers kept rolling in. We then killed of most of our available handlers and set up a generic giftcard implementation that can be used to connect any giftcard you want. You just have to do it yourself. This handler is called APIGIFTCARD.

Available giftcard configurations

In case you want to view the available configurations in your EVA environment, you can go to the Giftcards chapter in the Financials module in Admin Suite.

Creating configurations

Start off by clicking the '+' icon on the overview page.

  • Allow refund without transaction: Checking this will enable POS to display a button for emptying a giftcard when checking its balance (accessed through More options). Using this button will subsequently initiate the creation and checkout process for a new refund order.
  • Allow currency conversion: Checking this will allow for the giftcard to be used in OUs with a different default currency.


To use the APIGIFTCARD handler, you need to build an integration with a giftcard provider that can receive certain requests and send the correct responses. The only difference between physical and digital giftcards is that physical giftcards are 'activated' and digital giftcards are 'issued'.

If you selected the 'APIGIFTCARD' option in the creation window in Admin Suite, the window will expand to give you the needed options to connect with your giftcard handler.

Base URLThe URL that EVA will use for the various giftcard operations
UsernameThe 'username' used for the authentication at the handler
PasswordThe 'password' used for the authentication at the handler
Timeout (Seconds)The time the call is valid before timing out
Deny paying for giftcards with giftcards

You can prevent giftcards being paid for by means of giftcards, by setting GiftCards:Payment:DenyPayingForGiftCards to true. Mind that this setting is applicable only to the generic APIGIFTCARD handler.

Configuring alternative handlers

When setting up Adyen payments, many of the configurations for the Adyen SVS giftcard are already established.

AdyenStoredValue:ApiUrlThis is the URL required for the activation of giftcards.

The use of these settings assumes that you will be using the CheckoutAPI for refunds and captures. However, you can read more about the basic Adyen integration and the CheckoutAPI in the following docs: Payments using Adyen

Accepting giftcards as payment

To start, make sure there is a giftcard configuration in place that allows for payments (usage type 'Payment'). This can be done in Admin Suite through the Financials module, in the Payment methods chapter.

When you have that in place, we can create the following payment method under the Giftcard Payment Type:

Under Options, we can slightly customize our payment method. Just make sure to select your previously configured giftcard configuration from the Giftcard configuration dropdown list.

The Organization unit settings card lets you fine-tune the use of this payment method across your OUs.


When using the Adyen SVS giftcard, the payment will run via the Adyen payment methods, such as Adyen_CheckoutAPI_Giftcard

The giftcard payment option is available in the Companion App, POS and Checkout App.

Selling giftcards

In order to sell giftcards, we have to upload/import a giftcard product. Usually we import products using our ImportProducts service, but for giftcards, we can easily create a manual request. We have some examples ready for you under Creating Giftcards.

As we yet to have any method to link products to a giftcard configuration in ImportProducts, these imports will automatically generate their own giftcard configuration. Check up after importing to set the right configurations. This can be done in Admin Suite through the Financials module, in the Giftcards chapter.

To sell giftcards, you have to upload/import giftcard product(s) (this is done through the same aforementioned chapter). Here, you can link the product(s) to their respective giftcard configuration, where the Usage Type is set i.e. not on the product itself.

Refunding giftcards

Refunding giftcards is a straightforward process when you have a receipt or the original order, see here. Whether or not the card is refundable depends on the giftcard provider's business rules.

To initiate the refund process for giftcards, whether you have a receipt or the original order, you can create a return order. The simplest approach is to find the original order and create a directly.

If a physical giftcard is without a receipt or original order, you can scan or enter the serial number of the giftcard to create the return order.

Since physical giftcards are activated when they are shipped or or handed over to the customer, you can deactivate them once they've been returned. However, deactivation is no longer possible after the card has been used.

If you need to set up a refund process for digital giftcards without a receipt or the original order, there are a few additional steps to consider. If you're selling digital giftcards in a country that mandates refunds without requiring a receipt or the original order, see the steps in Refunding a digital giftcard.

Emptying giftcards on payment

EVA let you define a threshold for when giftcards can be emptied. If we put our threshold to 100 (100 cents), anytime a card is used for a payment that would leave less than a hundred cents remaining, the card will then be emptied completely. Simply put; anytime a giftcard falls below 100 cents - it will be emptied.

You can adjust this by changing the value of the setting GiftCards:MaximumOverPaymentInCents to a desire numeric amount in cents.