Introduction

This tutorial describes the processes that take place when a consumer performs a balance inquiry on a card using a partner’s application via Blackhawk Digital Services. It summarizes steps taken by the consumer and processes undertaken in the background via Blackhawk Digital Services in support of the balance inquiry. It also details the services and operations involved in the balance inquiry. You can use it to help define and construct the parts of your application that enable your customers to request the remaining balance on a card.

Balance Inquiry Process Summary

A Blackhawk distribution partner's application enables a consumer to perform a balance inquiry on a gift card to check its remaining balance. The consumer selects a card managed or purchased through the application and sends a request to get card balance. The diagram below shows the flow of a balance inquiry request initiated by a user.

Offline Processes

1. The partner application calls the Read 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 return from Step 1 above 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, then there is a call to Query Product Lines by Criteria API from Product Line Management Service based on locale and timestamp to get a list of available brands
5. The application calls Read Product Line from the Product Line Management Service with the productLineId returned in Step 4.

📘

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

Balance Inquiry: What Happens?

1. To enable a user to purchase a product for use through your application, follow the steps outlined in Create an Egift for an application to get an account. After a gift card is purchased, your application uses the associated account's entityId in order to perform a balance on the card.
2. If the card has not been provided to the user, the application can call Read Account from Account Processing services to get the balance on the card. This is a cached copy of the account stored on the Blackhawk server.
3. If the user has a physical card, then the user opens the application, either on the desktop or on a mobile device, and navigates to the feature that lets them manage a physical card.
4. Using the product line data from the offline processes, the application can display a list of available Blackhawk Network brands for selection. The following brand information can be displayed, but is not limited to these values:
   1. The pinRequired field indicates if a PIN is required as input (with either a yes or no value).
      1. If the value is no, the display should indicate that a PIN is optional.
   2. Use brandLogoImage to display the brand image for a product line.
   3. Use productLineDescription to display the brand description.
   4. Use defaultProductImages to display visual images of the back of card to identify the card number and PIN.
   5. The supported features indicates if in-network (PARTIAL_BALANCE_INQUIRY) and/or out-of-network (universal balance inquiry or UNIVERSAL_BALANCE_INQUIRY) is supported.
5. The user selects one of the brands and provides the required card information, such as its number and PIN.
6. The application calls the Verify Account API from the Account Processing services passing the product line entityId to productLineId from the cached offline processes, card number in the accountNumber field, and the PIN in pin. It also sets the accountType value to the type of the card – either CREDIT_CARD, GIFT_CARD, LOYALTY_CARD, and PHONE_CARD
   1. The balance will be returned by the Verify Account API call and be displayed to the user.
7. All subsequent calls to get balance after an eGift is purchased or physical card is digitized the application will use the Get Account Information API from Account Processing services. Use entityId from the account to make the call.

Make Sure the Balance Inquiry Shows Fresh Balance Information to the User

There may be occasions when a balance inquiry call does not successfully return the new balance from the processor, and the use instead sees an older balance that's been cached by the application. Blackhawk provides a way for your application to determine if a balance inquiry call has successfully returned a card's latest balance from the processor so that it can then display appropriate information to the user. Here's how to do that:

Your application calls the Get Account Information from the Account Processing Service and checks balanceAsOf and isBalanceStale to determine if the balance inquiry request was successful. Here's what they should indicate:

• balanceAsOf indicates precise date and time of the last successful balance inquiry request
• isBalanceStale sets a flag (boolean) to indicate whether the balance is "stale," that is, if the returned balance has been cached by the application, or if has been refreshed by the processor. If balance inquiry failed, it will be true, meaning that the application is using the result of a previous inquiry. If it succeeded, the flag will be set to false, meaning the balance shown is "fresh" from the processor.