Skip to main content

Digital giftcards

Digital giftcards differ from regular giftcards in that they don't require an actual giftcard 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 giftcards​

Because we have to show a different product detail page when we're dealing with digital giftcards, 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 giftcard. 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 giftcard like any other giftcard.

Digital giftcard flow​

Add to order​

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

In order to add a simple digital giftcard 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 giftcards for our order. This array also contains the GiftCardID (Result.[*].Identifiers.GiftCardID) for every giftcard, 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 giftcard 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 giftcard 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 giftcard will be sent out.

Giftcard 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 giftcards 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 giftcard without an original transaction​

In some countries, digital giftcards 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 giftcard with an electronic element to it is deemed a digital giftcard. 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 giftcard'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 giftcard 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 giftcard notes
  • AddDigitalGiftCardToOrder does not support giftcards with a set price; Amount should be forbidden when the giftcard 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 giftcards, GetDigitalGiftcardsForOrder only returns the GiftCardID for the first giftcard.