Skip to main content

Digital gift cards

Digital gift cards differ from regular gift cards in that they don't require an actual gift card to be shipped, they are sent out through e-mail or a plain old link, and they can be heavily customized to the customer's liking. Customization options include personal messages, images and even videos.

Recognizing digital gift cards​

Because we have to show a different product detail page when we're dealing with digital gift cards, we have to check the product type from the GetProductDetailResponse. If the product type includes both GiftCard and VirtualProduct, we know we're dealing with a digital gift card. If this is the case, there's several customization options we can display, all of which will be covered later on. For now, we will treat this digital gift card like any other gift card.

Digital gift card flow​

Add to order​

Because digital gift cards offer extended customization, we provide a heavily adjusted variation on AddProductToOrder; AddDigitalGiftCardToOrder.

In order to add a simple digital gift card to an order, we can keep the request very straightforward.

AddDigitalGiftCardToOrder
{
    "Amount": DigitalGiftCardAmount,
    "OrderID": OrderID,
    "ProductID": DigitalGiftCardProductID,
    "Data": {}
}

This will return an empty response if successful.

Checkout​

Now perform checkout like you would normally.

After checkout (delivery)​

After checkout, we call GetDigitalGiftCardsForOrder which responds with an array of gift cards for our order. This array also contains the GiftCardID (Result.[*].Identifiers.GiftCardID) for every gift card, we need this for concurrent requests.

Note

The GiftCardID is only generated after checkout.

Using this GiftCardID, we can call GetDigitalGiftCardOptions with the following payload;

{
    "OrderID": YourOrderID,
    "GiftCardID": "YourGiftCardID"
}

Which responds as follows;

{
    "CanBeUpdated": true,
    "AvailableCommunicationOptions": 1
}
  • CanBeUpdated speaks for itself, will be false when the gift card has been sent out.
  • AvailableCommunicationOptions; 1 is e-mail, 2 is SMS, 3 is both.

For this example, we will assume you want to send the gift card out through e-mail. In order for this to be possible, CanBeUpdated should be true and AvailableCommunicationOptions should include 1.

If this is the case, we can render two e-mail fields:

  • Sent from
  • Send to

Whatever the user enters in these fields should be passed in UpdateDigitalGiftCardOptions like so;

{
    "OrderID": YourOrderID,
    "GiftCardID": "YourGiftCardID",
    "FromEmailAddress": "From",
    "ToEmailAddress": "To"
}

After this has been updated, the gift card will be sent out.

Gift card delivery​

When the e-mail is sent out, EVA triggers the DigitalGiftCardMessage stencil.

Schedule e-mail​

It is possible to schedule the e-mail in case of birthdays for example. To schedule the e-mail rather than sending it out immediately, we have to add some options to UpdateDigitalGiftCardOptions like so;

{
    "OrderID": YourOrderID,
    "GiftCardID": "YourGiftCardID",
    "FromEmailAddress": "From",
    "ToEmailAddress": "To",
    "DeliverySchedule": "2022-12-08T13:28:00.000Z"
}

We expect the delivery schedule time in UTC.

Add content​

It is also possible to customize digital gift cards with some content. This content should be passed in the initial AddDigitalGiftCardToOrder request. This content can be used in the DigitalGiftCardMessage and DownloadDigitalGiftCard stencils (mail and pdf respectively).

Message​

We can include a message with a From and To.

AddDigitalGiftCardToOrder
{
    "Amount": DigitalGiftCardAmount,
    "OrderID": OrderID,
    "ProductID": DigitalGiftCardProductID,
    "Data": {
        "From": "Pete",
        "To": "Gina",
        "Text": "Sorry I ate all your Zucchini's, I really didn't mean to."
    }
}

Visuals​

We can also include an image or a video.

AddDigitalGiftCardToOrder
{
    "Amount": DigitalGiftCardAmount,
    "OrderID": OrderID,
    "ProductID": DigitalGiftCardProductID,
    "Data": {
        "Theme": {
            "VideoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&ab",
            "ImageUrl": "https://media3.giphy.com/media/Nx0rz3jtxtEre/giphy.gif?cid=ecf05e4750gbxsczhzwkn2jje6ykv3y5z66rptni9cnfblql&rid=giphy.gif&ct=g"
        }
    }
}

Refunding a digital gift card without an original transaction​

In some countries, digital gift cards have to be refunded at sight. This means they need to be refundable even when the customer doesn't have a receipt, and there's no original order/transaction present in EVA.

Any gift card with an electronic element to it is deemed a digital gift card. This includes being able to be used online, but also just having a chip, magnetic stripe, barcode or anything that makes it available for electronic entry. Any such card needs to be refundable up to one year after expiration of the gift card's validity period.

Since EVA can only refund if it's attached to an order, the following flow needs to be implemented to create orders specifically for a refund. All front-ends are capable of this.

Our GiftCardConfiguration services include the AllowRefundWithoutTransaction property, which will have to be enabled.

The CardBalanceCheck in turn will return CanRefundWithoutTransaction, which if true will allow for calling EmptyGiftCard with the GiftCardConfigurationID and CardNumber. Doing so will lead to the creation of a new order containing a gift card payment.

This newly created order can then be used to refund the customer and print a regular receipt - allowing you to comply with regulations.

General digital gift card notes
  • AddDigitalGiftCardToOrder does not support gift cards with a set price; Amount should be forbidden when the gift card does not have the AllowCustomPricing property. It should just take the price into account.
  • ToEmailAddress and FromEmailAddress do not work on AddDigitalGiftCardToOrder. These only work after checkout on EditDigitalGiftCardOptions.
  • On orders with multiple digital gift cards, GetDigitalGiftCardsForOrder only returns the GiftCardID for the first gift card.