Generic gift card interface

EVA has a generic interface which can be used to integrate any gift card provider. This interface has a set of requests that will be made by EVA to a given endpoint, and corresponding expected responses. This page documents these requests and expected responses, as well as any additional important information.

In order to use the generic gift card interface, make sure to set up a gift card provider of type APIGIFTCARD. When doing so, the configuration will require and endpoint to be set. We will refer to this endpoint as baseUrl from here on out.

Endpoints

The interface knows six requests and expected responses, each of these are sent to their corresponding endpoints. Whenever any action is performed in EVA that relates to this gift card configuration, EVA will fire on or more of these requests to the given endpoint to fetch or update information from or towards the gift card provider. These endpoints are, in no particular order:

• baseurl/card-info // used to fetch information on a given gift card
• baseurl/issue // used to issue digital gift cards
• baseurl/activate // used to activate physical gift cards
• baseurl/purchase // used to make a purhcase with a gift card
• baseurl/refund // used to refund transactions on a gift card
• baseurl/cancel // used to cancel gift cards

All requests made towards these endpoints use the POST method, and contain application/json as Content-Type header. EVA expects this header to be added in the response message as well.

Transactions

All interactions, except for card-info, require a transaction to be logged. This transaction is represented by a TransactionID and TransactionData, and these properties should be returned to EVA on all responses (except, again, for the card-info response).

EVA stores these transactions and they are used on cancel and on refund. You can read more on this in the corresponding sections on this page.

Important

Make sure to structure transactions in your integration in such a sense that they can possibly apply to multiple cards, as purchases with multiple cards are supported in this interface.

The interface

/card-info

This endpoint is called whenever card information is needed in EVA.

Request sent to baseurl/card-info

{
    "CardNumber": "341956071", // string
    "Pin": "1234" // string
}

Expected response

{
    "IsSuccess": true, // boolean
    "Balance": 19.50, // number
    "CurrencyID": "EUR", // string, ISO 4217 format
    "ErrorType": 0, // number, optional, explained under 'Error logging'
    "BusinessRules": {} // object, optional, explained under 'Additional Business Rules'
}

/issue

This endpoint is called whenever a digital gift card should be issued.

Request sent to baseurl/issue

{
    "CardIdentifier": "backend_id", // string, BackendID of the gift card product that is being sold
    "CurrencyID": "EUR", // string, ISO 4217 currency id for the gift card to be issued
    "Amount": 24.50 // number, amount to load onto the card
}

Expected response

{
    "IsSuccess": true, // boolean
    "CardNumber": "341956071", // string, card number for the newly created card
    "Pin": "1234", // string, pin for the newly created card
    "Balance": 19.50, // number, balance on the newly created card (should match amount from the request)
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "TransactionDate": "2024-10-30 12:00:22", // dateTime, explained under 'Transactions'
    "ErrorType": 0, // number, optional, explained under 'Error logging'
    "BusinessRules": {} // object, optional, explained under 'Additional Business Rules'
}

/activate

This endpoint is called whenever a physical gift card should be activated. The difference between this and /issue, is that these cards should already exist, but no be activated yet. This is also why you shouldn't include the card's pin code in the response, as that should be written on the card itself.

Request sent to baseurl/activate

{
    "CardNumber": "341956071",
    "CurrencyID": "EUR",
    "Amount": 19.50 // number, amount to load onto the card
}

Expected response

{
    "IsSuccess": true, // boolean
    "Balance": 19.50, // number
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "TransactionDate": "2024-10-30 12:00:22", // dateTime, explained under 'Transactions'
    "ErrorType": 0, // number, optional, explained under 'Error logging'
    "BusinessRules": {} // object, optional, explained under 'Additional Business Rules'
}

/purchase

This endpoint is called when a card is used to make a purchase.

Request sent to baseurl/purchase

{
    "CardNumber": "432875620465", // string, card number given for the purchase
    "Pin": "2345", // string, pin code given for given card number
    "CurrencyID": "EUR", // string
    "Amount": 19.50 // number, amount to refund from associated card
}

