Tutorial

This tutorial describes the processes that take place when a consumer reloads the value of a card using Blackhawk Digital Service. It summarizes steps taken by the consumer and processes undertaken in the background via Blackhawk Digital Services in support of the reload. It also details the services and operations involved. You can use it to help define and construct the parts of your application that enable your customers to reload the value of a card.

📘

Best Practices

For best practices refer to our Reload a Gift Card Integration Guide

📘

Note

Reload feature is only available for Open loop cards

Card Reload Process Summary

A Blackhawk distribution partner's application lets consumers reload gift cards. The consumer selects a card managed or purchased by the application and selects or enters an amount to add to the current value of the card, reloading it to a higher value. The diagram below shows the flow of a request initiated by a user to reload the value of a card.

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 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 Query Product Lines by Criteria API from Product Line Management Service based on locale and time stamp 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

Reload Card: What Happens?

1. If the user is purchasing a product for use through the application, follow Create an EGift for an application to get an account. The application uses the account's entityId to reload funds from a card created by generateEGift. Skip to Step 3.
2. 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.
3. Using the product line data from the offline processes, the user's application can display a list of available Blackhawk Network brands for selection.
4. The pinRequired field indicates if a PIN is required as input (with either a yes or no value).
5. If the value is no, the display should indicate PIN is optional.
6. Use brandLogoImage to display the brand image for a product line.
7. Use productLineDescription to display the brand description.
8. Use defaultProductImages to display visual images of the back of card to identify the card number and pin.
9. Use Reload Characteristics isReloadable, which indicates if a brand supports reload.
   1. If the brand supports reload, then use minReloadAmount and maxReloadAmount.
10. The user selects one of the brands and provides the required card information, such as its number and PIN.
11. The application calls the Verify Account API from the Account Processing services passing the product line entityId (from the cached offline process) to productLineId, 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.
12. Once the application stores the account of the card, the user can use the application to reload the card.
13. The application calls Reload Value API from Account Processing services using the following:
14. The entityId from the account.
15. The amount to redeem (which goes to amount).
16. The unique 12-digit retrieval reference number (which goes to retrievalReferenceNumber).
17. The unique GUID (which goes to requestId).
18. Currency from the account (which goes to currency).
19. The application checks the Reload Account response to know how about was approved (approvedAmount) and the resulting balance (resultingBalance).
20. If the Reload Account does not return a response:
21. Call the Reload Account with the same parameters from Step 5 above at least three times over period of time.
22. Set previousAttempts to 1 and for each subsequent call of Reload Account increment by 1, so the next value is 2.
23. If Reload Account is not responding contact Blackhawk Customer Service.
24. If the Reload Account returns a timeout:
25. Call reverseTransaction from the Acccount Processing service and map the requestId from Step 3 to reversalTxnRequestId.

📘

Note: the reverseTransaction operation is timebound and usually can be called after a certain timeframe. The reverseTransaction API should not be confused with voidAccount. reverseTransaction is to be used only for system exceptions.

Reload a Card Process Flow

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