Skip to main content

Generic giftcard interface

EVA has a generic interface which can be used to integrate giftcard providers. This involves a set of default requests and responses that need to be accounted for in the integration.

The identifier used for this giftcard method is APIGIFTCARD.

Note

Before starting to work on this integration, make sure to have a valid giftcard configuration for APIGIFTCARD.

EVA will call different endpoints for different operations, all calls are PUSH and contain application/json in the request headers. They also expect application/json in the response headers. Below is a list of requests that will be sent out by EVA, and the responses that are expected.

Used to fetch the current balance of a giftcard.

baseurl/card-info
{
    "CardNumber": "123445643",
    "Pin": "2342"
}

Response
{
    "IsSuccess": true,
    "Balance": 10.00,
    "CurrencyID": "EUR"
}

Business rules​

It is possible to include certain business rules in your integration. Business rules allow you to specify what EVA should expect from the giftcard provider - although this does not necessarily mean this is what the provider actually offers. These are entirely optional and can remain undefined, but that benefits from a little more explanation.

  • If you keep one of the Value settings undefined, EVA will simply try with the consumer's specified amount, and whether it will be successful or not is outside of EVA's control.
  • The same goes for Reloadable: you could set true here, but if the provider does not actually provide it, the action will fail still. If you however set it to false, you won't be able to initiate it regardless of the provider's situation.
ValueUsage
ActivateValueMinMinimum activation amount (e.g. 24.95)
ActivateValueMaxMaximum activation amount
PurchaseValueMinMinimum purchase amount
PurchaseValueMaxMaximum purchase amount
ReloadableWhether the card is reloadable
RefundableWhether the card is refundable

To make these business rules known, add the rules in the card-info response like so:

baseurl/card-info response
{
    "IsSuccess": true,
    "Balance": 10.00,
    "CurrencyID": "EUR",
    "BusinessRules": {
        "ActivateValueMin": 24.95
    }
}

Accepting multiple gift cards in one Payment​

EVA is capable of accepting multiple gift cards for a single transaction out of the box.

To facilitate this, use the property AllowMultipleCardsPayment in the CreateGiftCardConfiguration service call.

The CreatePayment service in turn will insert the all the cards’ payment details in the Properties property, like so:

Sample

["CardPayments"] = new JArray
        {
          JToken.FromObject(new CardPaymentDetails()
          {
            CardNumber = serialNumber1,
            Amount = 10,
          }),
          JToken.FromObject(new CardPaymentDetails()
          {
            CardNumber = serialNumber2,
            Amount = 5
          })
        }

Keep in mind that the external API must handle the /Purchase call in such a way, that it can handle the list of CardPayments on this new property (instead of via just 1 card in CardNumber and its Amount).