eGift Issuance

Introduction

This tutorial describes the processes that take place when a consumer purchases an eGift using Blackhawk Network Digital Services. It summarizes steps that need to be taken by a partner application to support the purchase of an eGift product and details the operations that provide the functionality enabling the sale and purchase of an eGift. You can use it to help define and construct the parts of your application that provide eGift functionality to your customers.

Process Summary

A Blackhawk Network distribution partner's application provides a list of available eGifts for purchase as defined by the partner product catalog. A consumer using the application selects a product, provides payment for the eGift, and purchases it. After completing the purchase the user has the options of viewing the eGift in the partner's application, sending the egift to a recipient via some channel like email or SMS, or storing the eGift in a digital wallet (or some other “bag”) managed by Blackhawk Network.

Offline Processes

  1. The partner application calls the Query All Product Catalogs API from the Product Catalog Management Service and receives a response containing a list of product catalog IDs.
  2. The application calls Read Product Catalog API from the Product Catalog Management Service for all product IDs returned from Step 1 and receives a response containing a list of product IDs.
  3. The application calls Read Product from the Product Management Service for every productId provided by the response in Step 2. The response includes product information for each productId, such as product image, terms and conditions, activation instructions, product description, and so on, which is cached by the application in order to display the list of products for sale.
  4. If the application displays brand information, it calls Read Product Line from the Product Line Management Service with the productLineId associated to every product in the product catalog, which is cached by the application in order to display the list of available brands.

📘

Offline Processes

Offline process refers to a process used by a client application to execute a set of API calls that retrieve all brand and product metadata. Learn More

Create eGift - What Happens?

  1. The user opens the application, either on the desktop or on a mobile device, and navigates to the list of products available for purchase. The application uses the cached data from the offline processes (Steps 3 and 4, above) to display brand and product information.

  2. The user selects a product to purchase and goes through partner’s payment process.

📘

Blackhawk Network doesn't require a user to be notified to review/accept terms and conditions.

  1. The application calls generateEGift from the EGift Processing Service, which has the following results:

    1. Maps a unique value to the requestId.
    2. eGift amount is sent to giftAmount.
    3. The cached product configurationId is sent to productConfigurationId.
    4. A unique 12-digit value is sent to retrievalReferenceNumber (to be used for reconciliation on the Settlement Detail file). If no value is supplied, one is automatically generated by the service
    5. Optionally the application can map giftFrom, giftTo, giftMessage, purchaserId, and recipientId.
  2. If the generateEGift does not return a response, do the following:

    1. Call reverseEGift mapping the requestId from Step 3 to reversalEGiftRequestId.
    2. Call generateEGift with the same parameters from Step 3 above at least three times over a period of time using a unique requestId for each call.
    3. For each attempt if the generateEGift call does not return a response, then call reverseEGift mapping the requestId from Step 3 to reversalEGiftRequestId.
    4. If reverseEGift does not respond, contact Blackhawk Network.
  3. If generateEGift returns a 504 or 502 timeout, do the following:

    1. Call reverseEGift mapping the requestId from Step 3 to reversalEGiftRequestId.
    2. Call generateEGift with the same parameters from Step 3 above at least three times over a period of time using a unique requestId for each call.
    3. For each attempt if the generateEGift call does not return a response or responds with an HTTP status code of 504 or 502, then call reverseEGift mapping the requestId from Step 3 to reversalEGiftRequestId.
    4. If reverseEGift does not respond, contact Blackhawk Network

📘

The reverseEGift operation is time bound and usually can be called after a certain time frame. The reverseEGift API should not be confused with voidEGift and reverseEGift is to be used only for system exceptions.

  1. The application can use one of the following options to deliver an eGift purchased by the user:

    1. If the application uses the Blackhawk Network eGift Application, the application provides a Blackhawk Network URL via some channel, which the user clicks to view the eGift in a browser or mobile application.
    2. The eGift can be printed or presented directly through the application for redemption.
  2. If the application provides the redemption display, then it uses a combination of product assets and account assets associated with the eGift.

    1. The products assets can be taken from the cached offline process, Step 3
      2.In order to get the account assets the application calls Read Account from the Account Processing Service with the accountId associated with the eGift, which was returned by generateEGift
      1. The application uses the account’s accountNumber (card number and redemption code) and securityCode (PIN).
  3. If the application enables the user to save gift cards to a bag, that is a digital wallet, with other gift cards/prepaid cards, then the user can opt to save the eGift to the bag/wallet. If a bag has not been created, the application can take these steps to do so and add the card to the bag:

    1. Call Create Person from the Person Management service providing personal information about the user.
    2. Call Create Bag from the Bag Management service mapping the personID to the ownerId created in the step above.
    3. Call Read Account from the Account Processing service with the accountId associated to the eGift returned by generateEGift.
    4. The application uses the account’s accountNumber and securityCode (optional) from the above to map the eGift to the bag (the digital equivalent of putting the eGift in the bag).
    5. The application calls Update Bag
  4. If the application can send the eGift to a recipient, it does so through the preferred channel for sending the eGift to the recipient. The application can provide the BHN Redemption URL through SMS, in-app gift acceptance, email, or another delivery method.

🚧

Important

The generateEGift operation does not send the eGift.

  1. If the product sold supports void in the case that a user purchases an eGift and wants to return it, then the application can call voidEGift from the EGift Processing services.
    1. Check the cached brand information if the product can be voided. The supported feature section should have VOID_ACTIVATION.
    2. If supported, call voidEGift with the entityId of the eGift mapped to the eGiftId.
    3. Check that isVoid is set to true.

📘

Note

Offline process refers to a process used by a partner application to execute a set of API calls that retrieve all brand and product metadata. That data is cached by the partner’s application. With that data, the partner can manage the content displayed through their application and optimize the user experience for selling eGifts or managing a gift card in a digital wallet.

Blackhawk Network recommends partners retrieving product and product line information in an offline process in order to minimize the number of calls made by the application and to control when content is updated on their application


Did this page help you?