Introduction

This tutorial describes the processes that take place when a consumer redeems a card using a Blackhawk issued Brand 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 redemption. It also details the services and operations involved in the redemption. You can use it to help define and construct the parts of your application that enable your customers to redeem the value of a card.

Redeem Card Process Summary

A Blackhawk issued Brand Partner's (not a Distribution Partner) application lets consumers redeem gift cards. The consumer selects a card managed or purchased through the application, provides the amount to redeem from the card, and purchases an item using the application. After completing the purchase the user can verify the remaining value of the card by getting a balance. The diagram below shows the flow of a request initiated by a user to redeem a card.

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.
4. If the application displays brand information, then there is a call to 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

Redeem card: What Happens?

1. If the user is purchasing a product for use through your application, follow the steps outlined in Create an Egift for an application to get an account. The application uses the account's entityId to redeem funds from a card created by generateEGift. Skip to Step 3.
2. If the user has a physical card, then the user opens your application, either on the desktop or on a mobile device, and navigates to the feature that lets them manage a physical card.
3. Using the product line data from the offline processes, the application can display a list of available Blackhawk Network brands for selection.
   1. The pinRequired field indicates if a PIN is required as input (with either a yes or no value).
   2. If the value is no, the display should indicate PIN is optional.
   3. Use the brandLogoImage to display the brand image for a product line.
   4. Use the productLineDescription to display the brand description.
   5. Use the defaultProductImages to display visual images of the back of card to identify the card number and PIN.
4. The user selects one of the brands and provides the required card information, such as its number and PIN.
5. The application calls the Verify Account API from the Account Processing services (V.1), passing the product line entityId to productLineId (from the results of the cached offline process), 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, or PHONE_CARD.
6. Once the application has stored the account of the card, the user can make a purchase of an item from the application.
7. The user selects an item purchases it using the stored card on the application from the step executed above.
8. The application goes through the payment process and calls Redeem Account from Account Processing services (V.1) using the following:
9. The entityId from the account
10. The amount to redeem (which goes to amount).
11. The unique 12-digit retrieval reference number (which goes to retrievalReferenceNumber).
12. The unique GUID (which goes to requestId).
13. Currency from the account (which goes to currency).
14. The application checks the Redeem Account response to see if the redemption amount was approved (approvedAmount) and to determine the resulting balance (resultingBalance).
15. If the Redeem Account does not return a response:
    1. Call the Redeem Account with the same parameters from Step 5 above at least three times over period of time.
16. Set previousAttempts to 1 and for each subsequent call of Redeem Account increment by 1, so the next value is 2.
17. If Redeem Account does not respond, contact Blackhawk Customer Service.
18. If Redeem Account returns a timeout:
19. Call reverseTransaction from the Acccount Processing services (V.1) and map the requestId from Step 3 to reversalTxnRequestId.

📘

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

Redeem a Card Process Flow

The following diagram shows the flow of a request initiated by a customer to redeem a card.