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.

Card info

Used to fetch the current balance of a giftcard.

baseurl/card-info

{
    "CardNumber": "123445643",
    "Pin": "2342"
}

Response

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

Activate

Used to activate a physical giftcard when sold.

baseurl/activate

{
    "CardNumber": "123445643",
    "CurrencyID": "EUR",
    "Amount": 10.00
}

Response

{
    "IsSuccess": true,
    "Balance": 10.00,
    "TransactionID": "TR2849839789",
    "TransactionDate": "2021-10-30 12:00:22"
}

Issue

Used to generate a digital giftcard.

baseurl/issue

{
    "CardIdentifier": "MYFIRSTCARD", // BackendID of the Eva Product
    "CurrencyID": "EUR",
    "Amount": 10.00
}

Response

{
    "IsSuccess": true,
    "Balance": 10.00,
    "TransactionID": "TR2849839789",
    "TransactionDate": "2021-10-30 12:00:22",
    "CardNumber": "13898380738",
    "Pin": "1234"
}

Cancel

Used to cancel an activated/issued card.

baseurl/cancel

{
    "TransactionID": "TR2849839789",
    "CardNumber": "13898380738"
}

Response

{
    "IsSuccess": true,
    "TransactionID": "TR2849839789",
    "TransactionDate": "2021-10-30 12:00:22"
}

Purchase

Used to execute a payment with a giftcard.

baseurl/purchase

{
    "CurrencyID": "EUR",
    "CardNumber": "13898380738",
    "Amount": 10.00,
    "Pin": "1234"
}

Response

{
    "IsSuccess": true,
    "Balance": 0.00,
    "TransactionID": "TR2849839789",
    "TransactionDate": "2021-10-30 12:00:22"
}

Refund

Used to refund an executed payment.

baseurl/refund

{
    "CurrencyID": "EUR",
    "TransactionID": "TR2849839789",
    "Amount": 5.00
}

Response

{
    "IsSuccess": true,
    "Balance": 5.00,
    "TransactionID": "TR2849839789",
    "TransactionDate": "2021-10-30 12:00:22"
}

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.

Value	Usage
ActivateValueMin	Minimum activation amount (e.g. 24.95)
ActivateValueMax	Maximum activation amount
PurchaseValueMin	Minimum purchase amount
PurchaseValueMax	Maximum purchase amount
Reloadable	Whether the card is reloadable
Refundable	Whether 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
    }
}