Expected response

{
    "IsSuccess": true, // boolean
    "Balance": 0, // number, remaining balance on the card after purchase
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "TransactionDate": "2024-10-30 12:00:22", // dateTime, explained under 'Transactions'
    "ErrorType": 0 // number, optional, explained under 'Error logging'
}

/cancel

This endpoint is called when a gift card should be cancelled, for example when an order containing the sale of a gift card is returned. EVA only allows this when no other transactions have been made with the card yet. The TransactionID sent here always matches the ID for either an /activate or /issue operation, so you can just completely empty the associated gift card.

Request sent to baseurl/cancel

{
    "CardNumber": "341956071",
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" // string, explained under 'Transactions'
}

Expected response

{
    "IsSuccess": true, // boolean
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "TransactionDate": "2024-10-30 12:00:22", // dateTime, explained under 'Transactions'
    "ErrorType": 0 // number, optional, explained under 'Error logging'
}

/refund

This endpoint is called when a refund should be processed for a transaction.

Request sent to baseurl/refund

{
    "CurrencyID": "EUR", // string
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "Amount": 19.50 // number, amount to refund from associated card
}

Expected response

{
    "IsSuccess": true, // boolean
    "Balance": 0, // number, remaining balance on the card after refund
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "TransactionDate": "2024-10-30 12:00:22", // dateTime, explained under 'Transactions'
    "ErrorType": 0 // number, optional, explained under 'Error logging'
}

Error logging

Since this is a whitelabel integration interface, it makes it difficult to returns errors to EVA which you would like displayed in our frontends. To mitigate this, we provide four generic error codes you can include in your response, which trigger messages in EVA frontends.

To use these, EVA can receive two error-specific properties in every response:

• IsSuccess
• ErrorType

IsSuccess should be used when there's any error of any kind. Simply return IsSuccess: false to throw the operation.

ErrorType is used for additional details. It exprects a numeric value from 0-3 which indicate the following to EVA:

• 0 = "Unknown error"
• 1 = "Card is expired"
• 2 = "Card is not activated"
• 3 = "Insufficient balance on the card"

VERY IMPORTANT

Do NOT display any other error type besides 0 if CardNumber and Pin are an invalid combination, or you leave a gaping security hole vulnerable to brute force attacks on your gift card combinations.

Additional 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 gift card 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
IsExpired	Whether the card is expired
DateOfPurchase	DateTime of purchase
DateOfExpiration	DataTime of expiration

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
    }
}

Origin details

If known, EVA will include origin details in the requests towards your endpoints. These are simple properties to provide some context about where the operation is taking place in EVA. These properties are as follows:

Example card-info

{
    "CardNumber": "341956071", // string
    "Pin": "1234", // string
    "OrganizationUnitID": 2555, // number
    "OrganizationUnitBackendID": "STORE_1004", // string
    "StationID": 1234, // number
    "StationBackendID": "STATION_3425" // string
}

Payment using multiple cards

On your gift card configuration, there's a checkbox which, if set, will allow you to use multiple gift cards for a single payment.

In the /purchase request this will look like this:

Request send to baseurl/purchase

{
    "Payments": [
        {
            "CurrencyID": "EUR",
            "CardNumber": "25336103214568813620040172411303902001000",
            "Pin": "1234",
            "Amount": 10.00
        },
        {
            "CurrencyID": "EUR",
            "CardNumber": "2533610321456881354627071719303902002000",
            "Pin": "1234",
            "Amount": 14.50
        }
    ]
}

This will also require a slightly altered expected response:

Expected response

{
    "IsSuccess": true, // boolean
    "BalancePerCard": {
        "25336103214568813620040172411303902001000": 2.50,
        "2533610321456881354627071719303902002000": 0
    },
    "TransactionID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", // string, explained under 'Transactions'
    "TransactionDate": "2024-10-30 12:00:22", // dateTime, explained under 'Transactions'
    "ErrorType": 0 // number, optional, explained under 'Error logging'
}